Skip to content
Braiv Docs

Translate captions

POST
/videos/{videoId}/captions
 
curl --request POST \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/captions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: import-launch-demo-20260901' \
  --data '{ "languages": [ "es", "fr" ], "reservationId": "rsv_01JZ9A", "reservationLineItemIdByLanguage": { "es": "li_01", "fr": "li_02" } }'

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

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
videoId
required
string
>= 1 characters

Braiv library video document ID.

Example 
vid_01JZ8M6A

Header Parameters

Section titled “Header Parameters ”
Idempotency-Key
string
>= 1 characters

Caller-generated key for safe POST retries. The API retains the first JSON response for 24 hours. Reusing a key with another path or body returns 409 IDEMPOTENCY_REPLAY.

Example 
import-launch-demo-20260901

Request Body required

Section titled “Request Body required ”
Media type application/json
object
languages
required

Unique caption translation targets.

Array<string>
>= 1 items unique items
reservationId

Optional credit reservation to consume.

string
reservationLineItemIdByLanguage

Reservation line-item IDs keyed by requested language.

object
key
additional properties
string
Example 
{
  "languages": [
    "es",
    "fr"
  ],
  "reservationId": "rsv_01JZ9A",
  "reservationLineItemIdByLanguage": {
    "es": "li_01",
    "fr": "li_02"
  }
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Translation jobs queued.

Media type application/json
object
jobs
required

One queued caption job per language.

Array<object>
object
id
required

Deterministic, pollable job ID.

string
type
required

Product workflow represented by the job.

string
Allowed values: import transcript dub captions shorts thumbnail packaging download
status
required

Current normalized job lifecycle state.

string
Allowed values: queued processing ready failed
videoId

Parent video when applicable.

string
language

Target language for a dub or caption job.

string
>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/
product

Dubbing product used by a dub job.

string
default: plus
Allowed values: plus premium
automationType

Packaging automation when type is packaging.

string
Allowed values: generateTitle generateDescription zeroPromptThumbnail
result

Type-specific ready-state artifacts.

object
key
additional properties
any
error

Terminal failure details when status is failed.

object
code
required

Machine-readable job failure code.

string
message
required

Human-readable job failure explanation.

string
details

Type-specific identifiers and context.

object
key
additional properties
any
Example 
{
  "jobs": [
    {
      "id": "captions_vid_01JZ8M6A_es",
      "type": "captions",
      "status": "queued",
      "language": "es"
    }
  ]
}

400

Section titled “400 ”

Request fields are missing, malformed, out of bounds, or mutually inconsistent.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "The request contains invalid or missing fields.",
    "details": {}
  }
}

401

Section titled “401 ”

A supported authentication header is missing or contains an invalid Public API key.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Examples

Authentication header missing

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing API key.",
    "details": {}
  }
}

403

Section titled “403 ”

Authentication succeeded, but the required scope, workspace role, or resource permission is missing.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Examples
Example scope 
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key lacks the required scope.",
    "details": {}
  }
}

404

Section titled “404 ”

The resource does not exist or is not accessible to the caller.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "details": {}
  }
}

409

Section titled “409 ”

The Idempotency-Key was reused with a different path or request body.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "IDEMPOTENCY_REPLAY",
    "message": "Idempotency-Key was reused with a different request.",
    "details": {
      "pathMatch": true,
      "hashMatch": false
    }
  }
}

429

Section titled “429 ”

The account has insufficient credits, or the request exceeded a rate limit.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits.",
    "details": {
      "required": 60,
      "available": 20,
      "shortfall": 40
    }
  }
}

500

Section titled “500 ”

An unexpected server error occurred.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": {}
  }
}