Translate Clips

By default, captions follow the language being spoken. A clip that switches between English and Spanish gets English captions for the English parts and Spanish captions for the Spanish parts, and which language wins where the speaker switches can vary from run to run. To deliver every clip in one language, add a Translate node to the workflow you trigger. Translate captions the whole clip in the language you choose, including the parts already spoken in it, and can optionally dub the voice.

1. Add Translate to your workflow

The API can change a Translate node’s settings on every request, but it cannot add the node. Add it once in the Overlap portal:

Open portal.overlap.ai, go to Workflows, and open the workflow you trigger through the API.
Add a Translate node and connect it after your styling nodes, as the last editing step before any export or posting nodes. For example:
Trigger → Find Clips → Style Video → Translate Trigger → Reframe → Subtitles → Title Overlay → Translate
In the Translate node, set:
- Dubbing level: Subtitles only translates the captions and keeps the original audio. Subtitles + Voice also replaces the audio with a dubbed voice.
- Target language: the language clips are delivered in by default, for example Spanish. A request can change it (step 2).
Save the workflow. Its workflowId does not change.

The translated clip keeps the subtitle style, title overlay, and other edits of the clip it was made from, which is why Translate goes after them.

Translate changes the language of the captions your workflow adds; it does not add captions. The workflow needs a Subtitles node or a Style Video node with a subtitles layer before Translate. Without one, rendered clips have no captions in any language.

Translate runs on every trigger of a workflow that contains it. For videos that should keep their spoken language, trigger a second workflow without Translate.

What comes out in the target language

Part of the clip	With Translate
Captions	Target language for the whole clip, including parts already spoken in it (requires a Subtitles or Style Video subtitles step)
Audio	Original audio with Subtitles only; dubbed in the target language with Subtitles + Voice
Title overlay text	Not translated. See Title overlay
`title` and `bio`	Not translated; `title` gets the language added, for example `(Spanish)`

2. Trigger the workflow

Trigger it with POST /trigger-template as usual. Clips come back in the language saved on the Translate node. To choose the language or dubbing level per request, add nodeConfigs.add_languages:

curl -X POST "https://api.joinoverlap.com/trigger-template" \
     -H "Authorization: Bearer $OVERLAP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "companyId": "'"$OVERLAP_COMPANY_ID"'",
           "workflowId": "'"$OVERLAP_WORKFLOW_ID"'",
           "url": "https://example.com/source-video.mp4",
           "nodeConfigs": {
             "add_languages": {
               "target_languages": ["es"],
               "dub_level": "subtitles_only"
             }
           }
         }'

Both fields are optional; a field you leave out keeps the value saved on the node. If the workflow has no Translate node, add_languages is ignored and clips come back in their spoken language.

Field	Values
`target_languages`	One language code: `es`, `fr`, `de`, `pt`, `it`, `hi`, `ja`, `ko`, `zh`, or `ar`. Codes are case-insensitive.
`dub_level`	`subtitles_only` (translated captions, original audio) or `voice` (translated captions and a dubbed voice).

Invalid values, such as an unknown dub_level, return INVALID_NODE_CONFIG.

More than one language

Each Translate node produces one language. For several languages per run, add one Translate node per language, each connected to the same upstream node. A request keyed by add_languages changes only the first Translate node, so to change a specific one, key the override by its node id. GET /workflow lists each node’s id and nodeType.

{
  "nodeConfigs": {
    "4f1c9a2e-translate-spanish-node-id": { "target_languages": ["es"] },
    "9b7d3e10-translate-french-node-id": { "target_languages": ["fr"] }
  }
}

3. Get the results

Poll GET /workflow-results/{triggerId} as usual. Translation adds roughly one to a few minutes per clip. Runs through Translate return only the translated clips. Each one has:

Field	Description
`id`	The translated clip’s own id: the original clip id followed by `__` and the language, for example `clip-123__es`. Use this id for every later call.
`variantLanguage`	The language the clip is delivered in, for example `es`.
`baseClipId`	The id of the original clip the translation was made from.
`title`	The original title followed by the language, for example `Product Launch Highlights (Spanish)`.

{
  "status": "Completed",
  "clips": [
    {
      "id": "clip-123__es",
      "baseClipId": "clip-123",
      "variantLanguage": "es",
      "title": "Product Launch Highlights (Spanish)",
      "aspectRatio": "9:16",
      "duration": 42.1
    }
  ]
}

If a clip cannot be translated, it is left out of clips instead of being returned in the original language.

4. Update and render

Call /update-clip and /render with the translated clip’s id. The rendered video has the translated captions burned in, with the styling from the workflow.

{
  "companyId": "your-company-id",
  "clipId": "clip-123__es"
}

Caption text of a translated clip is edited in the Overlap editor. The clip transcript endpoints edit the original spoken-language transcript, which does not change the translated captions.

Title overlay

Translate does not translate the title overlay. To show the overlay in the target language, send the text yourself. When the workflow uses a Title Overlay node, send the text with the trigger request:

{
  "companyId": "your-company-id",
  "workflowId": "your-workflow-id",
  "url": "https://example.com/source-video.mp4",
  "titleConfig": {
    "generateTitle": false,
    "text": "Lanzamiento del producto: lo más destacado"
  },
  "nodeConfigs": {
    "add_languages": { "target_languages": ["es"] }
  }
}

When the workflow uses Style Video, set the text on its title layer with nodeConfigs.style_video. With a Title Overlay node, you can also update titleConfig on the translated clip with /update-clip before calling /render.

Workflows

Clips

Brand Assets

Posts & Analytics

Errors

1. Add Translate to your workflow

What comes out in the target language

2. Trigger the workflow

More than one language

3. Get the results

4. Update and render

Title overlay

​1. Add Translate to your workflow

​What comes out in the target language

​2. Trigger the workflow

​More than one language

​3. Get the results

​4. Update and render

​Title overlay

1. Add Translate to your workflow

What comes out in the target language

2. Trigger the workflow

More than one language

3. Get the results

4. Update and render

Title overlay