Create an AI thumbnail

POST

/videos/{videoId}/thumbnails

curl --request POST \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/thumbnails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: import-launch-demo-20260901' \
  --data '{ "mode": "prompt", "prompt": "A dramatic creator reveal with bright studio lighting" }'

• Braiv Public API

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.

Authorizations

• bearerAuth
• apiKeyHeader

Parameters

Path Parameters

videoId

required

string

>= 1 characters

Braiv library video document ID.

Example

vid_01JZ8M6A

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

Media type application/json

Any of: discriminator: mode

object

object

mode

Uses your prompt as the creative direction for thumbnail generation. This is the default mode.

string

default: prompt

Allowed value: prompt

prompt

required

Natural-language description of the thumbnail scene, composition, subjects, and mood. The value must contain non-whitespace text.

string

>= 1 characters

characters

Character references to preserve. Not valid with thumbnail-precision.

Array<object>

<= 3 items

object

characterId

Saved character profile ID.

string

referenceImageIds

Saved reference image IDs.

Array<string>

<= 10 items

imageUrl

Primary character reference URL.

string format: uri

imageUrls

Additional character reference URLs.

Array<string>

<= 3 items

name

Character display name.

string

position

Desired composition position.

string

action

Desired character pose or action.

string

styleReferenceImageUrl

Public image URL whose visual style and layout should influence the result.

string format: uri

brandReferenceImageUrl

Public image URL providing brand colours, typography, or identity cues.

string format: uri

designInfluenceImageUrl

Composition influence image.

string format: uri

brandInfluence

Relative brand-style influence passed to generation.

number

referenceSchemaVersion

Reference payload model. Precision uses 2.

integer

Allowed values: 1 2

pipelineMode

thumbnail-v2 is Creative (character subjects). thumbnail-precision requires contentReferenceImageUrl or contentReferenceImageUrls. Prompt mode does not accept auto-detect flags.

string

default: thumbnail-v2

Allowed values: thumbnail-v2 thumbnail-precision

contentReferenceImageUrl

Primary Precision content plate.

string format: uri

contentReferenceImageUrls

Precision content plates (1–2).

Array<string>

brandVoiceId

Studio Brand Voice id from listBrandVoices.

string

<= 128 characters

textOverlay

Optional Precision headline.

string

omitTextOverlay

Precision only — omit generated headline text.

boolean

promoteToPrimary

Make the first generated image the video poster.

boolean

object

object

mode

required

Builds the thumbnail direction automatically from the video’s transcript and visual context instead of requiring a creative prompt.

string

Allowed value: zero_prompt

enabled

Optional; implied by mode: zero_prompt.

boolean

characterCount

Number of people or characters to preserve from characters. Send a JSON integer from 0 to 3 that matches the supplied array length.

integer

0 <= 3

characters

Character references matching characterCount.

Array<object>

<= 3 items

object

characterId

Saved character profile ID.

string

referenceImageIds

Saved reference image IDs.

Array<string>

<= 10 items

imageUrl

Primary character reference URL.

string format: uri

imageUrls

Additional character reference URLs.

Array<string>

<= 3 items

name

Character display name.

string

position

Desired composition position.

string

action

Desired character pose or action.

string

promoteToPrimary

Set to true to make the generated thumbnail the video’s primary poster when generation completes.

boolean

referenceSchemaVersion

Reference payload model. 2 is required for Precision.

integer

default: 1

Allowed values: 1 2

pipelineMode

Creative (thumbnail-v2) vs Precision (thumbnail-precision). There is no creative enum value. Precision rejects characters and needs content plates or autoDetectContentReferences.

string

default: thumbnail-v2

Allowed values: thumbnail-v2 thumbnail-precision

contentReferenceImageUrl

Primary content plate when not auto-detecting.

string format: uri

contentReferenceImageUrls

Precision content plates.

Array<string>

designInfluenceImageUrl

Composition influence image.

string format: uri

styleReferenceImageUrl

Style influence image.

string format: uri

brandReferenceImageUrl

Brand influence image.

string format: uri

brandInfluence

Relative brand-style influence passed to generation.

number

autoDetectCharacters

Creative only. Returns 202 and queues character detect.

boolean

characterDetectApprovalMode

Character detection workflow.

string

default: auto

Allowed values: auto review

autoDetectContentReferences

Precision only. Opaque key-moment detect; returns 202.

boolean

contentSlotCount

Number of Precision plates to select when auto-detecting.

integer

default: 1

Allowed values: 1 2

contentDetectApprovalMode

Content-reference detection workflow.

string

default: auto

Allowed values: auto review

contentDetectPrompt

Optional focus text that steers opaque key-moment detect.

string

textOverlay

Optional Precision headline.

string

omitTextOverlay

Precision only — omit generated headline text.

boolean

autoTranslateThumbnail

Effective only with non-empty thumbnailTranslationLanguageCodes.

boolean

thumbnailTranslationLanguageCodes

Languages for translated thumbnail variants.

Array<string>

unique items

brandVoiceId

Brand Voice id from listBrandVoices.

string

<= 128 characters

Examples

{
  "mode": "prompt",
  "prompt": "A dramatic creator reveal with bright studio lighting"
}

Faceless Creative zero-prompt

{
  "mode": "zero_prompt",
  "characterCount": 0,
  "promoteToPrimary": true
}

Precision with opaque key-moment detect

{
  "mode": "zero_prompt",
  "pipelineMode": "thumbnail-precision",
  "autoDetectContentReferences": true,
  "contentSlotCount": 2,
  "brandVoiceId": "bv_01"
}

Responses

200

Request created; synchronous setup may already return generated URLs.

Media type application/json

object

thumbnailRequestId

Created thumbnail request ID when generation starts synchronously.

string

jobId

required

Pollable thumbnail job ID, or packaging job ID when detect is queued (202).

string

status

queued when a detect-backed automation was registered.

string

registered

Whether a new automation run was created for a 202 response.

boolean

thumbnailUrl

Zero-prompt result when returned synchronously.

string format: uri

outputImageUrls

Prompt-mode generated images.

Array<string>

balance

Remaining account credit balance.

number

Example

{
  "thumbnailRequestId": "thumb_01",
  "jobId": "thumbnail_thumb_01",
  "outputImageUrls": [
    "https://cdn.braiv.co/thumb_01.jpg"
  ],
  "balance": 280
}

202

Zero-prompt automation queued because character or content-moment detect must finish first. Poll the packaging job.

Media type application/json

object

thumbnailRequestId

Created thumbnail request ID when generation starts synchronously.

string

jobId

required

Pollable thumbnail job ID, or packaging job ID when detect is queued (202).

string

status

queued when a detect-backed automation was registered.

string

registered

Whether a new automation run was created for a 202 response.

boolean

thumbnailUrl

Zero-prompt result when returned synchronously.

string format: uri

outputImageUrls

Prompt-mode generated images.

Array<string>

balance

Remaining account credit balance.

number

Example

{
  "jobId": "packaging_vid_01JZ8M6A_zeroPromptThumbnail",
  "status": "queued",
  "registered": true
}

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

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

API key invalid

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": {}
  }
}

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

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

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

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

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