Skip to content
Braiv Docs

Generate packaging assets

POST
/videos/{videoId}/packaging
 
curl --request POST \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/packaging \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: import-launch-demo-20260901' \
  --data '{ "automationOptions": { "generateTitle": { "enabled": true, "titleType": "informational", "overwriteMode": "fill-if-empty" }, "generateDescription": { "enabled": true, "descriptionType": "youtube-description", "overwriteMode": "fill-if-empty" }, "zeroPromptThumbnail": { "enabled": true, "characterCount": 0, "pipelineMode": "thumbnail-precision", "autoDetectContentReferences": true, "contentSlotCount": 1 } } }'

Enables one or more title, description, or zero-prompt-thumbnail automations. Send fields directly or under automationOptions; the nested form is recommended. Already-pending automation types are reported separately and are not duplicated. Required scope: packaging: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 ”
Media type application/json
One of:
object
automationOptions
required

Packaging automations to enable.

object
>= 1 properties
brandVoiceId

Shared fallback brand voice for description and thumbnail automation.

string
<= 128 characters
generateTitle

Title generation configuration.

object
enabled
required

Enables title generation.

boolean
titleType
required

Tone used for the generated title: funny is light or relatable; scary emphasizes warnings or mistakes; informational is direct and useful; mysterious creates a curiosity gap; and clickbait uses bold, high-energy framing.

string
Allowed values: funny scary informational mysterious clickbait
overwriteMode

Generation policy. fill-if-empty is the default automation mode; always explicitly allows replacement of the current title; and never records the automation as skipped without generating a title.

string
default: fill-if-empty
Allowed values: fill-if-empty always never
generateDescription

Description generation configuration.

object
enabled
required

Enables description generation.

boolean
descriptionType
required

Generated output format: youtube-description creates SEO copy with chapters and tags; social-post creates concise social copy; how-to-guide creates timestamped Markdown steps; blog-post creates a long-form Markdown article; and video-summary creates a timestamped narrative summary.

string
Allowed values: youtube-description social-post how-to-guide blog-post video-summary
overwriteMode

Generation policy. fill-if-empty is the default automation mode; always explicitly allows replacement of the active description; and never records the automation as skipped without generating copy.

string
default: fill-if-empty
Allowed values: fill-if-empty always never
brandVoiceId

Brand voice profile used for copy.

string
<= 128 characters
zeroPromptThumbnail

Context-derived thumbnail configuration.

object
enabled
required

Enables zero-prompt thumbnail generation.

boolean
characterCount

Number of character references to use.

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
referenceSchemaVersion

Reference payload model. 1 uses the legacy aesthetic, layout, and design-influence interpretation. 2 separates style recreation from brand references and enables thumbnail-precision.

integer
default: 1
Allowed values: 1 2
pipelineMode

Thumbnail generation workflow. thumbnail-v2 supports character, style, and brand references. thumbnail-precision uses one or two content-plate references and does not accept character references.

string
default: thumbnail-v2
Allowed values: thumbnail-v2 thumbnail-precision
contentReferenceImageUrl

Primary content plate reference.

string format: uri
contentReferenceImageUrls

Precision-mode 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

Not available in precision mode.

boolean
characterDetectApprovalMode

Character detection workflow. auto accepts detected references and continues; review waits for approval before generation.

string
default: auto
Allowed values: auto review
autoDetectContentReferences

Precision only. When omitted and no content plate URLs are sent

boolean
contentSlotCount

Number of distinct content-plate references selected for precision mode. Use 1 for one reference frame or 2 for two complementary frames.

integer
default: 1
Allowed values: 1 2
contentDetectApprovalMode

Content-reference detection workflow. auto accepts detected frames and continues; review waits for approval before generation.

string
default: auto
Allowed values: auto review
contentDetectPrompt

Optional focus text that steers opaque key-moment detect.

string
textOverlay

Optional Precision headline burned into the thumbnail.

string
omitTextOverlay

When true

boolean
autoTranslateThumbnail

Effective only with non-empty thumbnailTranslationLanguageCodes.

boolean
thumbnailTranslationLanguageCodes

Languages for translated thumbnail variants.

Array<string>
unique items
brandVoiceId

Brand voice profile used by thumbnail copy.

string
<= 128 characters
Example 
{
  "automationOptions": {
    "generateTitle": {
      "enabled": true,
      "titleType": "informational",
      "overwriteMode": "fill-if-empty"
    },
    "generateDescription": {
      "enabled": true,
      "descriptionType": "youtube-description",
      "overwriteMode": "fill-if-empty"
    },
    "zeroPromptThumbnail": {
      "enabled": true,
      "characterCount": 0,
      "pipelineMode": "thumbnail-precision",
      "autoDetectContentReferences": true,
      "contentSlotCount": 1
    }
  }
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

New automation jobs queued; pending duplicates identified.

Media type application/json
object
registered
required

Whether at least one new run was created.

boolean
alreadyPending
required

Requested automation types already in progress.

Array<string>
Allowed values: generateTitle generateDescription zeroPromptThumbnail
jobs
required

Newly queued packaging jobs.

Array<object>
object
id
required

Deterministic, pollable job ID.

string
type
required

Product workflow represented by the job.

string
Allowed values: import transcript dub captions shorts thumbnail packaging download
status
required

Current normalized job lifecycle state.

string
Allowed values: queued processing ready failed
videoId

Parent video when applicable.

string
language

Target language for a dub or caption job.

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

Dubbing product used by a dub job.

string
default: plus
Allowed values: plus premium
automationType

Packaging automation when type is packaging.

string
Allowed values: generateTitle generateDescription zeroPromptThumbnail
result

Type-specific ready-state artifacts.

object
key
additional properties
any
error

Terminal failure details when status is failed.

object
code
required

Machine-readable job failure code.

string
message
required

Human-readable job failure explanation.

string
details

Type-specific identifiers and context.

object
key
additional properties
any
Example 
{
  "registered": true,
  "alreadyPending": [],
  "jobs": [
    {
      "id": "packaging_vid_01JZ8M6A_generateTitle",
      "type": "packaging",
      "status": "queued",
      "automationType": "generateTitle"
    }
  ]
}

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

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