API Documentation

Start a new video generation job. The AI analyzes your prompt, plans scenes, generates visuals, voiceover, and music, then composes a final video. Costs credits based on complexity.

202 Job accepted (Retry-After: 10)

{
  "job_id": "wf_abc123def456789",
  "status": "running",
  "message": "Video generation started. Poll GET /api/v1/videos/{job_id} for status, or stream GET /api/v1/videos/{job_id}/events for real-time progress.",
  "webhook_url": "https://your-server.com/webhook"
}

job_id is prefixed with wf_ followed by a 32-character hex string. Keep it; you'll need it for all subsequent calls.

400 Invalid JSON, missing/short prompt, unknown aspect_ratio, or invalid webhook_url

402 Insufficient credits, CREDITS_OWED from a prior settlement upcharge, or NO_BILLING_ORG (the key's account has no organization yet — sign in to the dashboard once to initialize it). Response includes code and details.

429 Rate limit or monthly quota exceeded (Retry-After on rate limit only)

503 Inngest dispatch unavailable (Retry-After: 60)

Check the status and progress of a video generation job. Returns an ETag header for conditional requests, and Retry-After while the job is still running (3s when progress_pct > 70, 8s otherwise).

200 Job status

{
  "job_id": "wf_abc123def456789",
  "status": "running",
  "phase": "generate_video_clip",
  "progress_pct": 65,
  "composition_id": "comp_xyz"
}

composition_id, output, and error are only present when populated. phase is the name of the most recently-started tool or phase event (e.g. generate_image, compose_scenes).

Stream real-time progress as Server-Sent Events. The stream emits one event per workflow event (with the workflow's event_type as the SSE event: field) plus periodic : keepalive comments, and terminates with a final complete, errored, or timeout event. Maximum stream duration is 30 minutes; reconnect with ?last_event_id= to resume.

SSE text/event-stream

id: 12
event: phase
data: {"id":12,"event_type":"phase","message":"Generating media","created_at":"2026-04-01T12:01:00Z","progress":35}

id: 13
event: tool_start
data: {"id":13,"event_type":"tool_start","tool_name":"generate_image","message":"generate_image","detail":{"sceneId":"scene-3"},"progress":40}

id: 14
event: tool_complete
data: {"id":14,"event_type":"tool_complete","tool_name":"generate_image","detail":{"sceneId":"scene-3","assetType":"image"},"progress":52}

: keepalive

event: complete
data: {"status":"complete","composition_id":"comp_xyz","output":{"compositionId":"comp_xyz"}}

Retrieve the full video composition JSON. :id accepts either the wf_* job ID returned by POST /api/v1/videos or a composition_id (UUID) from a previous status response. Contains scene definitions, style spec, audio tracks, and R2 asset keys (resolve via POST /assets/sign).

200 Composition data

{
  "composition_id": "comp_xyz",
  "composition": {
    "id": "comp_xyz",
    "title": "...",
    "aspectRatio": "16:9",
    "totalDurationFrames": 900,
    "fps": 30,
    "scenes": [...],
    "style": {
      "colorPalette": {...},
      "typography": {...},
      "motionLanguage": "cinematic",
      "visualMedium": "photorealistic"
    },
    "audio": {
      "voiceover": {...},
      "music": {...}
    }
  }
}

Generate signed public URLs for composition asset keys. Use this to resolve asset references from the composition JSON into downloadable URLs. Up to 50 keys per request. For each image key, the response also includes _400w.jpg and _800w.jpg variants when available; for each video key, the _web.mp4 and _preview.mp4 variants. Keys that don't exist in storage are silently omitted from the response (no 404).

{
  "keys": ["assets/scene-1/image.png", "assets/scene-2/video.mp4"]
}

200

{
  "urls": {
    "assets/scene-1/image.png": "https://api.wavemakr.com/assets/...",
    "assets/scene-1/image_400w.jpg": "https://api.wavemakr.com/assets/...",
    "assets/scene-1/image_800w.jpg": "https://api.wavemakr.com/assets/...",
    "assets/scene-2/video.mp4": "https://api.wavemakr.com/assets/...",
    "assets/scene-2/video_web.mp4": "https://api.wavemakr.com/assets/...",
    "assets/scene-2/video_preview.mp4": "https://api.wavemakr.com/assets/..."
  }
}

Dispatch one static ad generation (or an N-card carousel). Charges a flat 8 credits per ad (carousel: 8 × cards). Async: poll the status URL, or pass webhook_url for a signed tool_run.completed push.

curl -X POST https://api.wavemakr.com/api/v1/static-ads \
  -H "Authorization: Bearer mcp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Bold launch ad for our espresso subscription",
    "site_url": "https://example-coffee.com",
    "platform": "meta",
    "format": "square"
  }'

202 Run accepted

{
  "run_id": "wtr_abc123def456",
  "credits_charged": 8,
  "status": "pending",
  "status_url": "/api/v1/static-ads/wtr_abc123def456"
}

400 Invalid JSON or input (neither prompt nor site_url)

402 Insufficient credits

503 Dispatch infrastructure temporarily unreachable

Poll a static-ad run. While in flight the response is { run_id, status } (pending / running). A failed run returns 502 with status: "error" and an error reason. On completion each delivered variant carries the final image URL, exact pixel size, ad copy, and its QC report. Single-ad runs also surface the one variant as variant; carousels return all cards in variants.

{
  "run_id": "wtr_abc123def456",
  "status": "complete",
  "variant": {
    "id": "adv_123",
    "url": "https://api.wavemakr.com/assets/...",
    "width": 1080,
    "height": 1080,
    "aspect_ratio": "1:1",
    "format": "square",
    "platforms": ["meta"],
    "headline": "Espresso, Delivered.",
    "cta": "Start Your Trial",
    "qc": { "status": "passed", "issues": [] }
  },
  "variants": [ ... ]
}

Free catalog of ad formats and platform packs: each format's exact delivery pixels, ratio, and the platforms it serves, plus each platform's recommended format pack. Use a format id (or a platform) in POST /api/v1/static-ads.

Free catalog of ad visual styles (dark authority, testimonial spotlight, minimalist hero, meme format, ...): id, name, use-case guidance, and platform compatibility. Pass a style id as style_id to pin the look; omit for AI selection.

Create a workspace once (POST /api/v1/workspaces), then dispatch this tool. Returns a run_id + the dynamically-computed credits_charged; poll GET /api/v1/tool-runs/:run_id for result.output.download_url.

202 { "run_id": "wtr_…", "status": "pending", "credits_charged": N }

402 Insufficient credits

413 Source too long (>2 h) / too large (>5 GB)

422 Undecodable / undeterminable-duration media

Retrieve usage statistics and remaining monthly quota for the calling API key. Quotas are evaluated server-side on every call to POST /api/v1/videos.

200

{
  "period_days": 30,
  "total_requests": 142,
  "total_cost_cents": 8500,
  "by_action": {
    "video_generation": { "count": 42, "cost_cents": 8500 }
  },
  "quota": {
    "quota_cents": null,
    "used_cents": 8500,
    "remaining_cents": null,
    "unlimited": true
  }
}

All fields use snake_case. Billing is credit-based and org-scoped (enforced with 402 on POST /api/v1/videos), so the per-key dollar quota is reported as unlimited: quota.unlimited is true and quota.quota_cents / quota.remaining_cents are null.