See captions on the real video before paying for a burn. mode sample: FREE contact sheet comparing up to 12 presets on real frames (no transcription, 30 sheets/hour); returns sheetUrl, per-preset frames and captionVideoArgs to pass to caption_video. mode still (default): one preset as a PNG exactly as burn_captions draws it; mode clip: an MP4 of up to 5 s. still and clip cost at most 1 credit flat and need captions (subtitles or transcriptionJobId). Media: mediaUrl/sourceUrl or fileId.
View input schema
{
"type": "object",
"properties": {
"mode": {
"description": "sample: FREE contact sheet comparing up to 12 presets on the real frame, never charges. still (default): one preset as a PNG, at most 1 credit. clip: one preset as an MP4 of up to 5 s, at most 1 credit.",
"type": "string",
"enum": [
"sample",
"still",
"clip"
]
},
"mediaUrl": {
"description": "Public https link to the video or audio (direct file, chat attachment URL, Google Drive or Dropbox share link; YouTube is refused). Pass this or fileId.",
"anyOf": [
{
"description": "Public https link to the video or audio (direct file, chat attachment URL, Google Drive or Dropbox share link; YouTube is refused). Pass this or fileId.",
"type": "string"
},
{
"description": "Alias of sourceUrl.",
"type": "string"
}
]
},
"fileId": {
"description": "Id of a file already uploaded with upload {action:'start'}, upload {action:'start_multipart'}, upload {action:'inline'} or import_url. Pass this or the media URL.",
"type": "string"
},
"subtitles": {
"description": "Existing captions as SRT, WebVTT or AwesomeVideo JSON text. Skips transcription (no transcription charge).",
"anyOf": [
{
"description": "Existing captions as SRT, WebVTT or AwesomeVideo JSON text. Skips transcription (no transcription charge).",
"type": "string"
},
{
"description": "Preview only: SRT/VTT/JSON captions to show instead of a sample phrase.",
"type": "string"
}
]
},
"transcriptionJobId": {
"description": "Id of a finished transcribe or caption_video job whose transcript to reuse (no new transcription charge).",
"anyOf": [
{
"description": "Id of a finished transcribe or caption_video job whose transcript to reuse (no new transcription charge).",
"type": "string"
},
{
"description": "Preview only: show real captions from this transcription (no new transcription).",
"type": "string"
}
]
},
"preset": {
"description": "Caption preset: id, slug or name from get_catalog {kind:'presets'} (e.g. 'hormozi-style', 'Clarity') or custom:cp_... from manage_preset {action:'create', type:'custom'}.",
"anyOf": [
{
"description": "Caption preset: id, slug or name from get_catalog {kind:'presets'} (e.g. 'hormozi-style', 'Clarity') or custom:cp_... from manage_preset {action:'create', type:'custom'}.",
"type": "string"
},
{
"description": "One preset (same as caption_video).",
"type": "string"
}
]
},
"presetId": {
"description": "Same as preset (kept for older clients): a preset id from get_catalog {kind:'presets'} or custom:cp_....",
"type": "string"
},
"brandPresetId": {
"description": "Id from manage_preset {action:'create', type:'brand'}: applies its font, color, position and logo on top of the preset.",
"type": "string"
},
"styleOverrides": {
"description": "Per-call style changes deep-merged onto the preset (same fields as get_catalog {kind:'presets'} style; null removes a field), validated with the renderer schema and bundled fonts. Example {\"fontSize\":72,\"maxWordsPerCaption\":2,\"wordEntrance\":\"bounce\"}. Same price. No need to manage_preset {action:'create', type:'custom'}. Every field with examples: get_catalog {kind:'styles'}.",
"anyOf": [
{
"description": "Per-call style changes deep-merged onto the preset (same fields as get_catalog {kind:'presets'} style; null removes a field), validated with the renderer schema and bundled fonts. Example {\"fontSize\":72,\"maxWordsPerCaption\":2,\"wordEntrance\":\"bounce\"}. Same price. No need to manage_preset {action:'create', type:'custom'}. Every field with examples: get_catalog {kind:'styles'}.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"description": "Same as caption_video, applied to every preset.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
]
},
"faceAvoid": {
"description": "true = move captions off faces (samples faces at 2 fps, same price; result.faceAvoid.faceLayout). Shortcut for styleOverrides.faceAvoid.",
"anyOf": [
{
"description": "true = move captions off faces (samples faces at 2 fps, same price; result.faceAvoid.faceLayout). Shortcut for styleOverrides.faceAvoid.",
"type": "boolean"
},
{
"description": "true = move captions off faces (samples faces at 2 fps, same price).",
"type": "boolean"
}
]
},
"highlightWords": {
"description": "Shortcut: words or phrases to color in every caption (accent/case-insensitive), e.g. [\"AwesomeVideo\", \"gratis\"]. Maps to styleOverrides.wordHighlights rule {id:\"custom\", words, color}; on highlighter-marker, ghost-keywords and brand-box it fills their keyword list in the preset colors. Same price.",
"anyOf": [
{
"description": "Shortcut: words or phrases to color in every caption (accent/case-insensitive), e.g. [\"AwesomeVideo\", \"gratis\"]. Maps to styleOverrides.wordHighlights rule {id:\"custom\", words, color}; on highlighter-marker, ghost-keywords and brand-box it fills their keyword list in the preset colors. Same price.",
"maxItems": 200,
"type": "array",
"items": {
"type": "string"
}
},
{
"description": "Words or phrases to color in every caption (accent- and case-insensitive), max 200. Fills the keyword list of highlighter-marker, ghost-keywords and brand-box in their own colors.",
"maxItems": 200,
"type": "array",
"items": {
"type": "string"
}
}
]
},
"highlightColor": {
"description": "#RRGGBB for highlightWords. Default #FACC15.",
"anyOf": [
{
"description": "#RRGGBB for highlightWords. Default #FACC15.",
"type": "string"
},
{
"description": "#RRGGBB color for highlightWords. Default #FACC15 (keyword presets keep their own color).",
"type": "string"
}
]
},
"atSeconds": {
"description": "Second of the video for the frame (or clip start). Default 0.",
"anyOf": [
{
"description": "Second of the video for the frame (or clip start). Default 0.",
"type": "number",
"minimum": 0
},
{
"description": "Preview only: second(s) of the video to show; up to 3 = one sheet.",
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "number",
"minimum": 0
}
}
]
}
]
},
"clipSeconds": {
"description": "Clip length for mode clip, 0.5-5 seconds. Default 5.",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 5
},
"maxCredits": {
"description": "Spending cap for this call in credits (1 credit = 1 cent). If the price is higher the call fails with 422 before charging.",
"type": "number",
"minimum": 0
},
"platform": {
"description": "Where the video will be posted: tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube, x (aliases like reels, instagram, shorts, snap, twitter; case-insensitive). Keeps captions out of that app's buttons and text. If the user says \"para TikTok\" / \"for Reels\", pass it; if they did not say and it matters, ask. Same price. Unknown values return 422 invalid_platform before any charge. See get_catalog {kind:'platforms'}.",
"anyOf": [
{
"description": "Where the video will be posted: tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube, x (aliases like reels, instagram, shorts, snap, twitter; case-insensitive). Keeps captions out of that app's buttons and text. If the user says \"para TikTok\" / \"for Reels\", pass it; if they did not say and it matters, ask. Same price. Unknown values return 422 invalid_platform before any charge. See get_catalog {kind:'platforms'}.",
"type": "string"
},
{
"description": "Where the video will be posted (tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube, x; aliases like reels, shorts, twitter). Keeps captions inside that app's safe zone at the same price.",
"type": "string"
}
]
},
"autoFit": {
"description": "Default true: caption size, words per caption (4 on 9:16, 5 on 1:1, 7 on 16:9), and a default safe zone follow the video shape, so text reads the same at 720p and 1080p and stays clear of app UI. Pass false only when the user wants the preset's exact fixed pixel sizes. Same price.",
"anyOf": [
{
"description": "Default true: caption size, words per caption (4 on 9:16, 5 on 1:1, 7 on 16:9), and a default safe zone follow the video shape, so text reads the same at 720p and 1080p and stays clear of app UI. Pass false only when the user wants the preset's exact fixed pixel sizes. Same price.",
"type": "boolean"
},
{
"description": "Default true: caption size, words per caption and a safe zone follow the video shape. false keeps the preset's exact sizes.",
"type": "boolean"
}
]
},
"sourceUrl": {
"description": "Same as caption_video.",
"type": "string"
},
"presets": {
"description": "Up to 12 presets to compare; default 6 that fit the video shape.",
"maxItems": 12,
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"description": "Spoken language (ISO 639-1) for the quick transcript of the sampled seconds. Omit to auto-detect.",
"type": "string"
},
"translateTo": {
"description": "Same as caption_video; the default sample phrase uses this language.",
"type": "string"
},
"audioVisual": {
"description": "Audio-only input (mp3, m4a, wav...): an editorial podcast design plus captions, drawn on the server by the web editor's own code, same price as the burn. {variant: swiss-grid | braun-radio | riso | editorial-cover | bauhaus | continuous-line | vinyl | type-wave | duotone-portrait | ma (default editorial-cover), showName (<=60), episode (<=12), speaker (<=60), coverImageUrl (https) or coverFileId (PNG/JPEG/WebP <=5 MB; shown by vinyl, duotone-portrait), background/accent/ink (#hex; ink auto from paper), captionMode integrated (default: the design typesets the captions) | preset (your caption preset draws), contrastGuard (default true), aspect 9:16|16:9|1:1|4:5 or width+height, overlays (<=8)}. Retired ids still work as aliases with a warning: bars→swiss-grid, ribbon→continuous-line, rings→ma, spectrogram→riso, skyline→bauhaus, silkline→type-wave, ivory→editorial-cover, halo→vinyl, needle→braun-radio, mono→duotone-portrait. On a video input: 422 audio_visual_needs_audio_input, not charged. Catalog: GET /v1/audio-visuals (MCP get_catalog {kind:'audio_visuals'}), free.",
"type": "object",
"properties": {
"variant": {
"description": "Design id: swiss-grid | braun-radio | riso | editorial-cover | bauhaus | continuous-line | vinyl | type-wave | duotone-portrait | ma (default editorial-cover). Retired ids still work as aliases with a warning: bars→swiss-grid, ribbon→continuous-line, rings→ma, spectrogram→riso, skyline→bauhaus, silkline→type-wave, ivory→editorial-cover, halo→vinyl, needle→braun-radio, mono→duotone-portrait. get_catalog {kind:'audio_visuals'} describes each design.",
"type": "string"
},
"showName": {
"description": "Show / podcast name (max 60). Empty: left out (mastheads fall back to Podcast).",
"type": "string",
"maxLength": 60
},
"episode": {
"description": "Episode label or number (max 12 chars), printed after Nº. Empty: left out.",
"anyOf": [
{
"type": "string",
"maxLength": 12
},
{
"type": "number"
}
]
},
"speaker": {
"description": "Speaker / host name for bylines (max 60). Empty: left out.",
"type": "string",
"maxLength": 60
},
"coverImageUrl": {
"description": "Public https PNG/JPEG/WebP (max 5 MB) for the cover/host image slot (vinyl, duotone-portrait). Fetched before any charge.",
"type": "string"
},
"coverFileId": {
"description": "Same as coverImageUrl but a fileId from upload {action:'start'}.",
"type": "string"
},
"background": {
"description": "Paper colour #rgb/#rrggbb (default: the design's). Ink switches automatically for contrast.",
"type": "string"
},
"accent": {
"description": "Accent colour #hex (spoken word, needle, seal...). Default: the design's.",
"type": "string"
},
"ink": {
"description": "Text/line colour #hex. Default: the design's, or auto from the paper.",
"type": "string"
},
"captionMode": {
"description": "integrated (default): the design typesets the captions word by word; preset: your caption preset draws them.",
"type": "string",
"enum": [
"integrated",
"preset"
]
},
"contrastGuard": {
"description": "Preset mode (default true): white text on a light design switches to the design's ink so it stays legible.",
"type": "boolean"
},
"enabled": {
"description": "false: paper + captions, no design.",
"type": "boolean"
},
"aspect": {
"description": "Frame shape; default from platform, else 9:16.",
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1",
"4:5"
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"overlays": {
"description": "Up to 8 image (imageUrl, PNG/JPEG/WebP <=5 MB) or text items {kind, x, y, width, height, start, end, ...} in frame pixels.",
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": {}
},
"text": {
"description": "Preview only: sample phrase.",
"type": "string",
"maxLength": 80
},
"fullText": {
"description": "Preview only: show all words in one caption (does not match a burn).",
"type": "boolean"
},
"api_key": {
"type": "string",
"description": "Only for a connection without an Authorization header: the token create_key returned (av_live_...). Pass it on every call to use that key in this same session, no reconnect or config change. Ignored when the connection already sends a key. It works like a password: create a new key if this conversation is shared."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}