Skip to main content
POST
Create a new translation order for your uploaded video projects. This endpoint allows you to request specific translation services such as closed captions, subtitles, dubbing, and more.

Authorizations

This endpoint requires API key authentication. Include your API key in the request header:
  • Header name: X-Api-Key
  • Header value: Your API key from the Ollang dashboard
  • Format: X-Api-Key: your-api-key-here
You can obtain your API key from your Ollang dashboard.

Body Parameters

string
required
Type of the order. Available options: - cc - Closed captions - subtitle - Subtitles - aiDubbing - AI Dubbing - studioDubbing - Studio-produced dubbing - document - Document translation (including Image to Image when the source is a JPEG, JPG, or PNG from Direct Upload)
number
required
Service level for the order. Level 0 means full AI generated and Level 1 is Human Review added version.
string
required
Unique identifier of the project this order belongs to. This should be a project ID from a previous video upload.
array
required
Array of target language configurations. At least one target language configuration is required.
string
Subtype of the order, specific to closed captions or transcription types. Must be one of: closedCaption or timecodedTranscription. For cc and subtitle orders it defaults to closedCaption when omitted.
string
Style of dubbing for audio orders. Must be one of: overdub, lipsync, or audioDescription. For aiDubbing and studioDubbing orders it defaults to lipsync when omitted; other order types ignore it.
string
Optional URL to receive a POST request when the order completes. Must be an https URL on a public host: http URLs, localhost, private or link-local IP addresses, and .local / .internal hostnames are rejected with 400. The callback payload includes the completed order’s translated content (documents, subtitle files, etc.) so you can process results immediately without a separate API call. See Order completion callback.
string
Optional https URL (same rules as callbackUrl) to receive a POST when the AI output for an order is ready — for Human Review (level: 1) orders, before the human review starts. See AI results ready callback.
string
Optional https URL (same rules as callbackUrl) to receive progress updates while a reviewer edits a Human Review (level: 1) order’s subtitles or dubbing. See Human review progress callback.
boolean
When set to true, a QC evaluation will automatically run after the AI order completes. Defaults to false. Auto-QC only applies to top-level orders (child orders created as part of a parent order are excluded).
string[]
Optional array of translation memory ids to apply to the created orders (maximum 20, no duplicates). Each id must be a memory owned by your account — get ids from List Memories or Create Memory. Stored translation units are matched per target language at translation time. Only document, subtitle/cc, and Adobe AE orders consume memories; other order types ignore this field.

Order completion callback

When callbackUrl is provided, Ollang sends a POST request to that URL after the order reaches a completed state. The request uses Content-Type: application/json. Delivery is best-effort:
  • One attempt, 10-second timeout, no retry. If your endpoint is down, slow, or returns an error, the callback is not sent again. Keep polling Get Order by ID (or Get Orders) as a safety net.
  • Unsigned. Requests carry no signature header, so anyone who knows the URL can call it. Treat the body as a notification and confirm status and outputs with Get Order by ID before acting on it.
  • Can repeat. An order that completes again — for example after a revision — sends another callback, so handle callbacks idempotently.
  • Public https hosts only. The URL is checked again at send time; a host that resolves to a private address is skipped.
Callback failures do not affect the order itself.

Callback payload

The callback POST body includes the completed order’s translated content, with document objects shaped like those in the Get Order by ID response:

Example callback payload

AI results ready callback

When aiResultsReadyCallbackUrl is provided, Ollang sends a POST to it when the order’s AI output is ready. For Human Review (level: 1) orders this arrives before the human review starts, so you can use the AI output early. Once a delivery succeeds (2xx) it is not sent again for that order. Delivery rules otherwise match the completion callback: 10-second timeout, no scheduled retry, unsigned, public https hosts only.

Human review progress callback

When humanReviewProgressCallbackUrl is provided on a Human Review (level: 1) order, Ollang sends a POST as a reviewer edits the order’s subtitles or dubbing. Updates are sent when progress crosses each 5% step (5%, 10%, 15%, …), not for every edit. Delivery rules match the other callbacks: 10-second timeout, no scheduled retry, unsigned, public https hosts only.

Response

The endpoint returns an array with one object per order the request created. Each object has the orderId and its orderType. The array is not guaranteed to have one entry per targetLanguageConfigs item, or to follow the order you supplied them in. Some order types also create the prerequisite orders they build on in the same request (for example, AI dubbing builds on closed-caption and subtitle orders), so the array can contain more entries than target languages. Pick the orders you need by orderType, and call Get Order by ID on each to read its targetLanguage rather than relying on array position.
array
Array of orders created by the request, in no guaranteed order.