---
title: "Reserve credits for a bundle"
method: POST
path: "/videos/{videoId}/reservations"
tags: ["Credits"]
---

# Reserve credits for a bundle

`POST /videos/{videoId}/reservations`

## Request

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

Atomically debits the full quoted bundle into escrow. Pass reservation and line-item IDs to supported product creation calls. Required scope: `videos:write`.

## Path parameters

- `videoId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CreditBundleRequest
  - `durationSeconds` number: Settled billing duration; otherwise resolved from the source video.
  - `dubs` CreditDubSelection[]: Dubs included in the quote or reservation.
    - `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.
    - `languages` LanguageCode[], required: Target languages priced separately.
  - `captionLanguageCodes` LanguageCode[]: Caption translation languages to price.
  - `transcriptOnly` boolean: Reserve source transcription as a standalone action.
  - `shorts` CreditShortsSelection
    - `kind` 'shorts' | 'promo' | 'clips', required: Shorts-family product to price: `shorts` prices short highlights, `promo` prices one promotional edit, and `clips` prices long-form excerpts.
    - `numClips` integer: Number of clips priced; defaults to one.
    - `includeWatermark` boolean: Affects clip pricing and subscriber rebates.
    - `isSubscriber` boolean: Pricing hint consumed by the bundle pricer.
    - `includeSoundtrack` boolean: Adds the promo soundtrack product.
    - `includeGeneratedThumbnail` boolean: Adds generated thumbnail pricing to each long clip.
  - `zeroPromptThumbnail` CreditThumbnailSelection
    - `enabled` boolean, required: Only `true` creates thumbnail line items.
    - `referenceProducts` string[]: Additional catalog products used as references.
    - `characterCount` integer: Character reference slots added to pricing.
    - `translateLanguageCodes` LanguageCode[]: Thumbnail translation languages priced individually.
    - `autoDetectContentMoments` boolean: Adds the `content-moment-detect` line item. Set this when the generation recipe uses Precision `autoDetectContentReferences`. Quote field name stays `autoDetectContentMoments` for pricing.

## Response `201`

Credits reserved and line items created.

- CreditReservation
  - `reservationId` string, required: Escrow identifier supplied to product requests.
  - `total` number, required: Total credits moved into escrow.
  - `durationSeconds` number, required: Settled duration used to reserve credits.
  - `lineItems` CreditReservationLine[], required: Escrow lines consumed by matching product actions.
    - `actionKey` 'dub' | 'captions' | 'transcript' | 'zero-prompt-thumbnail' | 'thumbnail-translate' | 'content-moment-detect' | 'lipsync' | 'shorts-clip' | 'promo' | 'longclip', required: Billable action consumed by downstream work.
    - `product` string, required: Internal catalog product used for pricing.
    - `targetLanguageCode` string: ISO-style language or locale code accepted by the underlying product.
    - `credits` number, required: Exact credits quoted or reserved.
    - `description` string: Human-readable line-item summary.
    - `lineItemId` string, required: Escrow line item passed to the matching create operation.

## 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.
- `422`: Media duration is unknown for duration-priced work.
- `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)