Skip to content
Braiv Docs

Create dubs

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

Queues one dub job per target language using the selected voice product and source voiceover track. 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 dub target languages.

Array<string>
>= 1 items unique items
product

Voice product used for all targets.

string
default: plus
Allowed values: plus premium
sourceVoiceover

Source narration used to produce the dub: original uses the video’s source transcript and narration; optimized uses the latest ready Optimize/redub transcript. Choose optimized only after that workflow is ready.

string
default: original
Allowed values: original optimized
reservationId

Optional credit escrow to consume.

string
reservationLineItemIdByLanguage

Reservation line-item IDs keyed by requested language.

object
key
additional properties
string
Example 
{
  "languages": [
    "es",
    "de"
  ],
  "product": "premium",
  "sourceVoiceover": "original",
  "reservationId": "rsv_01JZ9A",
  "reservationLineItemIdByLanguage": {
    "es": "li_01",
    "de": "li_02"
  }
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Dub jobs queued.

Media type application/json
object
videoId
required

Parent library video ID.

string
jobs
required

One queued dub 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
balance

Remaining credit balance when returned by the dubbing service.

number
Example 
{
  "videoId": "vid_01JZ8M6A",
  "jobs": [
    {
      "id": "dub_vid_01JZ8M6A_es_premium",
      "type": "dub",
      "status": "queued",
      "language": "es",
      "product": "premium"
    }
  ],
  "balance": 254
}

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": {}
  }
}