--- title: "Import or reserve a video" method: POST path: "/videos" tags: ["Videos"] --- # Import or reserve a video `POST /videos` ## Request - Base URL: `https://api.braiv.co/v1` - URL: `https://api.braiv.co/v1/videos` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` Creates a library video from a supported URL, direct HTTPS asset, or client upload reservation. URL imports begin immediately. For `upload`, use the returned object path and completion route with `createVideoUpload`. Optional product recipes are staged to run after ingest prerequisites. `products.packaging.thumbnail` accepts `true`/`{}` (faceless Creative) or the full zero-prompt object (Creative `thumbnail-v2` or Precision `thumbnail-precision`, including opaque key-moment detect). Optional `folderId` places the video in an existing Studio folder in the same personal or workspace library. Create folders with `POST /folders` or in Studio. Unknown or inaccessible folders return 404. Required scope: `videos:write`. ## Headers - `Idempotency-Key` string ## Request body - CreateVideoRequest - `source` union, required - UploadVideoSource - `type` 'upload', required: Reserves server-authoritative object storage for a client upload. - `fileName` string: Upload display/object filename; defaults to `upload.mp4`. Path separators are rejected. - `contentType` string: Upload MIME type; `audio/*` selects the audio ingest lane. - ProviderVideoSource - `type` 'youtube' | 'dropbox' | 'google_drive', required: Provider that owns the URL: - `youtube` — a YouTube watch or share URL. - `dropbox` — a publicly accessible Dropbox share URL. - `google_drive` — a publicly accessible Google Drive share URL. The value must match the provider represented by `url`. - `url` string, uri, required: Provider share or watch URL. - HttpsVideoSource - `type` 'https', required: Direct HTTPS fetch. - `url` string, uri, required: Publicly fetchable HTTPS media URL. - `workspaceId` string: Destination workspace. Omit for the caller's personal library. - `folderId` string: Existing Studio folder id in the same library as the import. The video is added to that folder (`UserVideos.tags`). Create folders with POST /folders or in Studio. - `products` ImportProducts: Work staged to begin after the source reaches the required ingest state. - `dubs` ImportDubRecipe[]: Dub recipes grouped by product and target languages. - `languages` LanguageCode[], required: Unique target languages to dub. - `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. - `shorts` ImportShortsRecipe - `kind` 'shorts' | 'promo' | 'clips': Output to generate after transcription: `shorts` creates short highlights, `promo` creates one 45–60 second promotional edit, and `clips` creates 5–25 minute landscape excerpts. - `numClips` number: Number of outputs requested. The import parser rounds this value; shorts requests support 1–10, while clips execution clamps it to 1–4. Promo requests always create one output. - `minDuration` number: Minimum length of each `shorts` output in seconds. It must be no greater than `maxDuration`; promo and clips workflows use their own duration rules. - `maxDuration` number: Maximum length of each `shorts` output in seconds. It must be no less than `minDuration`; promo and clips workflows use their own duration rules. - `aspectRatio` '9:16' | '16:9' | '1:1': Output frame shape: `9:16` is vertical, `16:9` is landscape, and `1:1` is square. Promos support `9:16` and `16:9`; clips are always generated in `16:9`. - `captionStyle` 'default' | 'karaoke' | 'modern' | 'impact' | 'subtle' | 'highlight' | 'pro_highlight': Visual preset used to burn captions into the generated video. - `default` — uppercase text with an outline and soft shadow. - `karaoke` — uppercase text that progressively highlights words as they are spoken. - `modern` — uppercase text that highlights the currently spoken word. - `impact` — one large uppercase word at a time with a hard shadow. - `subtle` — smaller mixed-case text on a semi-transparent dark background. - `highlight` — the current word appears on a solid highlight-colour box while surrounding words are dimmed. - `pro_highlight` — a compact, outline-free single-word highlight treatment. - `clipSelectionPrompt` string: Natural-language guidance describing topics, speakers, or moments to prioritise when selecting clips. - `packaging` ImportPackagingRecipe - `title` ImportTitleRecipe - `style` 'funny' | 'scary' | 'informational' | 'mysterious' | 'clickbait': Tone used for the generated title: - `funny` — light, clever, or relatable framing. - `scary` — warning, risk, or mistake-to-avoid framing. - `informational` — direct benefit, how-to, or structured-value framing. - `mysterious` — curiosity-gap framing that withholds the payoff. - `clickbait` — bold, high-energy framing using authority or superlatives. - `description` ImportDescriptionRecipe - `type` 'youtube-description' | 'social-post' | 'how-to-guide' | 'blog-post' | 'video-summary': Format used for generated copy: - `youtube-description` — an SEO-oriented YouTube description with chapters, hashtags, and tags. - `social-post` — a concise social post with a hook, takeaways, and hashtags. - `how-to-guide` — a step-by-step Markdown guide with timestamped instructions. - `blog-post` — a long-form Markdown article based on the video. - `video-summary` — a timestamped narrative summary with speaker attribution. - `thumbnail` union: Enables a zero-prompt thumbnail after ingest. `true` or `{}` is faceless Creative (`thumbnail-v2`, no characters). A full object uses the same fields as packaging `zeroPromptThumbnail`; `enabled` defaults to true. Creative uses character subjects; Precision (`pipelineMode: thumbnail-precision`) uses content plates or `autoDetectContentReferences` (opaque key-moment detect). - true: Faceless Creative zero-prompt (`characterCount: 0`). - object: Empty object — same as `{enabled: true}`. - 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` Video accepted. Poll the returned jobs; upload reservations also include upload instructions. - CreateVideoResponse - `videoId` string, required: Created library video ID. - `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. - `video` Video - `id` string, required: Library video ID. - `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. - `title` string: Current video title. - `description` string: Current video description. - `duration` number: Media duration in seconds. - `posterUrl` string, uri: Current poster image URL. - `provider` string: Internal source provider label. - `mediaType` 'video' | 'audio': Ingested media kind. - `defaultLanguageCode` string: ISO-style language or locale code accepted by the underlying product. - `url` string, uri: Primary playback URL when available. - `urlMulti` object: Playback URLs keyed by language code. - `workspaceId` string: Owning workspace, if any. - `folderIds` string[]: Studio folder ids this video belongs to (`UserVideos.tags`). - `createdAt` string, date-time: ISO creation timestamp. - `import` VideoStatusRef - `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. - `language` string: ISO-style language or locale code accepted by the underlying product. - `transcript` VideoStatusRef - `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. - `language` string: ISO-style language or locale code accepted by the underlying product. - `upload` object: Upload reservation instructions returned only for upload sources. - `objectPath` string, required: Server-authoritative destination object path. - `complete` string, required: Relative route used to create the upload session. - `jobs` Job[], required: Import, transcript, and recipe jobs to poll. - `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 source already exists, or the idempotency key was reused for a different request. - `422`: The source provider is unsupported or its duration cannot be resolved. - `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)