# AwesomeVideo > Browser video editor with styled, animated captions, plus a prepaid API and MCP server for agents. - API docs for agents: https://api.awesomevideoeditor.com/llms.txt (everything in one file: https://api.awesomevideoeditor.com/llms-full.txt or https://awesomevideoeditor.com/llms-full.txt) - OpenAPI: https://api.awesomevideoeditor.com/openapi.json - MCP (Streamable HTTP): https://api.awesomevideoeditor.com/mcp (server card: https://api.awesomevideoeditor.com/.well-known/mcp.json) - MCP with OAuth 2.1 (Claude, ChatGPT, Le Chat, agent platforms with custom connectors): https://api.awesomevideoeditor.com/mcp/oauth (discovery: https://api.awesomevideoeditor.com/.well-known/oauth-authorization-server) - Pricing: https://awesomevideoeditor.com/pricing (live JSON: https://api.awesomevideoeditor.com/v1/pricing) - Account and API keys: https://awesomevideoeditor.com/account (Trusted clients only: pasting an av_live_ key into a third-party web client exposes it to that site.) - Facts (short, citable: what it is, prices, endpoints, limits, welcome credits): https://awesomevideoeditor.com/facts - Best caption APIs and MCP servers for AI agents: https://awesomevideoeditor.com/best-caption-apis-for-ai-agents - MCP setup guides: https://awesomevideoeditor.com/mcp, https://awesomevideoeditor.com/mcp/claude, https://awesomevideoeditor.com/mcp/cursor, https://awesomevideoeditor.com/mcp/chatgpt, https://awesomevideoeditor.com/mcp/le-chat, https://awesomevideoeditor.com/mcp/manus - One-click install, keyless (then call create_key): Cursor cursor://anysphere.cursor-deeplink/mcp/install?name=awesomevideo&config=eyJ1cmwiOiJodHRwczovL2FwaS5hd2Vzb21ldmlkZW9lZGl0b3IuY29tL21jcD92aWE9YnRuLWN1cnNvciJ9 ; VS Code https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522awesomevideo%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.awesomevideoeditor.com%252Fmcp%253Fvia%255Cu003dbtn-vscode%2522%257D ; VS Code Insiders https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522awesomevideo%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.awesomevideoeditor.com%252Fmcp%253Fvia%255Cu003dbtn-vscode%2522%257D - Caption API (curl, prices): https://awesomevideoeditor.com/api/captions - Add subtitles to a video with an API: burn your own SRT/VTT or caption automatically (curl, MCP, real responses): https://awesomevideoeditor.com/guides/add-subtitles-to-video-api - Add subtitles to a video with Claude: custom connector or Claude Code, what to ask, real tool result: https://awesomevideoeditor.com/guides/add-subtitles-to-video-with-claude - API alternatives: https://awesomevideoeditor.com/zapcap-alternative, https://awesomevideoeditor.com/veed-api-alternative, https://awesomevideoeditor.com/submagic-api-alternative, https://awesomevideoeditor.com/captions-ai-api-alternative, https://awesomevideoeditor.com/ffmpeg-subtitles-alternative; price-per-minute table: https://awesomevideoeditor.com/caption-api-comparison - Caption styles with real renders and exact caption_video params: https://awesomevideoeditor.com/styles (hormozi-style, mrbeast-style, karaoke, pop-words, beast-one-word, highlighter-marker, number-punch, smart-pop at /styles/) - n8n auto captions workflow (importable JSON, no community node): https://awesomevideoeditor.com/integrations/n8n - Make.com auto captions recipe (one HTTP module, no FFmpeg): https://awesomevideoeditor.com/integrations/make - Free subtitle toolbox (shift timings, validate, WPM, convert; in the browser, no upload, no key): https://awesomevideoeditor.com/tools/subtitles — plus converters https://awesomevideoeditor.com/tools/vtt-to-srt (WebVTT to SRT), https://awesomevideoeditor.com/tools/srt-to-vtt (SRT to WebVTT), https://awesomevideoeditor.com/tools/srt-to-txt (SRT or VTT to a plain-text transcript); index: https://awesomevideoeditor.com/tools ## Every page on awesomevideoeditor.com - For agents and developers: agent recipes https://awesomevideoeditor.com/agents, caption API https://awesomevideoeditor.com/api/captions, add subtitles to a video with an API (own SRT or automatic) https://awesomevideoeditor.com/guides/add-subtitles-to-video-api, add subtitles to a video with Claude (connector or Claude Code) https://awesomevideoeditor.com/guides/add-subtitles-to-video-with-claude, MCP server https://awesomevideoeditor.com/mcp, MCP in Claude https://awesomevideoeditor.com/mcp/claude, MCP in Cursor https://awesomevideoeditor.com/mcp/cursor, MCP in ChatGPT https://awesomevideoeditor.com/mcp/chatgpt, MCP in Mistral Le Chat https://awesomevideoeditor.com/mcp/le-chat, MCP in Manus https://awesomevideoeditor.com/mcp/manus, n8n workflow https://awesomevideoeditor.com/integrations/n8n, Make.com recipe https://awesomevideoeditor.com/integrations/make, audio-to-video designs https://awesomevideoeditor.com/audio-visuals, pricing https://awesomevideoeditor.com/pricing, facts https://awesomevideoeditor.com/facts - Caption API comparisons: best caption APIs for agents https://awesomevideoeditor.com/best-caption-apis-for-ai-agents, price per minute https://awesomevideoeditor.com/caption-api-comparison, ZapCap API https://awesomevideoeditor.com/zapcap-alternative, VEED Subtitles API https://awesomevideoeditor.com/veed-api-alternative, Submagic API https://awesomevideoeditor.com/submagic-api-alternative, Captions.ai API https://awesomevideoeditor.com/captions-ai-api-alternative, FFmpeg subtitles https://awesomevideoeditor.com/ffmpeg-subtitles-alternative - Caption styles (8-second renders and exact params): all styles https://awesomevideoeditor.com/styles, Hormozi https://awesomevideoeditor.com/styles/hormozi-style, MrBeast https://awesomevideoeditor.com/styles/mrbeast-style, karaoke https://awesomevideoeditor.com/styles/karaoke, pop words https://awesomevideoeditor.com/styles/pop-words, one word at a time https://awesomevideoeditor.com/styles/beast-one-word, highlighter marker https://awesomevideoeditor.com/styles/highlighter-marker, number punch https://awesomevideoeditor.com/styles/number-punch, smart pop https://awesomevideoeditor.com/styles/smart-pop - Free browser editor (no account, no watermark): home https://awesomevideoeditor.com, subtitle generator https://awesomevideoeditor.com/subtitle-generator, video captions https://awesomevideoeditor.com/video-captions, audio to subtitles (MP3 to SRT, VTT or MP4) https://awesomevideoeditor.com/audio-to-subtitles, TikTok captions https://awesomevideoeditor.com/tiktok-captions, Instagram Reels captions https://awesomevideoeditor.com/instagram-captions, YouTube Shorts captions https://awesomevideoeditor.com/youtube-shorts-captions, caption up to 50 videos at once https://awesomevideoeditor.com/batch, community presets https://awesomevideoeditor.com/presets - Free subtitle tools (in the browser, no upload): all tools https://awesomevideoeditor.com/tools, subtitle toolbox https://awesomevideoeditor.com/tools/subtitles, VTT to SRT https://awesomevideoeditor.com/tools/vtt-to-srt, SRT to VTT https://awesomevideoeditor.com/tools/srt-to-vtt, SRT to TXT https://awesomevideoeditor.com/tools/srt-to-txt - Editor alternatives: CapCut https://awesomevideoeditor.com/capcut-alternative, Captions app https://awesomevideoeditor.com/captions-ai-alternative, Descript https://awesomevideoeditor.com/descript-alternative, Kapwing https://awesomevideoeditor.com/kapwing-alternative, Opus Clip https://awesomevideoeditor.com/opus-clip-alternative, Submagic https://awesomevideoeditor.com/submagic-alternative, VEED https://awesomevideoeditor.com/veed-alternative - En español: subtítulos para video https://awesomevideoeditor.com/es/video-captions, audio a subtítulos (MP3 a SRT, VTT o MP4) https://awesomevideoeditor.com/es/audio-to-subtitles, TikTok https://awesomevideoeditor.com/es/tiktok-captions, Instagram Reels https://awesomevideoeditor.com/es/instagram-captions, YouTube Shorts https://awesomevideoeditor.com/es/youtube-shorts-captions - Help: support https://awesomevideoeditor.com/support MCP without a key (connect to https://api.awesomevideoeditor.com/mcp): First job, no sign-in: 1) create_key {} (free): returns your token once. While today's starters last (a few per day) it already has 5 free welcomeCredits, enough for the sample, no challenge; otherwise welcomeCredits is 0 plus a welcomeChallenge. 2) Add "api_key": "" to the arguments of every next call (same session, no reconnect; or send Authorization: Bearer ). Only if welcomeCredits is 0: solve the challenge (SHA-256 proof-of-work, about 1-3 s) and call create_key {api_key, challenge, nonce} to claim 10 free welcome credits while the trial runs. 3) caption_video {"sourceUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "preset": "hormozi-pop"}: the 8 s sample costs 2 credits and returns the MP4, SRT and VTT. Then use your own public link or a fileId. Subtitles in one call: MCP `caption_video` (REST POST https://api.awesomevideoeditor.com/v1/captions) takes a public link (`sourceUrl`: direct file, chat attachment, Google Drive, Dropbox) or an uploaded `fileId`, transcribes, optionally translates (`translateTo`), burns, and returns the MP4 plus SRT/VTT. `platform` and `review: true` (link first, burn charged on approval) work here too. 5 credits per minute (7 with translation), the sum of the steps. YouTube links are not downloaded; upload the file instead. `import_url` (free) turns a public link into a `fileId`. Files up to 2048 MB: free resumable multipart upload, MCP `upload {action:'start_multipart'}` (REST POST https://api.awesomevideoeditor.com/v1/uploads/multipart) returns one PUT url per part; `upload {action:'status'}` lists missing parts after an interruption; `upload {action:'complete'}` assembles it (walkthrough in llms-full.txt). Every job view has `step`, `progress` (0-100, burn uses real ffmpeg progress), `eta_seconds`, `estimatedCompletionAt`, and `pollAfterSeconds`; a caption_video job that failed after transcribing can be resumed with `resume_job` (REST POST https://api.awesomevideoeditor.com/v1/jobs/{id}/resume), which reuses the transcript and charges only the remaining steps. Platform safe zones: pass `platform` (tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube, x; aliases reels, shorts, instagram...) to burn_captions, shorts, preview, or burn_captions {mode:'client_script'} so captions avoid that app's buttons and text. Same price. GET https://api.awesomevideoeditor.com/v1/platforms (free, no key; MCP get_catalog {kind:'platforms'}) lists them with margins. Caption autoFit (default on): size, words per caption (4 on 9:16, 5 on 1:1, 7 on 16:9), and a default safe zone (9:16 bottom 35%/top 15%/left 8%/right 15%, clear of TikTok, Reels and Shorts UI; 1:1 bottom 12%; 16:9 bottom 7%) follow the video shape, so a preset reads the same at 720p and 1080p. An explicit `platform` wins. Pass `autoFit: false` to burn_captions, caption_video, preview, shorts, burn_captions {mode:'client_script'}, or request_review for the preset's exact fixed pixel sizes. Same price. The web editor applies the identical rule. Caption forms (style fields, web and server identical): `maxWordsPerCaption` 1-8 (1 = one big word at a time) always wins over autoFit's words cap. `activeWordReflow: true` stops a scaled active word from overlapping its neighbours; `wordEntrance` bounce/slide-up/fade animates each word when spoken. `positionMode` cycle (top/middle/bottom by caption) or keyword (`positionKeywords` → `keywordPosition`) moves captions inside the safe zone. `captionLayout: "stacked"` stacks one word per line with a bigger hero word (`posterHeroScale`). `faceAvoid: true` moves captions off detected faces; the burn result returns `faceAvoid.faceLayout` to store as `style.faceLayout`. Dub voices: GET https://api.awesomevideoeditor.com/v1/voices (free, no key; MCP get_catalog {kind:'voices'}) lists every voice with a short MP3 sample; pass its id as `voice` to dub or plan. Human review: after transcribe, `request_review` (MCP) or POST /v1/reviews returns a private web-editor link (no login, up to 7 days). The person edits and approves; only then the burn runs and is charged. With `webhookUrl`/`notifyEmail` you get signed `review.approved`, `review.rejected` (with note) and `review.expired` events, once each. Saved glossary (`update_glossary {action:'save'}`, /v1/glossary, free) fixes brand names and slang in every transcription. Long video to short clips: MCP `create_clips` (REST POST https://api.awesomevideoeditor.com/v1/clips) transcribes, lets an LLM pick 1-10 self-contained moments (default 3, 15-60 s, snapped to sentence boundaries), and returns each as an MP4 (9:16 crop that follows the speaker by default, `reframe` center or none) with optional burned captions in any preset, plus title, hook, reason and score per clip. Price: 1 credit per source minute (transcription) + 1 per 10 source minutes + 3 per output minute; a 30-minute video with 3 clips is at most 42 credits. Custom presets: agents can design and save their own full caption style (free). MCP `manage_preset {action:'create', type:'custom'}` (REST POST https://api.awesomevideoeditor.com/v1/custom-presets) takes `style` (the same JSON `get_catalog {kind:'presets'}` returns) or `basePreset` + `overrides`, validates it (422 `invalid_style` lists the bad fields; fonts limited to the bundled Inter, Poppins, Oswald, Roboto, Anton, Bebas Neue, Playfair Display, Caveat, IBM Plex Mono), and returns `custom:cp_...` to pass as `preset` to burn_captions, caption_video, preview, shorts, or burn_captions {mode:'client_script'}. Up to 50 per key or account. `manage_preset {action:'submit'}` proposes one for the public community gallery; it appears in `get_catalog {kind:'presets'}` only after a human moderator approves it. Built-in caption presets (34; pass as `preset`, e.g. `builtin:beast-glow`): clarity, neon-glow, highlight, hormozi-style, mrbeast-style, sleek-caps, epic-lines, bubble-talk, power-play, sharp-notes, retro-glow, tiktok-vertical, karaoke, pop-words, frosted, editorial, handwritten, terminal, color-burst, iman-lowercase, beast-glow, signature-gold, beast-one-word, hormozi-pop, poster-hero, bounce-chunks, zone-jumper, podcast-karaoke, highlighter-marker, ghost-keywords, number-punch, smart-pop, brand-box, cycle-spotlight. New: `iman-lowercase` (clean lowercase Inter, the spoken word turns bold), `beast-glow` (white Bebas Neue caps, black outline, green glow, the spoken word in neon green), `signature-gold` (gold Caveat script, centered, the spoken word in pale cream). Caption-form presets: `beast-one-word` (one giant Anton word at a time, bounce entrance, active word yellow), `hormozi-pop` (3 Poppins caps words, the active word grows green and reflows its neighbours), `poster-hero` (stacked Anton poster, the active word is the big orange hero line), `bounce-chunks` (white Inter with black outline, 3 words, each bounces in), `zone-jumper` (Oswald caps chunks alternating center and bottom, active word sky blue), `podcast-karaoke` (left-aligned white Inter in 2-3 full lines, words light up as spoken). Highlight presets: `highlighter-marker` (yellow marker behind your keywords), `ghost-keywords` (faint upcoming words, keywords in cyan), `brand-box` (dark box, brand words on a violet tag), `number-punch` (numbers boxed in green, long words green), `smart-pop` (the key word of each line pops in yellow), `cycle-spotlight` (stacked caps cycling white, yellow, pink). Keywords come from `highlightWords` (no demo words built in): highlighter-marker, ghost-keywords and brand-box color exactly those words in their own colors (`highlightColor` recolors them); without `highlightWords` they show no keyword highlight. number-punch, smart-pop and cycle-spotlight need no words (numbers, word length and smart emphasis). Example: {"preset":"highlighter-marker","highlightWords":["free","today"]}. Per-call style (no saved preset needed): caption_video, burn_captions, preview, shorts, create_clips, remove_silences (with burnCaptions), translate with burn, batch items, request_review and burn_captions {mode:'client_script'} (REST: the same body fields on POST /v1/captions, /v1/captions/burn, /v1/captions/preview, /v1/shorts, /v1/clips, /v1/trim, /v1/translate, /v1/batch, /v1/reviews, /v1/captions/prepare) accept `styleOverrides` (style fields deep-merged onto the preset, null removes a field, validated like custom presets with bundled fonts only; 422 `invalid_style` lists bad fields) and `faceAvoid: true` (shortcut for styleOverrides.faceAvoid: captions move off faces, sampled at 2 fps; the result returns `faceAvoid.faceLayout`). Same price. Example: `{"sourceUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "preset": "builtin:hormozi-pop", "faceAvoid": true, "styleOverrides": {"fontSize": 72, "maxWordsPerCaption": 2, "wordEntrance": "bounce", "wordStateStyles": {"active": {"color": "#FACC15"}}}}`. Caption-form fields: maxWordsPerCaption (1-N words per caption), activeWordReflow (grown active word pushes neighbours), wordEntrance (bounce, slide-up, fade) + wordEntranceDuration, positionMode (cycle with positionCycle, keyword with positionKeywords + keywordPosition), captionLayout "stacked" + posterHeroScale, faceAvoid. Preview before ordering, free: MCP `preview {mode:'sample'}` (REST POST https://api.awesomevideoeditor.com/v1/captions/style-preview) never charges and never transcribes. It takes the same look fields as `caption_video` (sourceUrl/fileId, preset or presets (up to 12; default 6 for the video shape), language, translateTo, brandPresetId, styleOverrides, faceAvoid, highlightWords, highlightColor, platform, autoFit) plus preview-only `text` (sample phrase, max 80 chars), `fullText`, `atSeconds` (one second or up to 3, one sheet row each; default a frame with a face, else the middle) and `transcriptionJobId`/`subtitles` (show the real caption at that second). Each preset is rendered exactly like the burn: same output size, autoFit sizing, words per caption, safe zone, face avoidance and engine, on the real frame. If the text is longer than one caption you see the chunk on screen at that second (`truncated: true`), like the burn; `fullText: true` shows every line but no longer matches a burn. Response: `sheetUrl` (labeled contact sheet), `presets[].frames[]` (url per second) and `presets[].captionVideoArgs`: pass it unchanged to `caption_video` (or POST /v1/captions) to get what you saw. Limits: 30 sheets/hour and 200/day per key (up to 3 seconds = one sheet); 429 `rate_limited` with `retryAfterSeconds`; identical repeats come from cache and do not count. A brand logo is not drawn in the preview. Preview then order (example): 1. `preview` {"mode":"sample","sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","presets":["hormozi-pop","podcast-karaoke","clarity"],"language":"es","text":"Así se verán tus subtítulos","platform":"youtube","faceAvoid":true,"atSeconds":[2,5]} 2. Show `sheetUrl`; the person picks "podcast-karaoke". 3. `caption_video` with that preset's `captionVideoArgs`: {"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","preset":"podcast-karaoke","language":"es","platform":"youtube","faceAvoid":true} Audio-only input (podcast, voice note: mp3, m4a, wav, ...): `caption_video` and `burn_captions` (POST https://api.awesomevideoeditor.com/v1/captions, /v1/captions/burn) return an MP4 with one of ten editorial podcast designs plus the captions, drawn on the server by the web editor's own canvas code (same frames as exporting the audio in the editor). Same price as a video: 5 credits/min caption, 4 burn. `preview {mode:'sample'}` with `audioVisual` is free. Catalog with names, descriptions, fields, recommended caption presets and preview images: GET https://api.awesomevideoeditor.com/v1/audio-visuals (MCP `get_catalog {kind:'audio_visuals'}`), free, no key. Designs (`audioVisual.variant`, default `editorial-cover`): - `swiss-grid` (Swiss grid, light): International-style poster: a huge episode numeral on a six-column grid, one red hairline tracing the last 1.6 s of voice, progress rule and timecode. Fields: showName, episode, speaker. Empty fields: No episode: the numeral becomes the running timecode. No show/speaker: those labels are omitted. - `braun-radio` (Braun radio, light): Dieter Rams-style radio: tuning scale with an orange needle that follows the voice, perforated grille, two knobs (voice level, elapsed time). Fields: showName, episode, speaker. Empty fields: Labels are omitted; the radio itself carries the design. - `riso` (Riso print, light): Two-ink risograph: halftone discs in fluoro pink and blue overprint and breathe with the voice; misregistered type on paper tooth. Fields: showName, episode, speaker. Empty fields: No show name: the big title reads PODCAST. - `editorial-cover` (Editorial cover, light): Magazine cover: serif masthead and issue line; the sentence is set as a pull-quote word by word, with a hairline under the spoken word that thickens with the voice. Fields: showName, episode, speaker. Empty fields: No show name: the masthead reads Podcast. No speaker: the byline is omitted. - `bauhaus` (Bauhaus, light): Circle, square and half-disc on a grid; each answers the voice with its own small delay. Heavy lowercase type. Fields: showName, episode, speaker. Empty fields: The type stack is omitted; the composition stands alone. - `continuous-line` (Continuous line, light): One pen line writes the voice across ruled rows, back and forth so it never lifts; a nib dot marks the tip. Fields: showName, episode, speaker. Empty fields: Labels are omitted. - `vinyl` (Vinyl, dark): Top-down turntable: matte record turning at 33 rpm, cover art on the label, a light sheen that brightens with the voice, tonearm moving with progress. Fields: showName, episode, speaker, coverSrc. Empty fields: No cover: a plain label in the ink colour with the show name (or nothing). - `type-wave` (Type as waveform, dark): The captions are the visual: each word is set at the weight of its own loudness (Inter 200-900), with a live weight scale. Fields: showName, episode, speaker. Empty fields: Labels are omitted. In preset mode the show name (or PODCAST) breathes in weight instead. - `duotone-portrait` (Duotone portrait, light): Cover art or host photo in two inks, framed by a hairline that carries the voice around its edge; heavy caps with a marker block on the spoken word. Fields: showName, episode, speaker, coverSrc. Empty fields: No cover: a two-ink gradient field with the show's initials. - `ma` (Ma, light): Japanese restraint: one sumi ink dot on washi that breathes, slow rings on loud syllables, a vermilion seal and a vertical label. Fields: showName, episode, speaker. Empty fields: No show name: the seal is a plain vermilion square. `audioVisual` fields (all optional): - `showName` (string, max 60), `episode` (string or number, max 12), `speaker` (string, max 60): printed by the design; empty ones are left out. - `coverImageUrl` (public https) or `coverFileId` (from `upload {action:'start'}`): PNG/JPEG/WebP up to 5 MB, fetched before any charge; used by vinyl (record label) and duotone-portrait (two-ink portrait). Other designs ignore it with a warning. - `background` (paper), `accent`, `ink`: #rgb or #rrggbb. Default: the design's palette. Changing the paper picks a contrasting ink automatically unless `ink` is set. - `captionMode`: `integrated` (default) = the design sets each sentence itself, word by word; the caption preset is not drawn. `preset` = your caption preset draws and the design keeps its caption band clear. - `contrastGuard` (default true, preset mode): a preset whose text colour is too close to the paper (white text on a light design) switches to the design's ink without stroke/shadow. Light designs read best with Editorial, Sharp Notes or Frosted; dark designs (vinyl, type-wave) with Clarity, Iman Lowercase or Podcast Karaoke. - `aspect` 9:16 (default, or from `platform`) | 16:9 | 1:1 | 4:5, or `width`+`height` (128-3840); `enabled` false = paper + captions only; `overlays` up to 8 image/text items. - Retired visualizer ids still work and render their replacement, with a `warnings` entry on the job: 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. Their `presetId`/`config` fields are ignored (warning), gradient backgrounds fall back to the design's paper. - Errors: unknown variant/field, bad colour, too-long text, unreachable or non-image cover: 422 `invalid_audio_visual`, `charged: false`. curl: curl -X POST https://api.awesomevideoeditor.com/v1/captions -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" -d '{"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","platform":"tiktok","audioVisual":{"variant":"editorial-cover","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}}' MCP: caption_video {"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","audioVisual":{"variant":"vinyl","showName":"Field Notes","coverImageUrl":"https://example.com/cover.jpg"}} Python: requests.post("https://api.awesomevideoeditor.com/v1/captions", headers={"Authorization": f"Bearer {key}"}, json={"fileId": file_id, "preset": "editorial", "audioVisual": {"variant": "riso", "captionMode": "preset", "showName": "Field Notes"}}).json() A brand logo is drawn bottom right. preview, shorts and create_clips on audio return 422 `audio_only_input`, not charged. Long audio renders in 2-minute pieces that a retry or `resume_job` reuses; drawing takes about 0.2-0.4x the audio length on one vCPU; on staging a 50 s episode finished in 1-2.5 minutes end to end, transcription included. Style reference: `get_catalog {kind:'styles'}` (MCP) / GET https://api.awesomevideoeditor.com/v1/style-reference (free, no key) lists every style field the web editor has, with type, values/range and examples. Word highlights: `wordHighlights: {rules: [{id, enabled, color, backgroundColor?, words?, minLength?}], customLists?: [{id, name, enabled, color, backgroundColor?, words}]}`; rule ids numbers (digits, %), custom (its words list), acronym (ALL CAPS), hashtag (# and @), long (longer than minLength), person/orgloc (web editor NLP only; use custom words for server burns). Keywords in an accent color: `{"rules":[{"id":"custom","enabled":true,"color":"#FACC15","words":["gratis","AwesomeVideo"]}]}` or the shortcut `highlightWords: ["gratis","AwesomeVideo"], highlightColor: "#FACC15"` on any burn tool. Numbers: `{"rules":[{"id":"numbers","enabled":true,"color":"#F59E0B"}]}`. Marker background: `{"rules":[{"id":"custom","enabled":true,"color":"#000000","backgroundColor":"#FACC15","words":["oferta"]}]}`. Smart emphasis: `smartEmphasis: {enabled: true, target: "auto", style: "color"|"pop"|"pill", intensity: "low"|"med"|"high", color: "#A855F7"}` (server burns support target auto; verbs/nouns/numbers/custom are web-only, use wordHighlights instead). Word states: `wordStateStyles: {"active": {"color": "#FACC15", "scaleBy": 1.2}, "upcoming": {"opacity": 0.5}}` with revealMode word-by-word. Color cycle: `segmentColorCycle: {"enabled": true, "segmentSize": 2, "mode": "fixed", "variants": [{"text": "#FFFFFF"}, {"text": "#FACC15"}]}`. Free price checks: `quoteOnly: true` returns {costCents, breakdown, charged:false} without starting a job on create_clips (POST /v1/clips, needs durationSeconds), remove_silences (POST /v1/trim, durationSeconds; upper bound since it bills kept minutes) and generate_metadata (POST /v1/metadata; durationSeconds only when passing media without a transcript). Publishing metadata: MCP `generate_metadata` (REST POST https://api.awesomevideoeditor.com/v1/metadata) writes titles, a description, hashtags and YouTube chapters from what is said. Pass `transcriptionJobId` (any finished transcribe, caption_video, remove_silences or translate job) or `subtitles`, else `fileId`/`mediaUrl` (transcribed first, 1 credit/min). `platforms`: youtube (default), shorts, tiktok, instagram; 1 credit each. Options: language, titleCount 1-10, context (500 chars). `get_catalog {kind:'presets'}` returns each style JSON. Agents can start without a human: POST https://api.awesomevideoeditor.com/v1/keys/anonymous returns a key with 0 paid credits (plus 10 free welcome credits for caption_video/transcribe while the trial runs, with a solved GET /v1/keys/challenge proof-of-work; over MCP, create_key {} gives 5 starter credits with no challenge, 3 keys per day in total); paid calls answer 402 with a $5 checkout link for that key. Before a job, POST /v1/plan (free, no key) prices the whole pipeline and lists any limit violations; paid calls over a limit answer 422 limit_exceeded before charging. ## Credits 1 credit = 1 cent. - `pack_5`: $5 one-time = 500 credits. Never expire. - `pack_20`: $20 one-time = 2,200 credits. Never expire. - `pack_50`: $50 one-time = 6,000 credits. Never expire. - `creator`: $9/month = 1,200 credits/month, or $90/year (10× monthly, 12 grants). - `pro`: $29/month = 4,500 credits/month, or $290/year (10× monthly, 12 grants). Includes the account webhook. - `scale`: $99/month = 18,000 credits/month, or $990/year (10× monthly, 12 grants). Includes the account webhook. Credit policy: pack credits never expire. Monthly plan credits roll over through the end of the following month. `estimate` (REST /v1/quote and /v1/plan) and `get_catalog` are free. A paid call over a limit answers 422 before charging (`charged: false`). A server job that fails after charging is refunded automatically to the same balance. Rate limits: 429 `rate_limited` never charges; wait the `Retry-After` header (also `retryAfterSeconds` in the JSON) before retrying. --- # AwesomeVideo API for agents > Transcribe, translate, dub, trim, clip, and burn styled captions into video, and write titles, descriptions, hashtags, and chapters. Prepaid credits: 1 credit = 1 cent. REST and MCP share one key and one balance. - REST base: https://api.awesomevideoeditor.com/v1 - Full docs in one file (site overview + this file): https://api.awesomevideoeditor.com/llms-full.txt (same as https://awesomevideoeditor.com/llms-full.txt) - OpenAPI: https://api.awesomevideoeditor.com/openapi.json - MCP (Streamable HTTP): https://api.awesomevideoeditor.com/mcp - MCP server card: https://api.awesomevideoeditor.com/.well-known/mcp.json - Copy-paste recipes (curl, MCP, Python): https://awesomevideoeditor.com/agents - MCP setup per client: https://awesomevideoeditor.com/mcp (Claude: https://awesomevideoeditor.com/mcp/claude, Cursor: https://awesomevideoeditor.com/mcp/cursor, ChatGPT: https://awesomevideoeditor.com/mcp/chatgpt, Mistral Le Chat: https://awesomevideoeditor.com/mcp/le-chat, Manus: https://awesomevideoeditor.com/mcp/manus) - Custom connectors on agent platforms (Le Chat, Manus, Okou, Lindy, Genspark): if the platform offers a sign-in, use https://api.awesomevideoeditor.com/mcp/oauth (OAuth 2.1, dynamic client registration, one click on Allow; on Okou choose Automatic authentication, since Custom OAuth app needs a client ID and secret registered by hand); if it only takes a header, use https://api.awesomevideoeditor.com/mcp with `Authorization: Bearer av_live_...` and a key made for that platform. https://awesomevideoeditor.com/mcp#agent-platforms - One-click install, keyless (then call create_key): Cursor cursor://anysphere.cursor-deeplink/mcp/install?name=awesomevideo&config=eyJ1cmwiOiJodHRwczovL2FwaS5hd2Vzb21ldmlkZW9lZGl0b3IuY29tL21jcD92aWE9YnRuLWN1cnNvciJ9 ; VS Code https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522awesomevideo%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.awesomevideoeditor.com%252Fmcp%253Fvia%255Cu003dbtn-vscode%2522%257D ; VS Code Insiders https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522awesomevideo%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fapi.awesomevideoeditor.com%252Fmcp%253Fvia%255Cu003dbtn-vscode%2522%257D - Caption API landing (curl, price per minute): https://awesomevideoeditor.com/api/captions - Add subtitles to a video with an API (own SRT/VTT via POST /v1/captions/burn, or automatic via POST /v1/captions; also MCP): https://awesomevideoeditor.com/guides/add-subtitles-to-video-api - Add subtitles to a video with Claude (custom connector https://api.awesomevideoeditor.com/mcp/oauth with one click on Allow, or `claude mcp add --transport http awesomevideo https://api.awesomevideoeditor.com/mcp` in Claude Code; then "add subtitles to this video: " -> caption_video): https://awesomevideoeditor.com/guides/add-subtitles-to-video-with-claude - Compared with other caption APIs: https://awesomevideoeditor.com/zapcap-alternative, https://awesomevideoeditor.com/veed-api-alternative, https://awesomevideoeditor.com/submagic-api-alternative, https://awesomevideoeditor.com/captions-ai-api-alternative, https://awesomevideoeditor.com/ffmpeg-subtitles-alternative; price-per-minute table: https://awesomevideoeditor.com/caption-api-comparison - Facts (short, citable: prices, endpoints, limits, welcome credits): https://awesomevideoeditor.com/facts - Caption styles with 8-second demo renders and exact params: https://awesomevideoeditor.com/styles - Live prices: GET https://api.awesomevideoeditor.com/v1/pricing (no auth) - Website: https://awesomevideoeditor.com (pricing: https://awesomevideoeditor.com/pricing, account: https://awesomevideoeditor.com/account) - Best caption APIs and MCP servers for AI agents: https://awesomevideoeditor.com/best-caption-apis-for-ai-agents - n8n workflow (importable JSON, core nodes: POST /v1/captions then poll GET /v1/jobs/{id}): https://awesomevideoeditor.com/integrations/n8n - Make.com recipe (one HTTP module: POST /v1/captions with waitSeconds 50, or webhookUrl into a Make custom webhook for long videos; no FFmpeg): https://awesomevideoeditor.com/integrations/make - Free subtitle toolbox (shift timings, validate, WPM, convert; in the browser, no upload, no key): https://awesomevideoeditor.com/tools/subtitles — plus converters https://awesomevideoeditor.com/tools/vtt-to-srt (WebVTT to SRT), https://awesomevideoeditor.com/tools/srt-to-vtt (SRT to WebVTT), https://awesomevideoeditor.com/tools/srt-to-txt (SRT or VTT to a plain-text transcript); index: https://awesomevideoeditor.com/tools ## First job over MCP (no sign-in) Connected to /mcp without a key? Three calls to a captioned video (caption_video costs 5 credits per audio minute, $0.05/min; 1 credit = 1 cent): 1. create_key {} (free): returns your token once. While today's starters last (a few per day) it already has 5 free welcomeCredits, enough for the sample, no challenge; otherwise welcomeCredits is 0 plus a welcomeChallenge. 2. Add "api_key": "" to the arguments of every next call (same session, no reconnect; or send Authorization: Bearer ). Only if welcomeCredits is 0: solve the challenge (SHA-256 proof-of-work, about 1-3 s) and call create_key {api_key, challenge, nonce} to claim 10 free welcome credits while the trial runs. 3. caption_video {"sourceUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "preset": "hormozi-pop"}: the 8 s sample costs 2 credits and returns the MP4, SRT and VTT. Then use your own public link or a fileId. `estimate` and `get_catalog` are free without a key. A short balance answers 402 `insufficient_balance` with `checkoutUrl` ($5 = 500 credits); nothing is charged. ## Fastest path: one call (caption_video) To put burned subtitles on a video, call MCP `caption_video` (REST `POST https://api.awesomevideoeditor.com/v1/captions`) once. It runs transcribe -> optional translate -> burn and returns the MP4, SRT, VTT, JSON transcript, and `creditsCharged`. Converting an existing subtitle file between SRT, VTT, and plain text needs no API call: every job already returns SRT, VTT, and JSON, and the conversion is a free local text transform (SRT uses `00:00:01,000` and numbered cues; VTT starts with `WEBVTT` and uses `00:00:01.000`). Humans can use the free in-browser subtitle toolbox (shift, validate, WPM, convert) at https://awesomevideoeditor.com/tools/subtitles and the converters at https://awesomevideoeditor.com/tools. - Source: `sourceUrl` (public link: direct https/http file, chat attachment URL, Google Drive or Dropbox share link) or `fileId` (from `upload {action:'start'}`, `import_url`, or `upload {action:'inline'}`). YouTube, TikTok, and Instagram links answer 422 `youtube_not_supported` / `platform_url_unsupported` with `charged: false`: upload the file instead. - Options: `language` (default auto), `translateTo` (ISO 639-1), `preset` or `brandPresetId`, `platform` (same ids as burn_captions), `autoFit` (default true; see below), `glossary`, `review: true` (transcribe now, send `review.reviewUrl`, burn charged on approval), `maxCredits`, `webhookUrl` / `notifyEmail`, `Idempotency-Key`. - Waiting: MCP waits up to 45 s by default (`waitSeconds` 0-50, `wait: false` to return at once). REST returns 202 at once unless you send `wait: true` or `waitSeconds`. Still running after the window: you get `status: queued|running` and `id`; poll `get_job` / `GET /v1/jobs/{id}` after `pollAfterSeconds`. Every job view has `step` (queued, transcribe, translate, burn, finalize, done, failed), `progress` and `stepProgress` (0-100; burn is real ffmpeg progress), `eta_seconds`, `estimatedCompletionAt`, and `pollAfterSeconds`. `quote` and `plan` return `estimatedSeconds`. - Resume: a failed job is refunded in full. For caption_video, transcribe, create_clips, dub_video, trim/remove_silences and generate_metadata, `resume_job {jobId}` (REST `POST https://api.awesomevideoeditor.com/v1/jobs/{id}/resume`) continues where it stopped: transcription is saved in 30 s chunks, so only missing chunks are transcribed and the price is the original minus the minutes already transcribed (1/min); a caption job with a finished transcript pays only the remaining steps (usually burn, 4/min). Idempotent, never a double charge. No speech: transcribe finishes as succeeded with `result.noSpeech: true` and 0 credits; caption/clips/metadata fail with error `no_speech`, refunded, `resumable: false`; resume_job on either returns 409 `job_not_resumable` (reason `no_speech`, charged: false). Burns of videos over 5 min render in 4 min segments saved as they finish (same frames, timing and untouched audio as one pass), so a retry or resume re-renders only the missing segments; no 10 min limit. 422 `resume_not_supported` / `resume_media_expired` (charged: false): call the tool again. - Price: exactly transcribe + (translate) + burn, no surcharge: 5 credits per audio minute, 7 with `translateTo`. `quote` with `operation: "caption"` (plus `translateTo`) or `plan` with `{op: "caption"}` prices it for free. If the audio is already in `translateTo`, the translate share is refunded. No speech or any failure: everything is refunded. - Example (MCP): `caption_video {"sourceUrl": "https://drive.google.com/file/d/FILE_ID/view", "language": "es", "platform": "tiktok"}` - Example (REST): `curl -X POST https://api.awesomevideoeditor.com/v1/captions -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"sourceUrl":"https://example.com/clip.mp4","translateTo":"en","wait":true}'` ## MCP tools (server 0.5.0: 27 tools) `tools/list` on /mcp shows these 27 tools. Each is the same operation as the REST endpoint next to it (same key, balance, prices and limits). | MCP tool | REST | Example | | --- | --- | --- | | `create_key` | POST /v1/keys/anonymous | `create_key {"name":"my-agent"}` | | `upload` | POST /v1/uploads/url, /v1/uploads/multipart, /v1/uploads/{fileId}/complete, DELETE /v1/uploads/{fileId}, POST /v1/uploads | `upload {"action":"start","filename":"talk.mp4","contentType":"video/mp4","sizeBytes":5242880}` | | `import_url` | POST /v1/uploads/import | `import_url {"url":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4"}` | | `caption_video` | POST /v1/captions | `caption_video {"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","language":"es","platform":"tiktok"}` | | `transcribe` | POST /v1/transcribe | `transcribe {"fileId":"f_...","language":"en"}` | | `edit_transcript` | PATCH /v1/jobs/{id} | `edit_transcript {"jobId":"job_...","subtitles":"1\n00:00:00,000 --> 00:00:02,000\nHola"}` | | `burn_captions` | POST /v1/captions/burn (mode client_script: POST /v1/captions/prepare) | `burn_captions {"fileId":"f_...","transcriptionJobId":"job_...","preset":"Clarity"}` | | `get_catalog` | GET /v1/presets, /v1/style-reference, /v1/voices, /v1/platforms, /v1/audio-visuals | `get_catalog {"kind":"voices","language":"es","limit":10}` | | `estimate` | POST /v1/quote (no steps) or POST /v1/plan (steps) | `estimate {"steps":[{"op":"caption","translateTo":"en"}],"source":{"durationSeconds":420}}` | | `preview` | POST /v1/captions/preview (mode sample: POST /v1/captions/style-preview) | `preview {"mode":"sample","sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","presets":["Clarity","hormozi-style"]}` | | `batch` | POST /v1/batch | `batch {"operation":"caption","preset":"builtin:hormozi-pop","dryRun":true,"items":[{"fileId":"f_1","name":"ep1.mp4"},{"fileId":"f_2","name":"ep2.mp4"}]}` | | `get_presets` | GET /v1/custom-presets (yours only; all presets: GET /v1/presets), action get of a built-in or community id: entry of GET /v1/presets, /v1/custom-presets/{id}, /v1/brand-presets, POST /v1/custom-presets/validate | `get_presets {"action":"validate","basePreset":"Clarity","overrides":{"fontSize":72}}` | | `manage_preset` | POST/PATCH/DELETE /v1/custom-presets[/{id}], POST /v1/custom-presets/{id}/submit, POST/DELETE /v1/brand-presets[/{id}] | `manage_preset {"action":"create","type":"custom","name":"Mi estilo","basePreset":"Clarity","overrides":{"fontSize":72}}` | | `translate` | POST /v1/translate | `translate {"transcriptionJobId":"job_...","targetLanguage":"en"}` | | `dub` | POST /v1/dub | `dub {"fileId":"f_...","targetLanguage":"en","voiceTier":"basic"}` | | `generate_metadata` | POST /v1/metadata | `generate_metadata {"transcriptionJobId":"job_...","platforms":["youtube"]}` | | `create_clips` | POST /v1/clips (engine shorts: POST /v1/shorts) | `create_clips {"sourceUrl":"https://example.com/podcast.mp4","count":3}` | | `remove_silences` | POST /v1/trim | `remove_silences {"fileId":"f_...","quoteOnly":true,"durationSeconds":600}` | | `request_review` | POST /v1/reviews | `request_review {"transcriptionJobId":"job_...","preset":"Clarity","notifyEmail":"me@example.com"}` | | `get_review` | GET /v1/reviews/{id} | `get_review {"reviewId":"rv_..."}` | | `get_glossary` | GET /v1/glossary | `get_glossary {}` | | `update_glossary` | PUT/DELETE /v1/glossary | `update_glossary {"action":"save","entries":[{"term":"AwesomeVideo","aliases":["awsome video"]}]}` | | `get_job` | GET /v1/jobs/{id} | `get_job {"jobId":"job_..."}` | | `list_jobs` | GET /v1/jobs | `list_jobs {"limit":10}` | | `resume_job` | POST /v1/jobs/{id}/resume | `resume_job {"jobId":"job_..."}` | | `create_checkout` | POST /v1/checkouts | `create_checkout {}` | | `get_account` | GET /v1/balance + GET /v1/usage | `get_account {"response_format":"detailed"}` | Every result has `structuredContent` matching the tool's `outputSchema` (jobs share one shape: id, kind, status, step, progress, costCents, result, expiresAt). Errors are `isError: true` with `{"error", "code", "message", "status", "hint", "retryable"}`: `hint` says what to call next, `retryable` whether the same call can succeed later. `get_catalog` and `get_presets` lists are paginated (`limit`, `cursor` = `nextCursor`, `hasMore`, `total`) and take `response_format` concise (default) or detailed. The tool names used before 0.4.0 (52 tools) were replaced by these 27 and are no longer accepted. This file uses only the 0.4.0 names. Calling an older name (for example `create_upload`, `list_presets`, `quote`) answers -32602 with the 0.4.0 call to use instead (`upload`, `get_catalog`, `estimate`); REST routes are unchanged. Need to check or fix the text before burning? Use `transcribe` -> `edit_transcript` -> `burn_captions` instead. Already have an SRT or VTT file? Burn it as is with `burn_captions` (REST `POST https://api.awesomevideoeditor.com/v1/captions/burn`): media (`mediaUrl` or `fileId`) plus the file's text in `subtitles` (SRT, VTT or JSON cues, up to 1.5 MB; not a link) and a `preset`; your timings and wording are kept, nothing is transcribed, 4 credits per minute. Walkthrough with real responses: https://awesomevideoeditor.com/guides/add-subtitles-to-video-api ## Recipes (copy and paste) Zero to first video: 1) get a key (`POST /v1/keys/anonymous` or MCP `create_key`, no sign-in); 2) call the recipe with a public video URL; 3) if the balance is short you get 402 `insufficient_balance` with `checkoutUrl` (a human pays $5 = 500 credits for this key, no sign-in) and `quote`; retry the same call after paying. New keys may include a few `welcomeCredits` (free trial, see below). ```bash curl -X POST https://api.awesomevideoeditor.com/v1/keys/anonymous -H "Content-Type: application/json" -d '{"name":"my-agent"}' # -> {"token":"av_live_...","balanceCents":0,...} export AV_KEY=av_live_... ``` Free trial (welcome credits) with the proof-of-work, Python: ```python import hashlib, requests API = "https://api.awesomevideoeditor.com" c = requests.get(f"{API}/v1/keys/challenge").json() n = 0 while int.from_bytes(hashlib.sha256(f"{c['challenge']}:{n}".encode()).digest(), "big") >> (256 - c["bits"]): n += 1 key = requests.post(f"{API}/v1/keys/anonymous", json={"challenge": c["challenge"], "nonce": n}).json() print(key["welcomeCredits"], key["welcomeCreditsReason"]) ``` JavaScript (Node 18+, ESM): ```js import { createHash } from "node:crypto"; const API = "https://api.awesomevideoeditor.com"; const c = await (await fetch(API + "/v1/keys/challenge")).json(); let n = 0; while (createHash("sha256").update(c.challenge + ":" + n).digest().readUInt32BE(0) >>> (32 - c.bits)) n++; const key = await (await fetch(API + "/v1/keys/anonymous", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ challenge: c.challenge, nonce: n }) })).json(); console.log(key.welcomeCredits, key.welcomeCreditsReason); ``` MCP: `create_key {}` may already return 5 starter `welcomeCredits` (a few keys per day, no challenge). If `welcomeCredits` is 0 it returns `welcomeChallenge`; solve it, then call `create_key {"challenge": "...", "nonce": N}` on the connection that sends the new key. MCP client config (Streamable HTTP): ```json { "mcpServers": { "awesomevideo": { "url": "https://api.awesomevideoeditor.com/mcp", "headers": { "Authorization": "Bearer av_live_..." } } } } ``` ### Caption a video Video in, MP4 with burned subtitles plus SRT and VTT out. One call. Price: 5 credits per audio minute. ```bash curl -X POST https://api.awesomevideoeditor.com/v1/captions \ -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" \ -d '{"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","preset":"hormozi-pop","wait":true}' ``` MCP: `caption_video {"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","preset":"hormozi-pop"}` ```python import os, requests r = requests.post( "https://api.awesomevideoeditor.com/v1/captions", headers={"Authorization": f"Bearer {os.environ['AV_KEY']}"}, json={ "sourceUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "preset": "hormozi-pop", "wait": True }, timeout=120, ) print(r.status_code, r.json()) ``` ### Translate and dub Spoken translation fitted to the original timing, mixed over the original audio. Price: 5 credits per minute per language, plus transcription and translation. ```bash curl -X POST https://api.awesomevideoeditor.com/v1/dub \ -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" \ -d '{"mediaUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","targetLanguage":"es"}' ``` MCP: `dub {"mediaUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","targetLanguage":"es"}` ```python import os, requests r = requests.post( "https://api.awesomevideoeditor.com/v1/dub", headers={"Authorization": f"Bearer {os.environ['AV_KEY']}"}, json={ "mediaUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "targetLanguage": "es" }, timeout=120, ) print(r.status_code, r.json()) ``` ### 9:16 shorts from a long video An LLM picks the best moments, reframes them to 9:16 on the speaker and captions them. Price: about 1 credit per source minute plus a few per clip (30 min, 3 clips of 60 s = 42 credits); quote first. ```bash curl -X POST https://api.awesomevideoeditor.com/v1/clips \ -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" \ -d '{"sourceUrl":"https://example.com/podcast.mp4","count":3,"reframe":"face","platform":"tiktok"}' ``` MCP: `create_clips {"sourceUrl":"https://example.com/podcast.mp4","count":3,"reframe":"face","platform":"tiktok"}` ```python import os, requests r = requests.post( "https://api.awesomevideoeditor.com/v1/clips", headers={"Authorization": f"Bearer {os.environ['AV_KEY']}"}, json={ "sourceUrl": "https://example.com/podcast.mp4", "count": 3, "reframe": "face", "platform": "tiktok" }, timeout=120, ) print(r.status_code, r.json()) ``` ### Caption a folder Up to 50 videos in one call, one style, priced together. dryRun quotes for free. Price: 5 credits per audio minute per video. ```bash curl -X POST https://api.awesomevideoeditor.com/v1/batch \ -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" \ -d '{"operation":"caption","preset":"hormozi-pop","items":[{"mediaUrl":"https://example.com/ep1.mp4"},{"mediaUrl":"https://example.com/ep2.mp4"}]}' ``` MCP: `batch {"operation":"caption","preset":"hormozi-pop","items":[{"mediaUrl":"https://example.com/ep1.mp4"},{"mediaUrl":"https://example.com/ep2.mp4"}]}` ```python import os, requests r = requests.post( "https://api.awesomevideoeditor.com/v1/batch", headers={"Authorization": f"Bearer {os.environ['AV_KEY']}"}, json={ "operation": "caption", "preset": "hormozi-pop", "items": [ { "mediaUrl": "https://example.com/ep1.mp4" }, { "mediaUrl": "https://example.com/ep2.mp4" } ] }, timeout=120, ) print(r.status_code, r.json()) ``` ## Get a key Agent, no human needed: `POST https://api.awesomevideoeditor.com/v1/keys/anonymous` (no auth, optional body `{"name": "my-agent"}`) or the MCP tool `create_key`. You get `token` once. The key starts with 0 paid credits and the response has `firstJob`: the one call that captions a video from a public URL. Free trial for agents, while it runs: a new self-serve key can get 10 welcome credits (about 2 min of caption_video). Over MCP, create_key {} with no challenge gives 5 starter credits right away instead (enough for the 8 s sample; 3 keys per day in total); when today's starters are gone it returns 0 and a challenge, as below. Fair share: one per network and one per network operator per day (5 per operator per month), and the daily pool opens in 3 slots through the UTC day, so if it is taken, welcomeCreditsReason is slot_wait with nextSlotAt. To claim, solve a small proof-of-work (about 1-3 s of CPU): GET /v1/keys/challenge, find an integer nonce so SHA-256(challenge + ":" + nonce) starts with `bits` zero bits, and send {challenge, nonce} with POST /v1/keys/anonymous (or POST /v1/keys/welcome with your new key, or MCP create_key {challenge, nonce} on the key's connection). Without it (and without a starter) the key is created with 0 credits and reason pow_required plus a ready challenge. Welcome credits pay only caption_video and transcribe, jobs up to 2 min, are spent before paid credits on those jobs, and expire after 30 days. GET /v1/balance shows paidCents and welcomeCents. A network can create a few keys per day; reuse yours. Human: sign in at https://awesomevideoeditor.com/account with a magic link and create keys there. A human can also claim a self-serve key (`POST /v1/account/claim-key` with `{"token": "av_live_..."}` while signed in) so its balance and jobs move onto the account. Send `Authorization: Bearer av_live_...` on REST and on the MCP connection. Without a key, MCP `initialize`, `tools/list`, `create_key`, `estimate` (durationSeconds only without steps), and `get_catalog` work; other tools return an error that explains how to get a key. Trusted clients only: pasting an av_live_ key into a third-party web client exposes it to that site. REST `POST /v1/quote` also works without a key when you pass `operation` and `durationSeconds`, and so do `POST /v1/plan`, `GET /v1/presets` (built-in and community presets; your custom presets need the key), `GET /v1/fonts`, `GET /v1/style-reference`, `GET /v1/voices`, `GET /v1/platforms` and `GET /v1/audio-visuals`. Browser clients (CORS): `/mcp` and `/mcp/oauth` accept browser calls from any https origin (and http://localhost) with `Access-Control-Allow-Origin: *`, Bearer auth only, no cookies. REST `/v1` answers browser calls only from awesomevideoeditor.com (and localhost); from another site, call it from your server. Optional `?via=` on API and MCP URLs (e.g. `?via=n8n`) only tags where a call came from in request logs; it changes nothing in the request or the price. OAuth 2.1 (for MCP clients that prefer it, e.g. Claude, ChatGPT and Le Chat connectors): connect to `https://api.awesomevideoeditor.com/mcp/oauth`. It answers 401 with `WWW-Authenticate: Bearer resource_metadata=...`, and the client discovers `https://api.awesomevideoeditor.com/.well-known/oauth-authorization-server`, registers itself (`POST https://api.awesomevideoeditor.com/oauth/register`, RFC 7591), and runs the authorization code flow with PKCE S256. On the authorize page the human clicks **Allow to use AwesomeVideo** (one click, no sign-up, straight back to the app: it gets its own self-serve key with free trial credits when available), or signs in with an email magic link to use an account balance. Headless confidential clients can use `grant_type=client_credentials` (register with `token_endpoint_auth_method: client_secret_post`; one self-serve key per client). Free trial for headless clients: a new client_credentials key automatically gets a small free trial with no proof-of-work (5 welcome credits, about one 1-minute caption_video; same per-network and daily-pool limits, plus a small daily cap on headless trials). For the full trial instead, add `challenge` and `nonce` (solved from `GET https://api.awesomevideoeditor.com/v1/keys/challenge`) to that token request; a wrong, stale or already-used challenge+nonce returns `pow_invalid` (or `pow_expired`) and the key gets 0 credits, with no fallback to the 5 headless credits, so send them only when freshly solved. The token response that creates the key also says what it got: `welcome_credits`, `welcome_credits_reason` (`granted`, or why not, with `welcome_credits_message` and `next_slot_at` when the daily pool opens later), and `welcome_expires_at` (ISO time the welcome credits expire) when credits were granted. Or, if the key got no credits, later send them to `POST https://api.awesomevideoeditor.com/v1/keys/welcome` with the access token (once per key, first 24 h). Registration also accepts an empty or form-encoded body: with no redirect_uris it registers a headless client_credentials client and returns its secret. Access tokens (`av_oat_...`, 1 hour) and rotating refresh tokens (30 days) spend that key's balance, scope `mcp`. Each connected app gets its own key in /account (it does not use up API key slots); revoke it there. OAuth tokens also work on REST. ## Credits, packs, and plans 1 credit = 1 cent. Live list: GET https://api.awesomevideoeditor.com/v1/pricing. - `pack_5`: $5 one-time = 500 credits. Never expire. - `pack_20`: $20 one-time = 2,200 credits. Never expire. - `pack_50`: $50 one-time = 6,000 credits. Never expire. - `creator`: $9/month = 1,200 credits/month, or $90/year (10× monthly, 12 grants). - `pro`: $29/month = 4,500 credits/month, or $290/year (10× monthly, 12 grants). Includes the account webhook. - `scale`: $99/month = 18,000 credits/month, or $990/year (10× monthly, 12 grants). Includes the account webhook. Credit policy: pack credits never expire. Monthly plan credits roll over through the end of the following month. `estimate` (REST /v1/quote and /v1/plan) and `get_catalog` are free. A paid call over a limit answers 422 before charging (`charged: false`). A server job that fails after charging is refunded automatically to the same balance. ## Paying: 402 insufficient_balance Paid calls check the balance first. If it is short, the call returns HTTP 402 (MCP: an error result) and nothing is charged: `{"error": "insufficient_balance", "requiredCents": 2, "balanceCents": 0, "checkoutUrl": "https://...", "howToBuy": "..."}` What to do: show `checkoutUrl` to your human (or open it). It buys pack_5 ($5 = 500 credits) for this exact key, no sign-in. After payment the credits land on the key within seconds; poll `GET /v1/balance` and retry the same request (send the same `Idempotency-Key` to avoid duplicates). Use `maxCredits` on any paid call to refuse jobs that would cost more than you expect. New key that never got its free welcome credits (e.g. an OAuth connect clicked before the browser check finished)? The 402 for `caption_video` or `transcribe` also carries `freeWelcome`: solve its `welcomeChallenge` (about 1-3 s), claim with `POST /v1/keys/welcome` `{"challenge", "nonce"}` (MCP: `create_key {challenge, nonce}` on the same connection; same key, no card), then retry the same call. - `create_checkout` (MCP, without `product`) = `POST /v1/checkouts` with an empty body: the $5 checkout tied to this key. Works on any key, including self-serve keys. - `create_checkout` (MCP) = `POST /v1/checkouts` with `{"product": "pack_20" | "pack_50" | "creator" | "pro" | "scale", "interval": "month" | "year"}`: bigger packs and plans. The key must be claimed by an account first (otherwise 409 `account_required`). Neither call grants credits by itself; payment does. Failed jobs refund their credits automatically. ## Paid tools and rates | Tool | REST | Price | | --- | --- | --- | | `caption_video` | POST /v1/captions | 5 credits / audio minute (transcribe + burn), 7 with `translateTo` | | `transcribe` | POST /v1/transcribe | 1 credit / audio minute | | `burn_captions` | POST /v1/captions/burn | 4 credits / audio minute | | `preview` | POST /v1/captions/preview | 1 credit flat (one PNG frame or a clip of at most 5 s) | | `translate` | POST /v1/translate | 2 credits / minute (+ burn price with `burn: true`) | | `create_clips` | POST /v1/clips | 1 credit / source minute (transcribe, 0 with a transcript) + 1 per started 10 source minutes (highlights) + 3 / output minute (render; reserved for count × maxSeconds, unused part refunded) | | `shorts` | POST /v1/shorts | 6 credits / source minute | | `remove_silences` (alias `trim`) | POST /v1/trim (alias /v1/captions/trim) | 3 credits / kept minute, + 4 / kept minute with `burnCaptions` | | `generate_metadata` | POST /v1/metadata | 1 credit / platform from an existing transcript; + 1 credit / minute transcription when only media is passed | | `dub` | POST /v1/dub | 5 credits / source minute per language (basic), 12 (standard), + transcription and translation if not reused | | `batch` | POST /v1/batch | sum of items, no surcharge | Billing is per second of audio; transcribe and burn are each rounded up separately (an 8-second clip costs 2 credits). - transcribe: `mediaUrl` or `fileId`, optional `language` (default auto), `format` srt | vtt | json (json has word timestamps), `glossary` (names and terms; included). - burn_captions: media plus `subtitles` or `transcriptionJobId`, plus `preset` or `brandPresetId`. `combined: true` also returns SRT, VTT, and JSON at the burn price. `platform` (optional, same price) keeps captions out of the target app's UI: tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube (16:9), x; aliases like reels, instagram, shorts, snap, twitter; case-insensitive. If the user says "subtítulos para TikTok" or "for Reels", pass platform=tiktok / instagram_reels. Also on shorts, preview, burn_captions {mode:'client_script'}, and plan steps. Only position and margins change, never the preset's style. The result has `safe_zone {platform, margins, frame}` and a `warning` when the video shape does not match (e.g. 16:9 into tiktok: margins apply to the real frame; use shorts to crop to 9:16). Unknown values return 422 `invalid_platform` with `validPlatforms` before any charge. List: `GET /v1/platforms` (MCP `get_catalog {kind:'platforms'}`, free, no key). - autoFit (default **on** for burn_captions, caption_video, preview, shorts, burn_captions {mode:'client_script'}, review): caption size follows the frame (scale = short side / 720, cap height clamped to 3.0–4.6% of height on 9:16 and 1:1, 3.6–5.4% on 16:9), so a preset looks the same at 720p and 1080p; long captions split to at most 4 words on 9:16, 5 on 1:1, 7 on 16:9; and when no `platform` is given a default safe zone applies (9:16: bottom 35%, top 15%, left 8%, right 15%, clear of TikTok, Reels and Shorts UI; 1:1: bottom 12%; 16:9: bottom 7%). An explicit `platform` safe zone wins. Pass `autoFit: false` only when the user wants the preset's exact fixed pixel sizes and cue length. Same price either way. The web editor uses the same rule ("Auto size for video shape" checkbox), so a browser export and a server burn look identical. - Caption forms (style fields, same in the web editor and every burn): `maxWordsPerCaption` (integer 1-8) sets words per caption: 1 = one big word at a time (MrBeast/Hormozi hook style), 2-3 = short chunks. It always wins over autoFit's per-shape cap (autoFit still sizes the text and keeps the safe zone); unset = autoFit's cap. Validated by `get_presets {action:'validate'}`. - Word pop and entrances (style fields): `activeWordReflow: true` makes a scaled active word (`wordStateStyles.active.scaleBy`, smart-emphasis pop) push the words on its line aside instead of overlapping them (line breaks keep resting widths, so lines never jump). `wordEntrance` bounce (grows 0.55 to 1.15 then settles to 1, with overshoot), slide-up, or fade plays per word when it is spoken (words are hidden until then but keep their place); `wordEntranceDuration` 0.05-1 s (default 0.22). Same timing curve in the web editor and the burn. - Position modes (style fields): `positionMode` fixed (default) | cycle | keyword. cycle walks captions through `positionCycle` (1-6 of top|center|bottom, default top, center, bottom) by caption order; keyword moves captions containing one of `positionKeywords` (up to 50 words, accent-insensitive, or any active wordHighlights match) to `keywordPosition` (default center). Deterministic, and top/bottom always stay inside the safe zone (vertical 9:16 keeps captions in the middle ~63%). `dynamicPositionEnabled` jumps are also clamped to the safe zone. - Stacked poster (style fields): `captionLayout: "stacked"` puts one word per line; the hero word (first `positionKeywords` or highlighted word, else the longest) is `posterHeroScale` times bigger (1-3, default 1.8). Every word shrinks to fit the caption width; sizes come from the same font metrics in the web editor and the burn. Pair with `maxWordsPerCaption` 2-4. - Face avoidance (opt-in style field): `faceAvoid: true` makes burns and previews sample the video for faces at 2 fps (same detector as face reframe) and move each caption to the first clear band inside the safe zone (its own position, then bottom, top, center; it stays put while clear). The result returns `faceAvoid.faceLayout` ([{start, end, position}]); save it in the style as `faceLayout` and the web editor and later burns reuse it (no new detection). Same price; adds about 5 s of container time per 100 s of 720p video. - preview: same inputs as a burn, `mode` still | clip, `atSeconds`, `clipSeconds` up to 5. - translate: `transcriptionJobId` or `subtitles`, `targetLanguage` (ISO 639-1, e.g. es, fr, de, pt, ja; unsupported codes get 400). Keeps cue timing. Word-level highlight (karaoke) is not kept on translated captions. - create_clips (long video → short clips, one call): `sourceUrl` or `fileId` (YouTube, TikTok and Instagram links get 422), optional `transcriptionJobId` or `subtitles` to reuse a transcript (JSON with word timing gives the tightest cuts). Transcribes, then an LLM (Workers AI Llama 3.3 70B, 8B fallback) reads the numbered sentences and picks `count` (1-10, default 3) self-contained, non-overlapping moments of `minSeconds`-`maxSeconds` (default 15-60, range 5-90). Cuts start on a sentence start and end on a sentence end (or a word end when one sentence is too long). `reframe` face (default, 720×1280 crop that follows the speaker, center fallback), center, or none (source shape, long edge up to 1280). `captions` (default true) burns captions with `preset` (any preset or `custom:cp_...`), `platform`, `autoFit` as in caption_video. Result: `clips [{name, rank (1 = best), start, end, seconds, title, hook, reason, score 0-100, text, crop}]` in time order, each MP4 in `files` (`clip-1`...) with a URL, plus `transcript_srt`/`transcript_vtt`/`transcript_json` when it transcribed. `quoteOnly: true` with `durationSeconds` returns the price without a job. `wait`/`waitSeconds` (max 50) as in caption_video; long sources keep running: poll `GET /v1/jobs/:id` or pass `webhookUrl`/`notifyEmail`. Example: 30-minute video, 3 clips up to 60 s = 42 credits reserved (30 + 3 + 9), less when clips are shorter. Failed jobs refund automatically. - shorts: media plus transcript, `count` 1-5, `minSeconds` 5-60 (default 15), `maxSeconds` minSeconds-60. Returns non-overlapping 720×1280 clips with burned captions. `reframe` face (default) follows the main speaker with a smoothed crop and falls back to center when no face shows; center forces a center crop. Same price. - remove_silences / trim: media plus transcript (`transcriptionJobId` or `subtitles`). Cuts pauses between words over `silenceGapSeconds` (default 0.5, 0.2-3) keeping `paddingSeconds` (default 0.08) on each side, plus long pauses inside word timings found by ffmpeg silencedetect (`silenceNoiseDb` default -35; `detectSilences: false` to skip). Fillers, `fillerMode` "clear" (default): uh, um, uhm, er, erm, ah, eh, ehm, em, hmm, mhm, mm, mmm, and "este" only when said on its own. "aggressive" also cuts like, you know, I mean, basically, kind of, sort of, o sea, bueno, pues, digamos, tipo, como que, a ver, only when they stand alone (comma or pause around them). `fillers` adds words or phrases (always cut), `keepFillers` keeps some, `removeFillers: false` keeps all. Every cut gets a 12 ms audio fade so joins do not click. Returns the cut MP4, retimed SRT/VTT/JSON, `ranges` kept, and `stats` (sourceSeconds, keptSeconds, removedSeconds, cuts, fillersRemoved, fillerSample). `burnCaptions: true` burns the retimed captions in the same job with `preset`/`brandPresetId`/`platform`/`autoFit` (same renderer as burn_captions; the uncaptioned cut is also returned as `mp4_uncaptioned`). Billed on the kept duration. - generate_metadata: `transcriptionJobId` (alias `jobId`: any finished transcribe, caption_video, trim/remove_silences, or translate job; never re-transcribes) or `subtitles`, else `mediaUrl`/`fileId` (transcribed first, 1 credit/min). `platforms`: youtube (default), shorts, tiktok, instagram (alias reels); one result per platform at 1 credit each. `language` (default: the video's language), `titleCount` 1-10 (default 5), `context` (creator notes, 500 chars). Result `platforms.

`: `titles`, `description`, `hashtags` (shorts always includes #shorts), `chapters` [{start, timestamp, title}] for youtube on videos of 60 s or more (first at 0:00, 3+ chapters at least 10 s apart, snapped to speech; dropped with a warning otherwise), and `descriptionWithChapters` ready to paste. Llama 3.1 8B on Workers AI with validated JSON; invalid output is retried once, then the job fails and is refunded. For a trimmed video pass the trim job id so chapter times match the cut. - dub: media (`mediaUrl`, `fileId`, or a `transcriptionJobId` whose media is stored) and `targetLanguage`. Basic voices: en, es, fr, zh, ja, ko (Workers AI MeloTTS) and hi, ar, bn, pt, ru, ur, id, de, tr, it, vi (Google WaveNet). `voiceTier: "standard"`: en, es (Deepgram Aura-2) and hi, ar, bn, pt, ru, ur, id, de, tr, it, vi (Google Chirp 3 HD). `GET /v1/limits` lists what this deployment has enabled. Voices: `GET /v1/voices?language=de&tier=basic` (MCP `get_catalog {kind:'voices'}`, free, no key) lists every voice with gender, credits per minute, and a short MP3 `sampleUrl`; pass its `id` as `voice` to dub or plan (422 `voice_unknown`, `voice_language_mismatch`, or `voice_tier_mismatch` before any charge). Without `voice` you get the default voice. Google voices have a monthly character quota; when a job would pass it, `plan` lists it and dub returns 422 `provider_quota_exceeded` before any charge. Other languages return 422 `limit_exceeded` before any charge. Reuse `transcriptionJobId`/`subtitles` and `translationJobId`/`translatedSubtitles` to skip those charges. Each line is fitted to the original timing (up to 1.25x, then one shorter rewrite, then a cut with a short fade; short lines are padded). `keepOriginalAudio` duck (original at -18 dB, default) or mute. Returns MP4 plus target-language SRT, VTT, JSON; `audioTrack: true` adds M4A. No voice cloning, source separation, or lip sync. - batch: caption a whole folder. 1-50 items with one `operation`: `caption` (transcribe + burn per item, same output and price as caption_video), `transcribe`, or `burn`. One `preset` for all (items may override preset, styleOverrides, faceAvoid, translateTo). `dryRun: true` returns the total and debits nothing. Missing media, low balance or `maxCredits` reject the whole batch before any charge. Status: GET /v1/batches/{id}?offset=0&limit=50 returns `counts`, one page of `jobs` (index, name, files) and `page.nextOffset`. The web app's "Caption a folder" uses this same endpoint, so results are identical. Example: `POST /v1/batch {"operation":"caption","preset":"builtin:hormozi-pop","dryRun":true,"items":[{"fileId":"f_1","name":"ep1.mp4"},{"mediaUrl":"https://example.com/ep2.mp4"}]}` ## Human review and glossary (free) When the person wants to check captions first ("quiero revisarlo antes", "let me check it first"): `transcribe`, then `request_review` (POST /v1/reviews) with `transcriptionJobId` and `preset` → `reviewUrl` (web editor, no login, up to 7 days). Send it to the person; poll `get_review` (awaiting_review → approved with `burnJobId` → `burnJob.result.url`, or rejected with `note`). The burn is charged only on approval, once. With `webhookUrl`/`notifyEmail` you also get `review.approved` (burnJobId), `review.rejected` (note) and `review.expired`, once each, signed like job webhooks. Saved glossary: `update_glossary {action:'save'}` / `get_glossary` / `update_glossary {action:'delete'}` (/v1/glossary) with `{term, aliases, doNotTranslate}`; applied to every transcribe and translate (`useSavedGlossary: false` skips). ## Custom presets (design your own style) Free. `manage_preset {action:'create', type:'custom'}` (POST /v1/custom-presets) stores a full caption style for this key, or the account when the key is claimed: pass `style` (the same JSON document `get_catalog {kind:'presets'}` returns and the web editor stores: font, size, color, stroke, background, shadow, position, reveal mode, animation, motion, `wordStateStyles` for the active word, `wordHighlights`, `smartEmphasis`, `segmentColorCycle`, caption forms such as `maxWordsPerCaption`) or `basePreset` (e.g. `hormozi-style`) plus `overrides` (deep-merged; null removes a field). It is validated with the renderer schema: invalid styles return 422 `invalid_style` with `errors [{path, message}]` (unknown fields are rejected). `fontFamily` (anywhere in the style, and in brand presets) must be a bundled font: Inter, Poppins, Oswald, Roboto, Anton, Bebas Neue, Playfair Display, Caveat, IBM Plex Mono (`GET /v1/fonts`, or `fonts` in `get_catalog {kind:'presets'}`); other fonts return 422. The result's `preset` (`custom:cp_...`) works anywhere a preset is accepted: burn_captions, caption_video, preview, shorts, burn_captions {mode:'client_script'}, request_review, batch; server and browser renders are identical. `get_presets {action:'validate'}` checks without saving; preview one still before a paid burn. Limits: 50 presets per key/account, 20 KB per style. `get_catalog {kind:'presets'}` with a key also lists yours (source `custom`). Custom presets are private. `manage_preset {action:'submit'}` (POST /v1/custom-presets/:id/submit) proposes one for the public community gallery: it becomes `pending`, a human moderator reviews it, and it shows in `get_catalog {kind:'presets'}` for everyone only after approval (never automatic; max 5 submissions per day). Status: `get_presets {action:'get', id}` → `community.status`. Built-in caption presets (34; pass as `preset`, e.g. `builtin:beast-glow`): clarity, neon-glow, highlight, hormozi-style, mrbeast-style, sleek-caps, epic-lines, bubble-talk, power-play, sharp-notes, retro-glow, tiktok-vertical, karaoke, pop-words, frosted, editorial, handwritten, terminal, color-burst, iman-lowercase, beast-glow, signature-gold, beast-one-word, hormozi-pop, poster-hero, bounce-chunks, zone-jumper, podcast-karaoke, highlighter-marker, ghost-keywords, number-punch, smart-pop, brand-box, cycle-spotlight. New: `iman-lowercase` (clean lowercase Inter, the spoken word turns bold), `beast-glow` (white Bebas Neue caps, black outline, green glow, the spoken word in neon green), `signature-gold` (gold Caveat script, centered, the spoken word in pale cream). Caption-form presets: `beast-one-word` (one giant Anton word at a time, bounce entrance, active word yellow), `hormozi-pop` (3 Poppins caps words, the active word grows green and reflows its neighbours), `poster-hero` (stacked Anton poster, the active word is the big orange hero line), `bounce-chunks` (white Inter with black outline, 3 words, each bounces in), `zone-jumper` (Oswald caps chunks alternating center and bottom, active word sky blue), `podcast-karaoke` (left-aligned white Inter in 2-3 full lines, words light up as spoken). Highlight presets: `highlighter-marker` (yellow marker behind your keywords), `ghost-keywords` (faint upcoming words, keywords in cyan), `brand-box` (dark box, brand words on a violet tag), `number-punch` (numbers boxed in green, long words green), `smart-pop` (the key word of each line pops in yellow), `cycle-spotlight` (stacked caps cycling white, yellow, pink). Keywords come from `highlightWords` (no demo words built in): highlighter-marker, ghost-keywords and brand-box color exactly those words in their own colors (`highlightColor` recolors them); without `highlightWords` they show no keyword highlight. number-punch, smart-pop and cycle-spotlight need no words (numbers, word length and smart emphasis). Example: {"preset":"highlighter-marker","highlightWords":["free","today"]}. Per-call style (no saved preset needed): caption_video, burn_captions, preview, shorts, create_clips, remove_silences (with burnCaptions), translate with burn, batch items, request_review and burn_captions {mode:'client_script'} (REST: the same body fields on POST /v1/captions, /v1/captions/burn, /v1/captions/preview, /v1/shorts, /v1/clips, /v1/trim, /v1/translate, /v1/batch, /v1/reviews, /v1/captions/prepare) accept `styleOverrides` (style fields deep-merged onto the preset, null removes a field, validated like custom presets with bundled fonts only; 422 `invalid_style` lists bad fields) and `faceAvoid: true` (shortcut for styleOverrides.faceAvoid: captions move off faces, sampled at 2 fps; the result returns `faceAvoid.faceLayout`). Same price. Example: `{"sourceUrl": "https://awesomevideoeditor.com/samples/cc0-interview-es.mp4", "preset": "builtin:hormozi-pop", "faceAvoid": true, "styleOverrides": {"fontSize": 72, "maxWordsPerCaption": 2, "wordEntrance": "bounce", "wordStateStyles": {"active": {"color": "#FACC15"}}}}`. Caption-form fields: maxWordsPerCaption (1-N words per caption), activeWordReflow (grown active word pushes neighbours), wordEntrance (bounce, slide-up, fade) + wordEntranceDuration, positionMode (cycle with positionCycle, keyword with positionKeywords + keywordPosition), captionLayout "stacked" + posterHeroScale, faceAvoid. Preview before ordering, free: MCP `preview {mode:'sample'}` (REST POST https://api.awesomevideoeditor.com/v1/captions/style-preview) never charges and never transcribes. It takes the same look fields as `caption_video` (sourceUrl/fileId, preset or presets (up to 12; default 6 for the video shape), language, translateTo, brandPresetId, styleOverrides, faceAvoid, highlightWords, highlightColor, platform, autoFit) plus preview-only `text` (sample phrase, max 80 chars), `fullText`, `atSeconds` (one second or up to 3, one sheet row each; default a frame with a face, else the middle) and `transcriptionJobId`/`subtitles` (show the real caption at that second). Each preset is rendered exactly like the burn: same output size, autoFit sizing, words per caption, safe zone, face avoidance and engine, on the real frame. If the text is longer than one caption you see the chunk on screen at that second (`truncated: true`), like the burn; `fullText: true` shows every line but no longer matches a burn. Response: `sheetUrl` (labeled contact sheet), `presets[].frames[]` (url per second) and `presets[].captionVideoArgs`: pass it unchanged to `caption_video` (or POST /v1/captions) to get what you saw. Limits: 30 sheets/hour and 200/day per key (up to 3 seconds = one sheet); 429 `rate_limited` with `retryAfterSeconds`; identical repeats come from cache and do not count. A brand logo is not drawn in the preview. Preview then order (example): 1. `preview` {"mode":"sample","sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","presets":["hormozi-pop","podcast-karaoke","clarity"],"language":"es","text":"Así se verán tus subtítulos","platform":"youtube","faceAvoid":true,"atSeconds":[2,5]} 2. Show `sheetUrl`; the person picks "podcast-karaoke". 3. `caption_video` with that preset's `captionVideoArgs`: {"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","preset":"podcast-karaoke","language":"es","platform":"youtube","faceAvoid":true} Audio-only input (podcast, voice note: mp3, m4a, wav, ...): `caption_video` and `burn_captions` (POST https://api.awesomevideoeditor.com/v1/captions, /v1/captions/burn) return an MP4 with one of ten editorial podcast designs plus the captions, drawn on the server by the web editor's own canvas code (same frames as exporting the audio in the editor). Same price as a video: 5 credits/min caption, 4 burn. `preview {mode:'sample'}` with `audioVisual` is free. Catalog with names, descriptions, fields, recommended caption presets and preview images: GET https://api.awesomevideoeditor.com/v1/audio-visuals (MCP `get_catalog {kind:'audio_visuals'}`), free, no key. Designs (`audioVisual.variant`, default `editorial-cover`): - `swiss-grid` (Swiss grid, light): International-style poster: a huge episode numeral on a six-column grid, one red hairline tracing the last 1.6 s of voice, progress rule and timecode. Fields: showName, episode, speaker. Empty fields: No episode: the numeral becomes the running timecode. No show/speaker: those labels are omitted. - `braun-radio` (Braun radio, light): Dieter Rams-style radio: tuning scale with an orange needle that follows the voice, perforated grille, two knobs (voice level, elapsed time). Fields: showName, episode, speaker. Empty fields: Labels are omitted; the radio itself carries the design. - `riso` (Riso print, light): Two-ink risograph: halftone discs in fluoro pink and blue overprint and breathe with the voice; misregistered type on paper tooth. Fields: showName, episode, speaker. Empty fields: No show name: the big title reads PODCAST. - `editorial-cover` (Editorial cover, light): Magazine cover: serif masthead and issue line; the sentence is set as a pull-quote word by word, with a hairline under the spoken word that thickens with the voice. Fields: showName, episode, speaker. Empty fields: No show name: the masthead reads Podcast. No speaker: the byline is omitted. - `bauhaus` (Bauhaus, light): Circle, square and half-disc on a grid; each answers the voice with its own small delay. Heavy lowercase type. Fields: showName, episode, speaker. Empty fields: The type stack is omitted; the composition stands alone. - `continuous-line` (Continuous line, light): One pen line writes the voice across ruled rows, back and forth so it never lifts; a nib dot marks the tip. Fields: showName, episode, speaker. Empty fields: Labels are omitted. - `vinyl` (Vinyl, dark): Top-down turntable: matte record turning at 33 rpm, cover art on the label, a light sheen that brightens with the voice, tonearm moving with progress. Fields: showName, episode, speaker, coverSrc. Empty fields: No cover: a plain label in the ink colour with the show name (or nothing). - `type-wave` (Type as waveform, dark): The captions are the visual: each word is set at the weight of its own loudness (Inter 200-900), with a live weight scale. Fields: showName, episode, speaker. Empty fields: Labels are omitted. In preset mode the show name (or PODCAST) breathes in weight instead. - `duotone-portrait` (Duotone portrait, light): Cover art or host photo in two inks, framed by a hairline that carries the voice around its edge; heavy caps with a marker block on the spoken word. Fields: showName, episode, speaker, coverSrc. Empty fields: No cover: a two-ink gradient field with the show's initials. - `ma` (Ma, light): Japanese restraint: one sumi ink dot on washi that breathes, slow rings on loud syllables, a vermilion seal and a vertical label. Fields: showName, episode, speaker. Empty fields: No show name: the seal is a plain vermilion square. `audioVisual` fields (all optional): - `showName` (string, max 60), `episode` (string or number, max 12), `speaker` (string, max 60): printed by the design; empty ones are left out. - `coverImageUrl` (public https) or `coverFileId` (from `upload {action:'start'}`): PNG/JPEG/WebP up to 5 MB, fetched before any charge; used by vinyl (record label) and duotone-portrait (two-ink portrait). Other designs ignore it with a warning. - `background` (paper), `accent`, `ink`: #rgb or #rrggbb. Default: the design's palette. Changing the paper picks a contrasting ink automatically unless `ink` is set. - `captionMode`: `integrated` (default) = the design sets each sentence itself, word by word; the caption preset is not drawn. `preset` = your caption preset draws and the design keeps its caption band clear. - `contrastGuard` (default true, preset mode): a preset whose text colour is too close to the paper (white text on a light design) switches to the design's ink without stroke/shadow. Light designs read best with Editorial, Sharp Notes or Frosted; dark designs (vinyl, type-wave) with Clarity, Iman Lowercase or Podcast Karaoke. - `aspect` 9:16 (default, or from `platform`) | 16:9 | 1:1 | 4:5, or `width`+`height` (128-3840); `enabled` false = paper + captions only; `overlays` up to 8 image/text items. - Retired visualizer ids still work and render their replacement, with a `warnings` entry on the job: 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. Their `presetId`/`config` fields are ignored (warning), gradient backgrounds fall back to the design's paper. - Errors: unknown variant/field, bad colour, too-long text, unreachable or non-image cover: 422 `invalid_audio_visual`, `charged: false`. curl: curl -X POST https://api.awesomevideoeditor.com/v1/captions -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" -d '{"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","platform":"tiktok","audioVisual":{"variant":"editorial-cover","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}}' MCP: caption_video {"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","audioVisual":{"variant":"vinyl","showName":"Field Notes","coverImageUrl":"https://example.com/cover.jpg"}} Python: requests.post("https://api.awesomevideoeditor.com/v1/captions", headers={"Authorization": f"Bearer {key}"}, json={"fileId": file_id, "preset": "editorial", "audioVisual": {"variant": "riso", "captionMode": "preset", "showName": "Field Notes"}}).json() Copy-paste per design (REST body for POST /v1/captions; the same `audioVisual` object works in MCP caption_video, burn_captions and preview {mode:'sample'}): - swiss-grid: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"swiss-grid","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - braun-radio: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"braun-radio","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - riso: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"riso","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - editorial-cover: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"editorial-cover","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - bauhaus: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"bauhaus","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - continuous-line: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"continuous-line","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - vinyl: {"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","audioVisual":{"variant":"vinyl","showName":"Field Notes","episode":"12","speaker":"Alex Doe","coverImageUrl":"https://example.com/cover.jpg"}} - type-wave: {"sourceUrl":"https://example.com/episode.mp3","preset":"clarity","audioVisual":{"variant":"type-wave","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - duotone-portrait: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"duotone-portrait","showName":"Field Notes","episode":"12","speaker":"Alex Doe","coverImageUrl":"https://example.com/cover.jpg"}} - ma: {"sourceUrl":"https://example.com/episode.mp3","preset":"editorial","audioVisual":{"variant":"ma","showName":"Field Notes","episode":"12","speaker":"Alex Doe"}} - preset captions on a light design: {"audioVisual":{"variant":"swiss-grid","captionMode":"preset"},"preset":"sharp-notes"} - own colours: {"audioVisual":{"variant":"ma","background":"#14213d","accent":"#f2c14e"}} (ink becomes light automatically) - free preview first: preview {"mode":"sample","sourceUrl":"https://example.com/episode.mp3","presets":["clarity"],"audioVisual":{"variant":"type-wave","showName":"Field Notes"}} - legacy request (still works, warns): {"audioVisual":{"variant":"bars"}} renders swiss-grid. A brand logo is drawn bottom right. preview, shorts and create_clips on audio return 422 `audio_only_input`, not charged. Long audio renders in 2-minute pieces that a retry or `resume_job` reuses; drawing takes about 0.2-0.4x the audio length on one vCPU; on staging a 50 s episode finished in 1-2.5 minutes end to end, transcription included. Style reference: `get_catalog {kind:'styles'}` (MCP) / GET https://api.awesomevideoeditor.com/v1/style-reference (free, no key) lists every style field the web editor has, with type, values/range and examples. Word highlights: `wordHighlights: {rules: [{id, enabled, color, backgroundColor?, words?, minLength?}], customLists?: [{id, name, enabled, color, backgroundColor?, words}]}`; rule ids numbers (digits, %), custom (its words list), acronym (ALL CAPS), hashtag (# and @), long (longer than minLength), person/orgloc (web editor NLP only; use custom words for server burns). Keywords in an accent color: `{"rules":[{"id":"custom","enabled":true,"color":"#FACC15","words":["gratis","AwesomeVideo"]}]}` or the shortcut `highlightWords: ["gratis","AwesomeVideo"], highlightColor: "#FACC15"` on any burn tool. Numbers: `{"rules":[{"id":"numbers","enabled":true,"color":"#F59E0B"}]}`. Marker background: `{"rules":[{"id":"custom","enabled":true,"color":"#000000","backgroundColor":"#FACC15","words":["oferta"]}]}`. Smart emphasis: `smartEmphasis: {enabled: true, target: "auto", style: "color"|"pop"|"pill", intensity: "low"|"med"|"high", color: "#A855F7"}` (server burns support target auto; verbs/nouns/numbers/custom are web-only, use wordHighlights instead). Word states: `wordStateStyles: {"active": {"color": "#FACC15", "scaleBy": 1.2}, "upcoming": {"opacity": 0.5}}` with revealMode word-by-word. Color cycle: `segmentColorCycle: {"enabled": true, "segmentSize": 2, "mode": "fixed", "variants": [{"text": "#FFFFFF"}, {"text": "#FACC15"}]}`. Free price checks: `quoteOnly: true` returns {costCents, breakdown, charged:false} without starting a job on create_clips (POST /v1/clips, needs durationSeconds), remove_silences (POST /v1/trim, durationSeconds; upper bound since it bills kept minutes) and generate_metadata (POST /v1/metadata; durationSeconds only when passing media without a transcript). `get_catalog {kind:'presets'}` returns each style JSON. ## Free tools MCP 0.4.0 names: `create_key`, `import_url` (POST /v1/uploads/import), `upload` (every action: start, start_multipart, status, complete, abort, inline), `estimate` (REST /v1/quote and /v1/plan), `get_catalog` (presets, styles, voices, platforms, audio_visuals), `get_account`, `get_job`, `list_jobs`, `edit_transcript` (PATCH /v1/jobs/:id; next burn pays only the burn), `burn_captions {mode:'client_script'}` (returns ASS to render in a browser at no cost), `preview {mode:'sample'}`, `get_presets` / `manage_preset` (brand and custom presets, validate, submit; see Custom presets), `get_glossary` / `update_glossary`, `create_checkout`, webhooks, and `notifyEmail`. `plan`: `POST /v1/plan` (no key needed, never charges, 120/hour per IP) with `steps` (ordered: caption with optional `translateTo` (= caption_video), transcribe, translate, burn with `renderer` server|client, shorts with `count`/`minSeconds`/`maxSeconds`, trim with `keepSeconds`, preview, dub with `targetLanguage`/`voiceTier`) and `source` (`durationSeconds`, `bytes`, `via` upload|url, `transcriptCues`, or `mediaUrl`, sized with one HEAD request). Transcription is added when a later step needs a transcript unless `hasTranscript` is true, and translation before dub unless `hasTranslation` is true. Returns each step's credits, `totalCredits`, `totalUsd`, `freeAlternatives` (client burn is free), `feasible`, `limitViolations` (`code`, `limit`, `actual`, `unit`, `message`, `hint`), `limits`, and with a key `account.balanceCents` and `account.sufficient`. Call it before a pipeline. Limits: stored files (`fileId`) up to 2048 MB (one PUT or `POST /v1/uploads` up to 80 MB; larger via multipart upload or `import_url`), `mediaUrl` on a paid call up to 80 MB (a larger Content-Length is rejected before download; use `import_url` for bigger links), `dub` sources up to 80 MB for now, up to 3 hours, shorts 1-5 clips of 5-60 s, shorts transcripts up to 4000 cues (read in windows of 400). Paid tools check these before reserving credits and return 422 `limit_exceeded` with `violations` and `charged: false`. `quote`: `POST /v1/quote` with `operation` (default caption; caption with optional `translateTo`, transcribe, burn, preview, translate, shorts, trim, dub with `voiceTier` and `targetLanguage`) and `durationSeconds`, or `fileId` / `mediaUrl` (or `sourceUrl`) with a key, e.g. `{"operation":"caption","sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4"}`. Never debits. Trim quotes from media are an upper bound because trim bills kept seconds. ## Media Local files (for example a video the user attached in chat): call MCP `upload {action:'start'}` (or `POST /v1/uploads/url`) with `filename`, `contentType`, `sizeBytes` (JSON). Do not send that JSON to `POST /v1/uploads`: it takes multipart/form-data only and answers 400 `multipart_form_required`; it is free, checks limits first, and returns `fileId` plus a single-use `uploadUrl` valid 15 minutes. PUT the raw bytes there (`curl -X PUT --data-binary @clip.mp4 -H "Content-Type: video/mp4" ""`, no API key needed) and pass `fileId` to any tool. Clips up to 10 MB can go inline with MCP `upload {action:'inline'}`. Over 80 MB (up to 2048 MB), or on a flaky connection, use a resumable multipart upload (see below). A public link: MCP `import_url` (or `POST /v1/uploads/import` with `{"url": "..."}`, free, 30/hour) downloads it server-side into storage and returns a `fileId` (direct http/https file links, chat attachment URLs, Google Drive including the large-file confirm page, Dropbox, OneDrive; up to 2048 MB when the host sends Content-Length, streamed straight to storage, otherwise 80 MB; the cap is checked on Content-Length and while streaming; private, loopback, link-local, and metadata addresses, non-default ports, and redirects to them are blocked). Or upload with `POST /v1/uploads` (multipart `file`, up to 80 MB) and pass `fileId`, or pass `mediaUrl` (public https, up to 80 MB and 3 hours). Google Drive, Dropbox, and OneDrive share links are converted to direct downloads. YouTube, TikTok, and Instagram links are not supported. Results expire after 24 hours by default. Identical media and settings are cached per key and not charged twice. ### Large files: resumable multipart upload (up to 2048 MB) 1. MCP `upload {action:'start_multipart'}` (or `POST /v1/uploads/multipart`) with `{"filename":"talk.mp4","contentType":"video/mp4","sizeBytes":734003200}` (optional `partSizeBytes`, 5-95 MB, default 64 MB). Free; returns `fileId`, `partCount`, `parts` (`partNumber`, `offset`, `length`, `url`), `statusUrl`, `completeUrl`, `abortUrl`. Valid 24 hours. The URLs carry the upload token, so no API key is needed on them. 2. PUT each part's bytes. Any order, in parallel if you like, and re-sending a part just replaces it: ```bash # parts.json = the "parts" array from step 1 jq -c '.[]' parts.json | while read -r p; do off=$(jq -r .offset <<<"$p"); len=$(jq -r .length <<<"$p"); url=$(jq -r .url <<<"$p") tail -c +$((off+1)) talk.mp4 | head -c "$len" | curl -sf -X PUT --data-binary @- -H "Content-Length: $len" "$url" done ``` 3. Interrupted? MCP `upload {action:'status'}` (or `GET `) returns `missingParts`, `bytesReceived`, and `missing` with each missing part's offset, length, and url. PUT only those. 4. MCP `upload {action:'complete'}` (or `POST `) assembles the file; it is idempotent, and 409 `upload_incomplete` lists `missingParts`. Then pass `fileId` to `caption_video`, `transcribe`, `burn_captions`, `shorts`, `trim`, or `preview`, like any upload. `upload {action:'abort'}` (`DELETE `) cancels. Python, same flow: `for p in parts: f.seek(p["offset"]); requests.put(p["url"], data=f.read(p["length"]))`, then `requests.post(completeUrl)`. Files over 80 MB are never loaded into memory: jobs stream them to the renderer once and reuse that copy. ## Webhooks and email - Per-request: pass `webhookUrl` (public https) and/or `notifyEmail` on any paid call, on any key. The POST is signed: headers `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,`. The `whsec_` secret is returned on the first job that sets `webhookUrl` and at `GET /v1/webhook-secret`; use it as is. Three tries, no redirects. - Account webhook: Pro and Scale accounts can save one webhook for all jobs with `PATCH /v1/account` `{"webhookUrl": "https://..."}` and rotate its secret with `POST /v1/account/webhook/rotate`. ## Errors JSON `{"error": code, "message": text}` (MCP error results add `code`, `status`, `hint` = what to do next, and `retryable`). 400 invalid input, 401 missing or invalid key (the message says how to get one), 402 insufficient_balance, 404 not found, 409 conflict (e.g. `max_credits_exceeded`, `account_required`), 429 rate_limited (nothing charged; wait the `Retry-After` header, also `retryAfterSeconds` in the body; uploads 30/hour, jobs 30-60/hour per key, plan 120/hour per IP).