> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Translate Clips

> Deliver clips in one language through the API, even when the source video mixes languages.

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](https://docs.overlap.ai/nodes/translate.md) 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:

1. Open [portal.overlap.ai](https://portal.overlap.ai), go to **Workflows**, and open the workflow you trigger through the API.

2. Add a **Translate** node and connect it after your styling nodes, as the last editing step before any export or posting nodes. For example:

   ```text theme={null}
   Trigger → Find Clips → Style Video → Translate
   Trigger → Reframe → Subtitles → Title Overlay → Translate
   ```

3. 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).

4. 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.

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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-overlay) |
| `title` and `bio` | Not translated; `title` gets the language added, for example `(Spanish)` |

***

## 2. Trigger the workflow

Trigger it with [`POST /trigger-template`](https://docs.overlap.ai/api-reference/trigger) 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`:

```bash theme={null}
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`](https://docs.overlap.ai/api-reference/workflows#get-workflow) lists each node's `id` and `nodeType`.

```json theme={null}
{
  "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}`](https://docs.overlap.ai/api-reference/results) 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)`. |

```json theme={null}
{
  "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`](https://docs.overlap.ai/api-reference/update-clip) and [`/render`](https://docs.overlap.ai/api-reference/render) with the translated clip's `id`. The rendered video has the translated captions burned in, with the styling from the workflow.

```json theme={null}
{
  "companyId": "your-company-id",
  "clipId": "clip-123__es"
}
```

> [!NOTE]
>
> Caption **text** of a translated clip is edited in the Overlap editor. The
> [clip transcript](https://docs.overlap.ai/api-reference/clip-transcript.md) 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:

```json theme={null}
{
  "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`](https://docs.overlap.ai/api-reference/node-config-overrides#style_video).

With a Title Overlay node, you can also update `titleConfig` on the translated clip with [`/update-clip`](https://docs.overlap.ai/api-reference/update-clip) before calling `/render`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.