--- title: "Generate packaging assets" method: POST path: "/videos/{videoId}/packaging" tags: ["Packaging"] --- # Generate packaging assets `POST /videos/{videoId}/packaging` ## Request - Base URL: `https://api.braiv.co/v1` - URL: `https://api.braiv.co/v1/videos/{videoId}/packaging` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` 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`. ## Path parameters - `videoId` string, required ## Headers - `Idempotency-Key` string ## Request body - union: Nested `automationOptions` or the same fields at the root. At least one automation must have `enabled: true`. - object - `automationOptions` AutomationOptions, required - `brandVoiceId` string: Shared fallback brand voice for description and thumbnail automation. - `generateTitle` GenerateTitleAutomation - `enabled` true, required: Enables title generation. - `titleType` 'funny' | 'scary' | 'informational' | 'mysterious' | 'clickbait', 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. - `overwriteMode` 'fill-if-empty' | 'always' | 'never': 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. - `generateDescription` GenerateDescriptionAutomation - `enabled` true, required: Enables description generation. - `descriptionType` 'youtube-description' | 'social-post' | 'how-to-guide' | 'blog-post' | 'video-summary', 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. - `overwriteMode` 'fill-if-empty' | 'always' | 'never': 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. - `brandVoiceId` string: Brand voice profile used for copy. - `zeroPromptThumbnail` PackagingThumbnailAutomation - `enabled` true, required: Enables zero-prompt thumbnail generation. - `characterCount` integer: Number of character references to use. - `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. - `referenceSchemaVersion` 1 | 2: Reference payload model. `1` uses the legacy aesthetic, layout, and design-influence interpretation. `2` separates style recreation from brand references and enables `thumbnail-precision`. - `pipelineMode` 'thumbnail-v3' | 'thumbnail-v2' | 'thumbnail-precision' | 'v1': Omitted `pipelineMode` is `thumbnail-v3`. `thumbnail-v2` and `v1` remain available when sent explicitly. `thumbnail-precision` uses one or two content-plate references and does not accept character references. - `contentReferenceImageUrl` string, uri: Primary content plate reference. - `contentReferenceImageUrls` string[]: Precision-mode 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: Not available in precision mode. - `characterDetectApprovalMode` 'auto' | 'review': Character detection workflow. `auto` accepts detected references and continues; `review` waits for approval before generation. - `autoDetectContentReferences` boolean: Precision only. When omitted and no content plate URLs are sent - `contentSlotCount` 1 | 2: Number of distinct content-plate references selected for precision mode. Use `1` for one reference frame or `2` for two complementary frames. - `contentDetectApprovalMode` 'auto' | 'review': Content-reference detection workflow. `auto` accepts detected frames and continues; `review` waits for approval before generation. - `contentDetectPrompt` string: Optional focus text that steers opaque key-moment detect. - `textOverlay` string: Optional Precision headline burned into the thumbnail. - `omitTextOverlay` boolean: When true - `autoTranslateThumbnail` boolean: Effective only with non-empty thumbnailTranslationLanguageCodes. - `thumbnailTranslationLanguageCodes` LanguageCode[]: Languages for translated thumbnail variants. - `brandVoiceId` string: Brand voice profile used by thumbnail copy. - AutomationOptions - `brandVoiceId` string: Shared fallback brand voice for description and thumbnail automation. - `generateTitle` GenerateTitleAutomation - `enabled` true, required: Enables title generation. - `titleType` 'funny' | 'scary' | 'informational' | 'mysterious' | 'clickbait', 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. - `overwriteMode` 'fill-if-empty' | 'always' | 'never': 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. - `generateDescription` GenerateDescriptionAutomation - `enabled` true, required: Enables description generation. - `descriptionType` 'youtube-description' | 'social-post' | 'how-to-guide' | 'blog-post' | 'video-summary', 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. - `overwriteMode` 'fill-if-empty' | 'always' | 'never': 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. - `brandVoiceId` string: Brand voice profile used for copy. - `zeroPromptThumbnail` PackagingThumbnailAutomation - `enabled` true, required: Enables zero-prompt thumbnail generation. - `characterCount` integer: Number of character references to use. - `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. - `referenceSchemaVersion` 1 | 2: Reference payload model. `1` uses the legacy aesthetic, layout, and design-influence interpretation. `2` separates style recreation from brand references and enables `thumbnail-precision`. - `pipelineMode` 'thumbnail-v3' | 'thumbnail-v2' | 'thumbnail-precision' | 'v1': Omitted `pipelineMode` is `thumbnail-v3`. `thumbnail-v2` and `v1` remain available when sent explicitly. `thumbnail-precision` uses one or two content-plate references and does not accept character references. - `contentReferenceImageUrl` string, uri: Primary content plate reference. - `contentReferenceImageUrls` string[]: Precision-mode 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: Not available in precision mode. - `characterDetectApprovalMode` 'auto' | 'review': Character detection workflow. `auto` accepts detected references and continues; `review` waits for approval before generation. - `autoDetectContentReferences` boolean: Precision only. When omitted and no content plate URLs are sent - `contentSlotCount` 1 | 2: Number of distinct content-plate references selected for precision mode. Use `1` for one reference frame or `2` for two complementary frames. - `contentDetectApprovalMode` 'auto' | 'review': Content-reference detection workflow. `auto` accepts detected frames and continues; `review` waits for approval before generation. - `contentDetectPrompt` string: Optional focus text that steers opaque key-moment detect. - `textOverlay` string: Optional Precision headline burned into the thumbnail. - `omitTextOverlay` boolean: When true - `autoTranslateThumbnail` boolean: Effective only with non-empty thumbnailTranslationLanguageCodes. - `thumbnailTranslationLanguageCodes` LanguageCode[]: Languages for translated thumbnail variants. - `brandVoiceId` string: Brand voice profile used by thumbnail copy. ## Response `202` New automation jobs queued; pending duplicates identified. - CreatePackagingResponse - `registered` boolean, required: Whether at least one new run was created. - `alreadyPending` string[], required: Requested automation types already in progress. - `jobs` Job[], required: Newly queued packaging jobs. - `id` string, required: Deterministic, pollable job ID. - `type` 'import' | 'transcript' | 'dub' | 'captions' | 'shorts' | 'thumbnail' | 'packaging' | 'download' | 'music', required: Product workflow represented by the job. - `status` 'queued' | 'processing' | 'ready' | 'failed', required: Normalized lifecycle shared by jobs and video projections: `queued` is waiting to start, `processing` is running, `ready` completed successfully, and `failed` reached a terminal error. - `videoId` string: Parent video when applicable. - `language` string: ISO-style language or locale code accepted by the underlying product. - `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. - `automationType` 'generateTitle' | 'generateDescription' | 'zeroPromptThumbnail': Packaging automation when type is packaging. - `result` object: Type-specific ready-state artifacts. - `error` JobError - `code` string, required: Machine-readable job failure code. - `message` string, required: Human-readable job failure explanation. - `details` object: Type-specific identifiers and context. ## 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. - `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)