Skip to content
Braiv Docs

Reserve credits for a bundle

POST
/videos/{videoId}/reservations
 
curl --request POST \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/reservations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: import-launch-demo-20260901' \
  --data '{ "durationSeconds": 184, "captionLanguageCodes": [ "es", "fr" ], "shorts": { "kind": "promo", "includeSoundtrack": true } }'

Atomically debits the full quoted bundle into escrow. Pass reservation and line-item IDs to supported product creation calls. Required scope: videos: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

Section titled “Request Body ”

At least one billable action is required.

Media type application/json
object
durationSeconds

Settled billing duration; otherwise resolved from the source video.

number
> 0
dubs

Dubs included in the quote or reservation.

Array<object>
object
product

Dubbing product to price.

string
default: plus
Allowed values: plus premium
languages
required

Target languages priced separately.

Array<string>
>= 1 items unique items
captionLanguageCodes

Caption translation languages to price.

Array<string>
unique items
transcriptOnly

Reserve source transcription as a standalone action.

boolean
shorts

Shorts-family bundle to price.

object
kind
required

Shorts-family product to price: shorts prices short highlights, promo prices one promotional edit, and clips prices long-form excerpts.

string
Allowed values: shorts promo clips
numClips

Number of clips priced; defaults to one.

integer
default: 1 >= 1
includeWatermark

Affects clip pricing and subscriber rebates.

boolean
isSubscriber

Pricing hint consumed by the bundle pricer.

boolean
includeSoundtrack

Adds the promo soundtrack product.

boolean
includeGeneratedThumbnail

Adds generated thumbnail pricing to each long clip.

boolean
zeroPromptThumbnail

Zero-prompt thumbnail bundle to price.

object
enabled
required

Only true creates thumbnail line items.

boolean
referenceProducts

Additional catalog products used as references.

Array<string>
characterCount

Character reference slots added to pricing.

integer
0 <= 3
translateLanguageCodes

Thumbnail translation languages priced individually.

Array<string>
unique items
autoDetectContentMoments

Adds the content-moment-detect line item. Set this when the generation recipe uses Precision autoDetectContentReferences. Quote field name stays autoDetectContentMoments for pricing.

boolean
Example 
{
  "durationSeconds": 184,
  "captionLanguageCodes": [
    "es",
    "fr"
  ],
  "shorts": {
    "kind": "promo",
    "includeSoundtrack": true
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Credits reserved and line items created.

Media type application/json
object
reservationId
required

Escrow identifier supplied to product requests.

string
total
required

Total credits moved into escrow.

number
durationSeconds
required

Settled duration used to reserve credits.

number
lineItems
required

Escrow lines consumed by matching product actions.

Array
>= 1 items
object
actionKey
required

Billable action consumed by downstream work.

string
Allowed values: dub captions transcript zero-prompt-thumbnail thumbnail-translate content-moment-detect lipsync shorts-clip promo longclip
product
required

Internal catalog product used for pricing.

string
targetLanguageCode

Language charged by this line

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

Exact credits quoted or reserved.

number
description

Human-readable line-item summary.

string
lineItemId
required

Escrow line item passed to the matching create operation.

string
Example 
{
  "reservationId": "rsv_01JZ9A",
  "total": 132,
  "durationSeconds": 184,
  "lineItems": [
    {
      "lineItemId": "li_01",
      "actionKey": "captions",
      "product": "translate-captions-only",
      "targetLanguageCode": "es",
      "credits": 46
    },
    {
      "lineItemId": "li_02",
      "actionKey": "promo",
      "product": "promo",
      "credits": 40
    }
  ]
}

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
    }
  }
}

422

Section titled “422 ”

Media duration is unknown for duration-priced work.

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

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