---
title: "Create an AI thumbnail"
method: POST
path: "/videos/{videoId}/thumbnails"
tags: ["Thumbnails"]
---

# Create an AI thumbnail

`POST /videos/{videoId}/thumbnails`

## Request

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

Creates a prompt-directed thumbnail (`mode: prompt`) or a zero-prompt
thumbnail (`mode: zero_prompt`) derived from transcript and visual
context. Pipeline `thumbnail-v2` is Creative (character subjects).
`thumbnail-precision` uses one or two content plates and rejects
characters. Auto-detect (`autoDetectCharacters` or
`autoDetectContentReferences`) is zero-prompt only and returns `202`
with a packaging job id. Prompt Precision requires explicit content
image URLs. Required scope: `thumbnails:write`.

## Path parameters

- `videoId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- union
  - PromptThumbnailRequest
    - `mode` 'prompt': Uses your `prompt` as the creative direction for thumbnail generation. This is the default mode.
    - `prompt` string, required: Natural-language description of the thumbnail scene, composition, subjects, and mood. The value must contain non-whitespace text.
    - `characters` ThumbnailCharacter[]: Character references to preserve. Not valid with `thumbnail-precision`.
      - `characterId` string: Saved character profile ID.
      - `referenceImageIds` string[]: Saved reference image IDs.
      - `imageUrl` string, uri: Primary character reference URL.
      - `imageUrls` string[]: Additional character reference URLs.
      - `name` string: Character display name.
      - `position` string: Desired composition position.
      - `action` string: Desired character pose or action.
    - `styleReferenceImageUrl` string, uri: Public image URL whose visual style and layout should influence the result.
    - `brandReferenceImageUrl` string, uri: Public image URL providing brand colours, typography, or identity cues.
    - `designInfluenceImageUrl` string, uri: Composition influence image.
    - `brandInfluence` number: Relative brand-style influence passed to generation.
    - `referenceSchemaVersion` 1 | 2: Reference payload model. Precision uses `2`.
    - `pipelineMode` 'thumbnail-v3' | 'thumbnail-v2' | 'thumbnail-precision' | 'v1': Omitted `pipelineMode` is `thumbnail-v3`. `thumbnail-v2` and `v1` remain available when sent explicitly. `thumbnail-precision` requires `contentReferenceImageUrl` or `contentReferenceImageUrls`. Prompt mode does not accept auto-detect flags.
    - `contentReferenceImageUrl` string, uri: Primary Precision content plate.
    - `contentReferenceImageUrls` string[]: Precision content plates (1–2).
    - `brandVoiceId` string: Studio Brand Voice id from `listBrandVoices`.
    - `textOverlay` string: Optional Precision headline.
    - `omitTextOverlay` boolean: Precision only — omit generated headline text.
    - `promoteToPrimary` boolean: Make the first generated image the video poster.
  - ZeroPromptThumbnailRequest
    - `mode` 'zero_prompt', required: Builds the thumbnail direction automatically from the video's transcript and visual context instead of requiring a creative prompt.
    - `enabled` true: Optional; implied by `mode: zero_prompt`.
    - `characterCount` integer: Number of people or characters to preserve from `characters`. Send a JSON integer from 0 to 3 that matches the supplied array length.
    - `characters` ThumbnailCharacter[]: Character references matching characterCount.
      - `characterId` string: Saved character profile ID.
      - `referenceImageIds` string[]: Saved reference image IDs.
      - `imageUrl` string, uri: Primary character reference URL.
      - `imageUrls` string[]: Additional character reference URLs.
      - `name` string: Character display name.
      - `position` string: Desired composition position.
      - `action` string: Desired character pose or action.
    - `promoteToPrimary` boolean: Set to `true` to make the generated thumbnail the video's primary poster when generation completes.
    - `referenceSchemaVersion` 1 | 2: Reference payload model. `2` is required for Precision.
    - `pipelineMode` 'thumbnail-v3' | 'thumbnail-v2' | 'thumbnail-precision' | 'v1': Omitted `pipelineMode` is `thumbnail-v3` and uses reference schema 2. `thumbnail-v2` and `v1` remain available when sent explicitly. `thumbnail-precision` rejects characters and needs content plates or `autoDetectContentReferences`.
    - `contentReferenceImageUrl` string, uri: Primary content plate when not auto-detecting.
    - `contentReferenceImageUrls` string[]: Precision content plates.
    - `designInfluenceImageUrl` string, uri: Composition influence image.
    - `styleReferenceImageUrl` string, uri: Style influence image.
    - `brandReferenceImageUrl` string, uri: Brand influence image.
    - `brandInfluence` number: Relative brand-style influence passed to generation.
    - `autoDetectCharacters` boolean: Creative only. Returns 202 and queues character detect.
    - `characterDetectApprovalMode` 'auto' | 'review': Character detection workflow.
    - `autoDetectContentReferences` boolean: Precision only. Opaque key-moment detect; returns 202.
    - `contentSlotCount` 1 | 2: Number of Precision plates to select when auto-detecting.
    - `contentDetectApprovalMode` 'auto' | 'review': Content-reference detection workflow.
    - `contentDetectPrompt` string: Optional focus text that steers opaque key-moment detect.
    - `textOverlay` string: Optional Precision headline.
    - `omitTextOverlay` boolean: Precision only — omit generated headline text.
    - `autoTranslateThumbnail` boolean: Effective only with non-empty thumbnailTranslationLanguageCodes.
    - `thumbnailTranslationLanguageCodes` LanguageCode[]: Languages for translated thumbnail variants.
    - `brandVoiceId` string: Brand Voice id from `listBrandVoices`.

## Response `200`

Request created; synchronous setup may already return generated URLs.

- CreateThumbnailResponse
  - `thumbnailRequestId` string: Created thumbnail request ID when generation starts synchronously.
  - `jobId` string, required: Pollable thumbnail job ID, or packaging job ID when detect is queued (`202`).
  - `status` string: `queued` when a detect-backed automation was registered.
  - `registered` boolean: Whether a new automation run was created for a `202` response.
  - `thumbnailUrl` string, uri: Zero-prompt result when returned synchronously.
  - `outputImageUrls` string[]: Prompt-mode generated images.
  - `balance` number: Remaining account credit balance.

## Other responses

- `202`: Zero-prompt automation queued because character or content-moment detect must finish first. Poll the packaging job.
- `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)