--- title: "Create shorts, a promo, or clips" method: POST path: "/videos/{videoId}/shorts" tags: ["Shorts"] --- # Create shorts, a promo, or clips `POST /videos/{videoId}/shorts` ## Request - Base URL: `https://api.braiv.co/v1` - URL: `https://api.braiv.co/v1/videos/{videoId}/shorts` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` Queues the selected shorts-family workflow. The request is discriminated by `kind`; fields accepted by one variant are not forwarded to another. Poll `getShorts` until it returns 200 or 422. Required scope: `shorts:write`. ## Path parameters - `videoId` string, required ## Headers - `Idempotency-Key` string ## Request body - union - CreateClipRequest: Generate short highlight videos with configurable duration, framing, and captions. - `kind` 'shorts': Selects short highlight generation. You may omit this field because `shorts` is the default. - `numClips` integer: Number of separate highlight videos to generate. Send a JSON integer from 1 to 10. - `minDuration` number: Shortest acceptable clip length in seconds. Send a JSON number from 15 to 180 that is no greater than `maxDuration`. - `maxDuration` number: Longest acceptable clip length in seconds. Send a JSON number from 15 to 180 that is no less than `minDuration`. - `aspectRatio` '9:16' | '16:9' | '1:1': Output frame shape: `9:16` is vertical for Shorts, Reels, and TikTok; `16:9` is landscape; and `1:1` is square. - `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. - `captionPosition` 'top' | 'middle' | 'bottom': Vertical caption placement within the video frame: `top` uses the upper safe area, `middle` centres the captions, and `bottom` uses the lower safe area. - `clipSelectionPrompt` string: Optional natural-language guidance for choosing moments from the source video. Describe topics, speakers, or moments to prioritise. The value is trimmed, must be no more than 2,000 characters, and an empty string is treated as omitted. - CreatePromoRequest: Generate one 45–60 second promotional edit with optional soundtrack. - `kind` 'promo', required: Selects promotional video generation. - `totalDuration` number: Target duration of the finished promo in seconds. Send a JSON number from 45 to 60. - `aspectRatio` '9:16' | '16:9': Output frame shape: `9:16` is vertical for mobile feeds and `16:9` is landscape. - `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. - `captionPosition` 'top' | 'middle' | 'bottom': Vertical caption placement within the video frame: `top` uses the upper safe area, `middle` centres the captions, and `bottom` uses the lower safe area. - `includeSoundtrack` boolean: Set to `true` to generate and mix background music beneath the dialogue. A soundtrack adds 20 credits to the promo request. - `soundtrackGenre` 'orchestral' | 'cinematic' | 'synth' | 'acoustic' | 'pop' | 'hip hop' | 'ambient' | 'trip hop' | 'electronic' | 'rock' | 'jazz' | 'classical': Music style used when `includeSoundtrack` is `true`. Send the lowercase value exactly as shown; `hip hop` and `trip hop` contain spaces. - `orchestral` — grand arrangements with strings, brass, woodwinds, and percussion. - `cinematic` — dramatic, emotional film-score music that builds tension. - `synth` — modern synthesizers, electronic textures, and digital production. - `acoustic` — warm, organic guitar, piano, and string instrumentation. - `pop` — catchy melodies, modern drums, bass, and accessible high-energy production. - `hip hop` — beats, bass, drums, samples, and urban rhythm. - `ambient` — spacious atmospheric pads with minimal rhythm. - `trip hop` — moody downtempo beats, deep bass, and atmospheric synths. - `electronic` — synthesizers, electronic drums, digital effects, and EDM-style production. - `rock` — energetic electric guitars, drums, and bass. - `jazz` — saxophone, piano, double bass, drums, and a swing or improvisational feel. - `classical` — refined traditional orchestral composition. An unrecognised value falls back to `cinematic`. - CreateLongClipRequest: Generate one to four 5–25 minute landscape excerpts selected from long source media. - `kind` 'clips', required: Selects long-form clip generation. - `numClips` integer: Number of separate long-form excerpts to generate. Send a JSON integer from 1 to 4. Each excerpt is selected within the fixed 5–25 minute duration range; values outside 1–4 are clamped. - `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. - `captionPosition` 'top' | 'middle' | 'bottom': Vertical caption placement within the video frame: `top` uses the upper safe area, `middle` centres the captions, and `bottom` uses the lower safe area. - `clipSelectionPrompt` string: Optional natural-language guidance for choosing long-form excerpts. Describe the topic, speaker, or narrative section to prioritise. The value is trimmed, must be no more than 2,000 characters, and an empty string is treated as omitted. ## Response `202` Shorts-family request queued. - CreateShortsResponse - `shortsRequestId` string, required: Created shorts-family request ID. - `jobId` string, required: Pollable shorts job ID. - `creditsSpent` number, required: Credits charged or consumed from escrow. - `balance` number, required: Remaining account credit balance. ## 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)