Skip to navigation
Synthesia API referenceLocalization

Create a localization from a media URL

Start localizing a video from a URL. Poll GET /localizations/{localization_id} until done is true.

Required scope: localization:write (in Studio: Localization (write))

Authentication

AuthorizationBearer

Your Synthesia API key.

  • Send it as Authorization: Bearer <key>; a bare key also works.
  • An endpoint that needs a scope names it in its description; Scopes lists them all.
  • A :write scope also satisfies the same resource’s :read.
  • Without the scope, the request fails with a 403 insufficient_scope.

Request

This endpoint expects an object.
mediaUrlstringRequired1-8192 characters

A presigned S3 HTTPS URL for the video to localize, with the bucket in the host (https://<bucket>.s3.<region>.amazonaws.com/...). Other URLs are not supported yet.

titlestringRequired1-256 characters
The title of the localized video.
sourceLanguagestringRequired>=1 character

The language spoken in the video, from GET /localizations/languages?supports=dubbing_source, or auto to detect it.

targetLanguageslist of stringsRequired

The languages to localize into, from GET /localizations/languages?supports=dubbing_target. Each language once.

lipsyncEnabledbooleanOptionalDefaults to true

Whether to lip-sync the localized videos. Lip-sync costs extra credit and needs a plan that includes it: without it, adding locales is refused, and a new localization fails once processed.

burnedInCaptionsEnabledbooleanOptionalDefaults to false
Whether to burn captions into the localized videos.
videoDurationenumOptional

adaptive adjusts the video’s speed to fit the translation; original keeps the source’s duration.

Allowed values:
visibilityenumOptional
Who can view the localized videos.
Allowed values:

Response headers

Request-IdstringOptional
The id of this request's audit record. Quote it when reporting a problem.

Response

Successful Response
idstring

The localization id, prefixed l10n_….

statusenum

queued while the source video is fetched, processing once localization starts, then completed or failed.

Allowed values:
errorobject or null

Why the localization failed. Branch on its code: moderation or processing_error. More codes may be added. Null unless the status is failed.

createdAtdatetime or null
Null until the source video is imported.
donebooleanRead-only

True once status is terminal, whatever the outcome. Poll until it is true, then read status.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
413
Content Too Large Error
415
Unsupported Media Type Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error