---
title: "Translate captions"
method: POST
path: "/videos/{videoId}/captions"
tags: ["Transcripts"]
---

# Translate captions

`POST /videos/{videoId}/captions`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/videos/{videoId}/captions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Creates one caption translation job per target language. Jobs appear with the `captions_` prefix in the video job list. Required scope: `dubs:write`.

## Path parameters

- `videoId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- TranslateCaptionsRequest
  - `languages` LanguageCode[], required: Unique caption translation targets.
  - `reservationId` string: Optional credit reservation to consume.
  - `reservationLineItemIdByLanguage` object: Reservation line-item IDs keyed by requested language.

## Response `202`

Translation jobs queued.

- TranslateCaptionsResponse
  - `jobs` Job[], required: One queued caption job per language.
    - `id` string, required: Deterministic, pollable job ID.
    - `type` 'import' | 'transcript' | 'dub' | 'captions' | 'shorts' | 'thumbnail' | 'packaging' | 'download' | 'music', required: Product workflow represented by the job.
    - `status` 'queued' | 'processing' | 'ready' | 'failed', required: Normalized lifecycle shared by jobs and video projections: `queued` is waiting to start, `processing` is running, `ready` completed successfully, and `failed` reached a terminal error.
    - `videoId` string: Parent video when applicable.
    - `language` string: ISO-style language or locale code accepted by the underlying product.
    - `product` 'plus' | 'premium': Dubbing voice product: - `plus` — expressive multilingual dubbing using a Braiv voice. - `premium` — dubbing with a cloned voice created from each speaker's source samples.
    - `automationType` 'generateTitle' | 'generateDescription' | 'zeroPromptThumbnail': Packaging automation when type is packaging.
    - `result` object: Type-specific ready-state artifacts.
    - `error` JobError
      - `code` string, required: Machine-readable job failure code.
      - `message` string, required: Human-readable job failure explanation.
    - `details` object: Type-specific identifiers and context.

## Other responses

- `400`: Request fields are missing, malformed, out of bounds, or mutually inconsistent.
- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `404`: The resource does not exist or is not accessible to the caller.
- `409`: The Idempotency-Key was reused with a different path or request body.
- `429`: The account has insufficient credits, or the request exceeded a rate limit.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)