WowReveal
从视频链接制作带旁白的 9:16 短视频:AI 故事、配音、字幕、片段和 AI 视频。
托管 MCP 服务器
npx add-mcp 'https://wowreveal.com/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
API · MCP · Agents
Let your AI agent run your Reels studio
Connect Claude, Cursor or any MCP agent to WowReveal in one line. Ask in plain words — it finds trending videos, makes story shorts in 27 languages, writes post kits and hands you the links.
Get your API keyRead the docs
Included on every paid plan · same credits as the app
Claude · WowReveal connected MCP
Works with
- Claude Code
- Claude Desktop
- claude.ai
- Cursor
- Windsurf
- Cline
- VS Code
- OpenAI Agents SDK
How it works
From zero to an agent that ships reels in under two minutes.
- 01
Create an API key
In Developers inside the app. Keys are shown once, stored hashed and revocable anytime. - 02
Connect your agent
One command for Claude Code, a connector for claude.ai, a JSON block for Cursor and the rest. - 03
Ask in plain words
The agent picks the tools, checks the price, starts jobs and polls until your videos are ready.
Connect your agent
One endpoint for every client. Paste your key where it says YOUR_API_KEY.
MCP server URL
Streamable HTTP · stateless · sign-in (OAuth) or API key: Bearer or X-API-Key
Connect by signing in — no key
Add the MCP server URL above as a connector and sign in to WowReveal when asked. A page tells you what the app may do; press Allow. You can disconnect it any time in Settings → Security → Connected apps. Needs a paid plan with API & MCP access.
- Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector, paste the URL, then Connect.
- Claude Code: run claude mcp add --transport http wowreveal https://wowreveal.com/mcp, then /mcp → Authenticate.
- ChatGPT: in Settings → Connectors add a custom MCP connector (on some plans it needs Developer mode), paste the URL and choose OAuth.
- VS Code: run “MCP: Add Server…”, choose HTTP, paste the URL and allow access when the browser opens.
- Cursor: add the URL as shown in the Cursor tab below (no key), then press Connect next to WowReveal in Settings → MCP and sign in.
- A client that can only send a key: use the key setup below.
Run this once in your terminal. Then ask Claude anything — try “What's my WowReveal balance?”.
bash
<code>claude mcp add --transport http wowreveal https://wowreveal.com/mcp --header "Authorization: Bearer YOUR_API_KEY"</code>
Check the connection with /mcp inside Claude Code.
Share with your team (.mcp.json)
Commit this file and let each teammate set WOWREVEAL_API_KEY in their environment.
.mcp.json
<code>{
"mcpServers": {
"wowreveal": {
"type": "http",
"url": "https://wowreveal.com/mcp",
"headers": {
"Authorization": "Bearer ${WOWREVEAL_API_KEY}"
}
}
}
}</code>
Every tool your agent needs
Read tools are free. Write tools spend the same credits as the app — and failed jobs are refunded automatically.
35 tools with clear names, descriptions and safety hints. Prices are live.
| Tool | What it does | Cost |
|---|---|---|
| Account & catalogs | ||
get_account | Balance, plan, plan limits and current prices. Agents call it first. | Free |
list_templates | Niche templates (talent shows, makeovers, animal rescue…) with their default settings. | Free |
list_languages | The 27 languages for scripts, voiceovers, captions and post kits. | Free |
list_caption_styles | Animated caption styles you can pick per video. | Free |
list_voices | AI narrator voices — storytelling voices first. | Free |
list_brand_assets | Your Brand Kit logos and music plus the free library — ids for the logo and music settings. | Free |
estimate_credits | Price any action before running it and check the balance covers it. | Free |
| Shorts & projects | ||
create_shortBackground job | Story, transformation or best-moment short from a link or upload — returns the job id instantly. | Story 8 credits · Transformation 14 credits · Clips 3 credits |
get_project | Status, progress, script and the signed video link when it's ready. | Free |
list_projects | Your projects, newest first, with status filters and pagination. | Free |
wait_for_project | Waits up to 50 s for a job to finish — no tight polling loops. | Free |
retry_projectBackground job | Runs a failed project again at the current price — no new upload or link needed. | Current price of its tool |
delete_project | Deletes a finished or failed project and its files for good. | Free |
create_compilationBackground job | Numbered “Top 10” long video from your finished shorts. | 8 credits |
| AI Clipper | ||
start_clipperBackground job | Analyses a long video and proposes the best self-contained clips. | 6 credits / 30 min of source |
get_clip_plan | Clip candidates with scores, timecodes and reasons. | Free |
generate_clipsBackground job | Renders the clips you picked as captioned 9:16 videos. | 2 credits / clip |
| Instant tools | ||
write_script | Viral narration script from a video or a text, sized to the length you need. | 1 credit |
create_post_kit | Titles, description, hashtags and first comment per platform and language. | 1 credit |
write_hooks | Ten opening lines for the first 3 seconds, for a topic or a script, in the styles and language you pick. | 1 credit |
rewrite_text | A caption, post or script rewritten for Reels, Shorts, TikTok, Threads, X or Telegram. | 1 credit |
translate_text | A text translated into any of the 27 languages, keeping links, @mentions, hashtags and emojis. | 1 credit |
video_ideas | Video ideas for a niche, or a 7- or 30-day content plan. | 2 credits |
reply_to_comment | Three reply options to a viewer's comment, in your tone. | 1 credit |
repurpose_text | A long text or transcript turned into a short script, thread, carousel or newsletter paragraph. | 2 credits |
create_cover | Cover / thumbnail JPEG from a video frame or an image, with a bold headline. | 2 credits |
generate_voiceover | Text → natural MP3 voiceover in any of the 27 languages. | 1 credit / 100 chars |
| Planning | ||
search_trends | Recent viral YouTube videos in a niche, ranked by views per day. | 1 credit · repeats free |
earnings_estimate | Rough payout range for a view count by platform, audience, niche and originality — an estimate, not a promise. | Free |
| AI Studio | ||
import_image | Give it a picture by link or base64 — the start image for image presets and image-to-video. | Free |
list_studio_models | Image & video models available to you, with their settings and prices. | Free |
list_studio_presets | One-click effects: camera moves, transitions, VFX, product shots. | Free |
studio_generateBackground job | Generate AI images or videos — returns generation ids instantly. | Per model |
get_generation | Status and signed output links of a generation. | Free |
list_generations | Your AI Studio generations, newest first, with signed output links. | Free |
Account & catalogs
get_accountFree Balance, plan, plan limits and current prices. Agents call it first.list_templatesFree Niche templates (talent shows, makeovers, animal rescue…) with their default settings.list_languagesFree The 27 languages for scripts, voiceovers, captions and post kits.list_caption_stylesFree Animated caption styles you can pick per video.list_voicesFree AI narrator voices — storytelling voices first.list_brand_assetsFree Your Brand Kit logos and music plus the free library — ids for the logo and music settings.estimate_creditsFree Price any action before running it and check the balance covers it.
Shorts & projects
create_shortStory 8 credits · Transformation 14 credits · Clips 3 credits Story, transformation or best-moment short from a link or upload — returns the job id instantly. Background jobget_projectFree Status, progress, script and the signed video link when it's ready.list_projectsFree Your projects, newest first, with status filters and pagination.wait_for_projectFree Waits up to 50 s for a job to finish — no tight polling loops.retry_projectCurrent price of its tool Runs a failed project again at the current price — no new upload or link needed. Background jobdelete_projectFree Deletes a finished or failed project and its files for good.create_compilation8 credits Numbered “Top 10” long video from your finished shorts. Background job
AI Clipper
start_clipper6 credits / 30 min of source Analyses a long video and proposes the best self-contained clips. Background jobget_clip_planFree Clip candidates with scores, timecodes and reasons.generate_clips2 credits / clip Renders the clips you picked as captioned 9:16 videos. Background job
Instant tools
write_script1 credit Viral narration script from a video or a text, sized to the length you need.create_post_kit1 credit Titles, description, hashtags and first comment per platform and language.write_hooks1 credit Ten opening lines for the first 3 seconds, for a topic or a script, in the styles and language you pick.rewrite_text1 credit A caption, post or script rewritten for Reels, Shorts, TikTok, Threads, X or Telegram.translate_text1 credit A text translated into any of the 27 languages, keeping links, @mentions, hashtags and emojis.video_ideas2 credits Video ideas for a niche, or a 7- or 30-day content plan.reply_to_comment1 credit Three reply options to a viewer's comment, in your tone.repurpose_text2 credits A long text or transcript turned into a short script, thread, carousel or newsletter paragraph.create_cover2 credits Cover / thumbnail JPEG from a video frame or an image, with a bold headline.generate_voiceover1 credit / 100 chars Text → natural MP3 voiceover in any of the 27 languages.
Planning
search_trends1 credit · repeats free Recent viral YouTube videos in a niche, ranked by views per day.earnings_estimateFree Rough payout range for a view count by platform, audience, niche and originality — an estimate, not a promise.
AI Studio
import_imageFree Give it a picture by link or base64 — the start image for image presets and image-to-video.list_studio_modelsFree Image & video models available to you, with their settings and prices.list_studio_presetsFree One-click effects: camera moves, transitions, VFX, product shots.studio_generatePer model Generate AI images or videos — returns generation ids instantly. Background jobget_generationFree Status and signed output links of a generation.list_generationsFree Your AI Studio generations, newest first, with signed output links.
earnings_estimate gives rough public ranges, not a promise. It follows Meta's March 2026 originality rule: someone else's footage counts as original only when you appear in it and add something new. So unless you say the footage is your own (or you are on screen), it assumes reworked footage, which pays far less. Meta alone decides who is paid.
What you can ask
Paste into Claude once WowReveal is connected. The agent picks the tools, checks your balance and polls the jobs.
“Find 5 trending talent show auditions from this week and make story shorts in Spanish with the talent-show template. Wait until they're done and give me the video links.”
“Analyse this podcast with the AI Clipper and render the 4 highest-scoring clips with captions: https://www.youtube.com/watch?v=…”
“What's my WowReveal balance, and how many story shorts and transformation shorts can I still afford this month?”
“Write a Facebook post kit in Russian for my latest finished short and suggest the best time to post it.”
“Make a countdown compilation “Top 5 golden buzzers” from my five most recent finished shorts.”
“My Facebook Reels page posts footage I film myself and gets 2 million views a month, mostly from the US. Estimate the payout range and tell me what Meta's originality rule changes.”
REST API reference
JSON over HTTPS. Base URL https://wowreveal.com/api/v1. Same validation, limits and credits as the app.
- GET
/api/v1/meAccount: balance, plan, limits and current prices. Free - GET
/api/v1/templates?locale=enNiche templates, localised (locale=en|ru). Free - GET
/api/v1/languagesContent languages. Free - GET
/api/v1/caption-stylesCaption styles. Free - GET
/api/v1/voicesNarrator voices. Free - GET
/api/v1/assets?kind=logoBrand Kit logos and music (yours + the library) with preview links. Ids for settings.logoAssetId (null = no logo), settings.logoPosition and settings.music. Free - POST
/api/v1/uploadsUpload a video, audio or image (multipart, field “file”) → upload id. Unused uploads are deleted after 48 hours. Free - POST
/api/v1/uploads/from-urlGive an image by an https link ({ url }): downloaded here (public addresses only, 10 MB at most) and stored as an upload. Free - GET
/api/v1/uploads/:idOne upload: kind, size, duration. 404 once it has been cleaned up. Free - POST
/api/v1/projectsStart story / transformation / clips shorts from links or uploads.Idempotency-Key Story 8 credits · Transformation 14 credits · Clips 3 credits - GET
/api/v1/projectsList projects (status, tool, posted, q, cursor, limit). Free - GET
/api/v1/projects/:idOne project with signed video, download and thumbnail links. Free - PATCH
/api/v1/projects/:idRename a project ({ name }). Free - DELETE
/api/v1/projects/:idDelete a project and its files (409 JOB_IN_PROGRESS while it is being made). Free - POST
/api/v1/projects/:id/retryRun a failed project again (retryable: true) at the current price of its tool.Idempotency-Key Current price of its tool - POST
/api/v1/compilationsNumbered compilation from finished projects.Idempotency-Key 8 credits - POST
/api/v1/clipper/plansAI Clipper analysis of a long video.Idempotency-Key 6 credits / 30 min of source - GET
/api/v1/clipper/plansYour 20 latest clip plans, newest first. Free - GET
/api/v1/clipper/plans/:idClip plan status, candidates, the style settings new clips get and when the plan expires (7 days after it is ready). Free - POST
/api/v1/clipper/plans/:id/generateRender chosen candidates. Optional: settings (another caption style, layout, music…) and cuts (a new start / end per candidate, up to 10 s beyond the AI's) — same price per clip.Idempotency-Key 2 credits / clip - POST
/api/v1/post-kitTitles, description, hashtags, first comment.Idempotency-Key 1 credit - POST
/api/v1/hooksTen opening lines for a topic or a script (platform, language, styles).Idempotency-Key 1 credit - POST
/api/v1/rewriteA text rewritten for one platform (tone, length, emojis, hashtags).Idempotency-Key 1 credit - POST
/api/v1/translateA text translated into one of the 27 content languages, optionally adapted for a country.Idempotency-Key 1 credit - POST
/api/v1/ideasVideo ideas for a niche, or a 7- or 30-day content plan.Idempotency-Key 2 credits - POST
/api/v1/comment-repliesThree reply options to a viewer's comment.Idempotency-Key 1 credit - POST
/api/v1/repurposeA long text turned into a short script, thread, carousel or newsletter paragraph.Idempotency-Key 2 credits - POST
/api/v1/scriptNarration script from a video or text.Idempotency-Key 1 credit - POST
/api/v1/ttsText → MP3 voiceover (signed link).Idempotency-Key 1 credit / 100 chars - POST
/api/v1/coverCover JPEG from a finished project or an uploaded image / video, with a headline (vertical, horizontal or both).Idempotency-Key 2 credits - POST
/api/v1/trends/searchTrending videos for a niche or query. 1 credit · repeats free - GET
/api/v1/studio/modelsAI Studio models and presets. Free - POST
/api/v1/studio/generationsStart AI image / video generations.Idempotency-Key Per model - GET
/api/v1/studio/generationsList generations (kind, status, favorite, cursor, limit). Free - GET
/api/v1/studio/generations/:idGeneration status and signed outputs. Free - DELETE
/api/v1/studio/generations/:idDelete a generation and its files (409 while it runs). Free - POST
/api/v1/studio/generations/:id/to-uploadCopy a studio output into an upload ({ index }) — a source for a short or a compilation. Free - POST
/api/v1/estimatePrice an action before running it. Free - POST
/api/v1/earnings/estimateCreator payout estimate (originality as Meta's 2026 rule reads it). Free - GET
/api/v1/webhooksYour webhooks. Free - POST
/api/v1/webhooksAdd a webhook ({ url, events? }). The signing secret comes back once. Free - PATCH
/api/v1/webhooks/:idChange a webhook's address or events, or turn it off / on. Free - DELETE
/api/v1/webhooks/:idDelete a webhook. Free - POST
/api/v1/webhooks/:id/testSend a test event to the webhook now (one try). Free - GET
/api/v1/webhooks/:id/deliveriesThe webhook's delivery log, newest first (30 days). Free - GET
/api/v1/openapi.jsonThis API as an OpenAPI 3.1 document. Public: no key needed. Free
Request & response
POST /api/v1/projects — request
<code>{
"tool": "story",
"sources": [
{
"url": "https://www.youtube.com/watch?v=VIDEO_ID"
}
],
"settings": {
"templateId": "talent-show",
"language": "es",
"targetSeconds": 35,
"captionStyle": "pop_bounce",
"voiceId": "nPczCjzI2devNBz1zQrb",
"music": "auto",
"headline": true,
"ending": "follow"
}
}</code>
201 Created
<code>{
"projects": [
{
"id": "6f1c2d9e-8a41-4c1b-9f0e-2b7d5a3c9e11",
"name": "Golden buzzer audition",
"tool": "story",
"templateId": "talent-show",
"language": "es",
"status": "queued",
"step": "queued",
"progress": 0,
"videoUrl": null,
"downloadUrl": null,
"thumbnailUrl": null,
"queue": {
"position": 2,
"ahead": 1
},
"creditsCharged": 8,
"createdAt": "2026-10-04T09:30:00.000Z"
}
],
"creditsCharged": 8,
"balance": 442
}</code>
GET /api/v1/projects/:id — when complete
<code>{
"project": {
"id": "6f1c2d9e-8a41-4c1b-9f0e-2b7d5a3c9e11",
"status": "complete",
"step": "complete",
"progress": 100,
"title": "Nadie esperaba esta voz…",
"durationSec": 34.2,
"videoUrl": "https://wowreveal.com/api/media/eyJrIjoicHYi…",
"downloadUrl": "https://wowreveal.com/api/media/eyJrIjoicHYi…d",
"thumbnailUrl": "https://wowreveal.com/api/media/eyJrIjoicHQi…",
"captionsUrl": "https://wowreveal.com/api/media/eyJrIjoicGMi…d",
"errorCode": null,
"completedAt": "2026-10-04T09:36:12.000Z",
"expiresAt": "2026-11-18T09:36:12.000Z"
}
}</code>
402 Payment Required
<code>{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits: 8 required, 3 available",
"details": {
"required": 8,
"balance": 3
}
}
}</code>
Authentication
Send your key in the Authorization header on every request: Authorization: Bearer wr_live_…. The MCP endpoint (/mcp) also takes it as X-API-Key: wr_live_…, for catalogs and clients that can only set that header; if both are sent, Bearer is used. Keys belong to your account, are stored as SHA-256 hashes and can be revoked anytime in Developers. Missing or revoked keys get 401 with a WWW-Authenticate header; plans without API access get 403.
http
<code>Authorization: Bearer wr_live_…</code>
MCP (/mcp) also accepts
<code>X-API-Key: wr_live_…</code>
Sign in with OAuth (no key)
MCP clients can connect without a key: the 401 of /mcp points to /.well-known/oauth-protected-resource/mcp (RFC 9728) and from there to the authorization server (/.well-known/oauth-authorization-server, RFC 8414). Apps register themselves (POST /oauth/register, RFC 7591, public clients), send the person to /oauth/authorize with PKCE (S256 is required) and the resource /mcp, and exchange the code at /oauth/token. The person signs in and presses Allow. Access tokens (wro_at_…) last 1 hour and work at /mcp and /api/v1 as Authorization: Bearer; refresh tokens last 60 days and are used once, each refresh returns a new one, and an old one used again closes the connection. Tokens are stored as hashes. Revoke with POST /oauth/revoke (RFC 7009); the person can disconnect any app in Settings → Security → Connected apps. A password change, signing out everywhere or deleting the account disconnects every app. Plan limits, rate limits and the kill switch apply as for keys.
Media links
Video, thumbnail and audio URLs in API and MCP responses are absolute signed links valid for 24 hours — download them or pass them on. Fetch the project again for fresh links.
Safe retries
Add an Idempotency-Key header (REST) or idempotency_key argument (MCP) to create calls. Repeating the same request with the same key within 24 hours returns the first result instead of charging again — also after our server restarts or updates. The same key with a different body returns 409. If the first request was cut off before it answered, the key answers 409 too: check your projects and, if nothing started, use a new key.
OpenAPI 3.1
The whole API as one document, for Postman, SDK generators and ChatGPT Actions. Request bodies are generated from the same schemas the server checks them with, so they cannot drift.
Webhooks
Skip the polling: register an https address and WowReveal sends it a signed JSON message the moment a job ends. Add one in Developers in the app (below your keys) or with POST /api/v1/webhooks — up to 5 per account. MCP agents can still use wait_for_project instead.
Events
project.completed
A short, clip or compilation is ready.
project.failed
A project failed — its credits are already refunded.
clipper.analysis_ready
A clip plan is ready: the candidates are in the message.
clipper.analysis_failed
A clip analysis failed — refunded.
studio.completed
An AI Studio generation is done.
studio.failed
An AI Studio generation failed — refunded.
You are told about every job of the account, also the ones started in the app. Leave events out to get them all.
Delivery rules
Answer with any 2xx within 10 seconds. Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours (seven tries in about 20 hours), then marked failed. The address must be https and public: private networks, redirects and invalid certificates are refused. A webhook that has had no successful delivery for 3 days is switched off. Every delivery is in the log in Developers, and “Send test event” sends a webhook.test message.
bash
<code>curl -s -X POST https://wowreveal.com/api/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/wowreveal-hook","events":["project.completed","project.failed"]}'</code>
What you receive
A POST with a JSON body. data holds the object exactly as the REST API returns it, with signed media links valid for 24 hours. id is the same on every retry — use it to ignore repeats.
POST · WowReveal-Event: project.completed
<code>{
"id": "evt_5f0c1d7a9e2b4c36a81d0f42",
"type": "project.completed",
"createdAt": "2026-10-19T09:36:12.418Z",
"data": {
"project": {
"id": "6f1c2d9e-8a41-4c1b-9f0e-2b7d5a3c9e11",
"status": "complete",
"title": "Nadie esperaba esta voz…",
"durationSec": 34.2,
"videoUrl": "https://wowreveal.com/api/media/eyJrIjoicHYi…",
"downloadUrl": "https://wowreveal.com/api/media/eyJrIjoicHYi…d",
"thumbnailUrl": "https://wowreveal.com/api/media/eyJrIjoicHQi…",
"errorCode": null
}
}
}</code>
Check the signature
Every message carries WowReveal-Signature: t=,v1=. v1 is the HMAC-SHA256 of “.” with your webhook's secret, which is shown once when you add it. Compute it over the raw body, compare in constant time and refuse a t older than five minutes. Also sent: WowReveal-Event, WowReveal-Event-Id and WowReveal-Delivery.
js
<code>import crypto from "node:crypto";
// rawBody: the request body exactly as received (a string or Buffer), not re-serialised JSON
export function isFromWowReveal(secret, rawBody, signatureHeader) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.trim().split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // too old: a replay
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}</code>
MCP and REST names
MCP tools take flat snake_case arguments; the REST API takes the nested camelCase bodies of the OpenAPI document. They do the same thing — this table maps the main ones. The other tools use the body fields of their endpoint in snake_case (voice_id is voiceId). With a preset, MCP fills the preset's prompt template from prompt and preset_values; REST takes the finished prompt.
create_short → POST /api/v1/projects
| MCP argument | REST field |
|---|---|
tool | tool |
url | sources[].url |
urls | sources[].url |
upload_id | sources[].uploadId |
name | sources[].name |
template_id | settings.templateId |
language | settings.language |
target_seconds | settings.targetSeconds |
genre | settings.genre |
caption_style | settings.captionStyle |
voice_id | settings.voiceId |
music | settings.music |
logo_asset_id | settings.logoAssetId |
logo_position | settings.logoPosition |
headline | settings.headline |
headline_text | settings.headlineText |
hook | settings.hookEnabled |
ending | settings.ending |
ending_text | settings.endingText |
ending_cta | settings.endingCta |
reveal_mode | settings.revealMode |
edit_mode | settings.editMode |
idempotency_key | Idempotency-Key header |
write_hooks → POST /api/v1/hooks
| MCP argument | REST field |
|---|---|
topic | topic |
script | script |
platform | platform |
language | language |
styles | styles |
translate_text → POST /api/v1/translate
| MCP argument | REST field |
|---|---|
text | text |
language | language |
adapt_for_country | adaptForCountry |
country | country |
reply_to_comment → POST /api/v1/comment-replies
| MCP argument | REST field |
|---|---|
comment | comment |
video_context | videoContext |
tone | tone |
creator_style | creatorStyle |
start_clipper → POST /api/v1/clipper/plans
| MCP argument | REST field |
|---|---|
url | source.url |
upload_id | source.uploadId |
max_clips | maxClips |
target_seconds | targetSeconds |
language | language |
caption_style | settings.captionStyle |
layout | settings.layout |
headline | settings.headline |
music | settings.music |
logo_asset_id | settings.logoAssetId |
generate_clips → POST /api/v1/clipper/plans/:id/generate
| MCP argument | REST field |
|---|---|
plan_id | :id in the path |
candidate_ids | candidateIds |
caption_style | settings.captionStyle |
create_compilation → POST /api/v1/compilations
| MCP argument | REST field |
|---|---|
project_ids | items[].projectId |
title | title |
format | format |
numbering | numbering |
intro_card | introCard |
outro_text | outroText |
language | language |
music | music |
studio_generate → POST /api/v1/studio/generations
| MCP argument | REST field |
|---|---|
model_key | modelKey |
preset_id | presetId |
prompt | prompt |
negative_prompt | negativePrompt |
params | params |
start_upload_id | inputs[]: { role: "start", uploadId } |
start_generation_id | inputs[]: { role: "start", generationId } |
end_upload_id | inputs[]: { role: "end", uploadId } |
reference_upload_ids | inputs[]: { role: "reference", uploadId } |
count | count |
Rate limits
Limits are per account and shared with the app. Over the limit you get 429 RATE_LIMITED with a Retry-After header. Plans also cap parallel jobs (ACTIVE_JOBS_LIMIT).
All API & MCP requests
120 / min
Video jobs (shorts, clipper, compilations)
20 / min
Instant tools (script, post kit, voice, trends)
30 / min
AI Studio generations
30 / min
Uploads
60 / hour
Every API and MCP answer reports the tightest limit the request counted against: RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until it frees one more call). Slow down before Remaining reaches 0; at 0, wait RateLimit-Reset seconds. A 429 has the same number in Retry-After.
http
<code>RateLimit-Limit: 20
RateLimit-Remaining: 19
RateLimit-Reset: 3</code>
Pricing
API and MCP access is included on every paid plan from Starter. Calls spend the same credits as the app, read-only calls are free and failed jobs are refunded automatically.
Errors
Failures always look the same — an HTTP status plus a stable machine-readable code. MCP tools return the same information as an actionable isError result.
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | Some fields need attention. Please check the form and try again. |
BAD_REQUEST | That request didn't look right. Please check and try again. | |
INVALID_URL | That doesn't look like a valid video link. | |
UNSUPPORTED_SITE | We can't import videos from this site yet. Try YouTube, Facebook, TikTok, a direct https link to an MP4, MOV or WebM file, or upload the file. | |
SOURCE_UNAVAILABLE | We couldn't access this video. It may be private, age-restricted or removed. | |
SOURCE_LOGIN_REQUIRED | This video is only visible to people signed in to Facebook or Instagram (or it isn't public), so we can't download it. Ask the author to make it public, or download it yourself and upload the file instead. | |
SOURCE_NOT_A_VIDEO | This link opens a channel, playlist, profile, page or a photo post (a slideshow), not one video. Open the video itself and copy its link (Share, then Copy link), or upload the file instead. | |
SOURCE_TOO_LONG | This video is longer than your plan allows. Use a shorter one or upgrade. | |
UPLOAD_INVALID | This file looks damaged or isn't a real video, audio or image. | |
| 401 | INVALID_API_KEY | This API key is invalid or has been revoked. |
| 402 | INSUFFICIENT_CREDITS | Not enough credits. Top up or upgrade your plan to continue. |
| 403 | API_ACCESS_REQUIRES_PLAN | API and MCP access is available on every paid plan. |
ACCOUNT_BANNED | This account has been suspended. Contact support if you think this is a mistake. | |
PLAN_REQUIRED | This feature needs a paid plan. | |
PLAN_LIMIT | This goes beyond your plan's limits. Upgrade to unlock more. | |
SOURCE_TOO_LONG | This video is longer than your plan allows. Use a shorter one or upgrade. | |
INVALID_TOKEN | This link is invalid. Request a new one. | |
| 404 | NOT_FOUND | We couldn't find that. It may have been deleted or expired. |
UPLOAD_NOT_FOUND | The uploaded file is no longer available. Please upload it again. | |
| 409 | CONFLICT | This was changed somewhere else. Refresh and try again. |
JOB_IN_PROGRESS | This is still processing. Try again when it's done. | |
JOB_NOT_RETRYABLE | This job can't be retried. Create a new one instead. | |
PLAN_NOT_READY | The analysis isn't finished yet. | |
PLAN_EXPIRED | This clip plan has expired. Analyze the video again. | |
| 413 | PAYLOAD_TOO_LARGE | That file is too large for your plan. |
PLAN_LIMIT | This goes beyond your plan's limits. Upgrade to unlock more. | |
| 415 | UNSUPPORTED_MEDIA | That file type isn't supported. |
| 422 | CONTENT_BLOCKED | This content was blocked by the AI safety filter. Try a different prompt or source. |
NO_AUDIO | This video has no usable audio track. | |
| 429 | RATE_LIMITED | You're going a little fast. Wait a moment and try again. |
ACTIVE_JOBS_LIMIT | You have the maximum number of jobs running. Wait for one to finish or upgrade. | |
| 500 | INTERNAL_ERROR | Something broke on our side. We've been notified — please try again shortly. |
RENDER_FAILED | Rendering failed. Your credits were refunded — please try again. | |
| 502 | AI_FAILED | The AI couldn't process this video. Your credits were refunded — try again or use another source. |
TTS_FAILED | The voiceover couldn't be generated. Your credits were refunded. | |
PROVIDER_ERROR | An AI provider had a hiccup. Your credits were refunded — please try again. | |
DOWNLOAD_FAILED | We couldn't download the source video. Check the link or upload the file. | |
| 503 | SERVICE_UNAVAILABLE | This service is temporarily unavailable. Please try again in a few minutes. |
FEATURE_DISABLED | This feature is temporarily turned off. | |
MAINTENANCE | WowReveal is down for a quick upgrade. Please check back in a few minutes. | |
| 504 | TIMEOUT | This took too long and was stopped. Your credits were refunded. |
Why a job failed
A failed project, clip plan or generation carries an errorCode (and a short errorMessage); its credits are refunded automatically. When a project says retryable: true, POST /api/v1/projects/:id/retry (MCP: retry_project) runs it again at the current price — the last column says whether that can help.
| Code | What happened | Retry? |
|---|---|---|
DOWNLOAD_FAILED | We couldn't download the source video. Check the link or upload the file. | Later — the site may have been busy; try again later or upload the file. |
SOURCE_UNAVAILABLE | We couldn't access this video. It may be private, age-restricted or removed. | No — the video is private, deleted or region-locked — pick another source. |
SOURCE_LOGIN_REQUIRED | This video is only visible to people signed in to Facebook or Instagram (or it isn't public), so we can't download it. Ask the author to make it public, or download it yourself and upload the file instead. | No — a Facebook or Instagram video only signed-in people can see cannot be downloaded — ask the author to make it public, or upload the file. |
SOURCE_NOT_A_VIDEO | This link opens a channel, playlist, profile, page or a photo post (a slideshow), not one video. Open the video itself and copy its link (Share, then Copy link), or upload the file instead. | No — the link opens a channel, playlist, profile, page or a photo post, not one video — send the video's own link, or upload the file. |
SOURCE_TOO_LONG | This video is longer than your plan allows. Use a shorter one or upgrade. | No — use a shorter video or a plan that allows longer sources. |
INSUFFICIENT_CREDITS | Not enough credits. Top up or upgrade your plan to continue. | Later — after topping up. |
NO_AUDIO | This video has no usable audio track. | No — pick a video with sound, or a tool that does not need it. |
CONTENT_BLOCKED | This content was blocked by the AI safety filter. Try a different prompt or source. | No — change the source or the prompt. |
AI_FAILED | The AI couldn't process this video. Your credits were refunded — try again or use another source. | Yes — it usually works on the next try. |
TTS_FAILED | The voiceover couldn't be generated. Your credits were refunded. | Yes — it usually works on the next try. |
RENDER_FAILED | Rendering failed. Your credits were refunded — please try again. | Yes — it usually works on the next try. |
PROVIDER_ERROR | An AI provider had a hiccup. Your credits were refunded — please try again. | Later — an AI provider had a hiccup; wait a few minutes. |
TIMEOUT | This took too long and was stopped. Your credits were refunded. | Later — try again later, or with a shorter source. |
INTERRUPTED | Processing was interrupted. Your credits were refunded — please try again. | Yes — the job was cut off on our side (a restart or a stuck step); run it again. |
CANCELLED | You cancelled this video before it started. Your credits were refunded. | Yes — it was cancelled in the web app before it started, and its credits came back; run it again when you need it. |
INTERNAL_ERROR | Something broke on our side. We've been notified — please try again shortly. | Yes — try again; if it repeats, contact support. |
Give your agent a studio
Create a key, paste one line, and ask for your first batch of reels.