Generate a thumbnail

Braiv can generate a video thumbnail without a written prompt, or from a prompt you supply. Two pipelines:

• Creative (pipelineMode: thumbnail-v2, the default) — character subjects (0–3). Discover ids with GET /characters.
• Precision (pipelineMode: thumbnail-precision) — one or two content plates from the programme. Characters are rejected. Set autoDetectContentReferences: true to detect key moments internally (no public moments API), or pass contentReferenceImageUrl / contentReferenceImageUrls.

There is no creative enum value. Brand Voices (GET /brand-voices) apply as brandVoiceId on either pipeline.

Quote first when you want a hard cap: POST /videos/{videoId}/quote with zeroPromptThumbnail. Precision auto-detect adds a content-moment-detect line — set autoDetectContentMoments: true on the quote (pricing name) when the recipe uses autoDetectContentReferences.

1. Discover characters and Brand Voices

curl -sS "$BRAIV_API_BASE/characters" \
  -H "Authorization: Bearer $BRAIV_API_KEY"
curl -sS "$BRAIV_API_BASE/brand-voices" \
  -H "Authorization: Bearer $BRAIV_API_KEY"

Scope: videos:read.

2. Import-time (zero-prompt only)

POST /videos products.packaging.thumbnail uses the same object as packaging zeroPromptThumbnail. true or {} is faceless Creative.

Creative with a saved character

"packaging": {
  "thumbnail": {
    "enabled": true,
    "pipelineMode": "thumbnail-v2",
    "characterCount": 1,
    "characters": [{"characterId": "char_01"}],
    "brandVoiceId": "bv_01"
  }
}

Precision with opaque key-moment detect

"packaging": {
  "thumbnail": {
    "enabled": true,
    "pipelineMode": "thumbnail-precision",
    "autoDetectContentReferences": true,
    "contentSlotCount": 2,
    "brandVoiceId": "bv_01"
  }
}

Poll import_{videoId} first, then packaging_{videoId}_zeroPromptThumbnail. Upload and HTTPS recipes create the same automation runs as URL import.

See Import with a recipe.

3. Already imported

Zero-prompt (async when detect is on) — POST /videos/{videoId}/thumbnails with mode: zero_prompt and the same fields. Auto-detect returns 202 and jobId packaging_{videoId}_zeroPromptThumbnail. Without detect, the call is 200 with a thumbnail_* job.

Zero-prompt via packaging — same config under zeroPromptThumbnail on POST /videos/{videoId}/packaging. See Title, description, thumbnail.

Prompt — mode: prompt (default) plus prompt. Creative may include characters. Precision requires explicit content plate URLs (auto-detect is 400; use zero-prompt or packaging instead).

curl -sS -X POST "$BRAIV_API_BASE/videos/$VIDEO_ID/thumbnails" \
  -H "Authorization: Bearer $BRAIV_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "prompt",
    "prompt": "A confident presenter beside a before-and-after split, high contrast",
    "pipelineMode": "thumbnail-v2",
    "characters": [{"characterId": "char_01"}],
    "brandVoiceId": "bv_01",
    "promoteToPrimary": true
  }'

Poll thumbnail_{thumbnailRequestId} or the packaging job from a 202.

MCP

After Connect, use braiv_list_characters and braiv_list_brand_voices, then pass the same JSON on braiv_create_video (products.packaging.thumbnail), braiv_create_packaging, or braiv_create_thumbnail. See MCP.