Create shorts, a promo, or clips
const url = 'https://api.braiv.co/v1/videos/vid_01JZ8M6A/shorts';const options = { method: 'POST', headers: { 'Idempotency-Key': 'import-launch-demo-20260901', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"kind":"shorts","numClips":3,"minDuration":20,"maxDuration":60,"aspectRatio":"9:16","captionStyle":"highlight","captionPosition":"bottom"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/shorts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: import-launch-demo-20260901' \ --data '{ "kind": "shorts", "numClips": 3, "minDuration": 20, "maxDuration": 60, "aspectRatio": "9:16", "captionStyle": "highlight", "captionPosition": "bottom" }'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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Braiv library video document ID.
Example
vid_01JZ8M6AHeader Parameters
Section titled “Header Parameters ”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-20260901Request Body
Section titled “Request Body ”Generate short highlight videos with configurable duration, framing, and captions.
object
Selects short highlight generation. You may omit this field because shorts is the default.
Number of separate highlight videos to generate. Send a JSON integer from 1 to 10.
Shortest acceptable clip length in seconds. Send a JSON number from 15 to 180 that is no greater than maxDuration.
Longest acceptable clip length in seconds. Send a JSON number from 15 to 180 that is no less than minDuration.
Output frame shape: 9:16 is vertical for Shorts, Reels, and
TikTok; 16:9 is landscape; and 1:1 is square.
Visual preset used to burn captions into each clip.
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.
Vertical caption placement: top uses the upper safe area,
middle centres the captions, and bottom uses the lower safe area.
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.
Generate one 45–60 second promotional edit with optional soundtrack.
object
Selects promotional video generation.
Target duration of the finished promo in seconds. Send a JSON number from 45 to 60.
Output frame shape: 9:16 is vertical for mobile feeds and 16:9 is landscape.
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.
Vertical caption placement when captions are enabled: top uses
the upper safe area, middle centres the captions, and bottom
uses the lower safe area.
Set to true to generate and mix background music beneath the dialogue. A soundtrack adds 20 credits to the promo request.
Music style used when includeSoundtrack is true. Send one of
these lowercase values; hip hop and trip hop contain spaces.
orchestral— grand strings, brass, woodwinds, and percussion.cinematic— dramatic, emotional film-score music.synth— synthesizers and modern electronic textures.acoustic— warm guitar, piano, and string instrumentation.pop— catchy melodies 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— electronic drums, digital effects, and EDM-style production.rock— energetic electric guitars, drums, and bass.jazz— saxophone, piano, double bass, drums, and swing rhythms.classical— refined traditional orchestral composition.
An unrecognised value falls back to cinematic.
Generate one to four 5–25 minute landscape excerpts selected from long source media.
object
Selects long-form clip generation.
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.
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.
Vertical caption placement when captions are enabled: top uses
the upper safe area, middle centres the captions, and bottom
uses the lower safe area.
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.
Examples
{ "kind": "shorts", "numClips": 3, "minDuration": 20, "maxDuration": 60, "aspectRatio": "9:16", "captionStyle": "highlight", "captionPosition": "bottom"}{ "kind": "promo", "totalDuration": 60, "aspectRatio": "16:9", "captionStyle": "modern", "captionPosition": "bottom", "includeSoundtrack": true, "soundtrackGenre": "cinematic"}{ "kind": "clips", "numClips": 2, "captionStyle": "modern", "captionPosition": "bottom", "clipSelectionPrompt": "Prioritize practical product demonstrations."}Responses
Section titled “ Responses ”Shorts-family request queued.
object
Created shorts-family request ID.
Pollable shorts job ID.
Credits charged or consumed from escrow.
Remaining account credit balance.
Example
{ "shortsRequestId": "req_01JZA", "jobId": "shorts_req_01JZA", "creditsSpent": 60, "balance": 240}Request fields are missing, malformed, out of bounds, or mutually inconsistent.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Example
{ "error": { "code": "INVALID_ARGUMENT", "message": "The request contains invalid or missing fields.", "details": {} }}A supported authentication header is missing or contains an invalid Public API key.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
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": {} }}Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Examples
{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "The API key lacks the required scope.", "details": {} }}The resource does not exist or is not accessible to the caller.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Example
{ "error": { "code": "NOT_FOUND", "message": "Resource not found.", "details": {} }}The Idempotency-Key was reused with a different path or request body.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Example
{ "error": { "code": "IDEMPOTENCY_REPLAY", "message": "Idempotency-Key was reused with a different request.", "details": { "pathMatch": true, "hashMatch": false } }}The account has insufficient credits, or the request exceeded a rate limit.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Example
{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits.", "details": { "required": 60, "available": 20, "shortfall": 40 } }}An unexpected server error occurred.
object
Structured public API error envelope.
object
Stable machine-readable error code.
Human-readable error summary.
Machine-readable operation-specific context; empty when unavailable.
object
Example
{ "error": { "code": "INTERNAL", "message": "An unexpected error occurred.", "details": {} }}