API Documentation

Body: feedFileId, template (baseSlug static-ads | ads-catalog-video, prompt with {{title}} slots, optional formatIds / aspectRatio / styleId), optional rowIds / sessionId. Feed validation + image ingest run before reserve. Over 24 variants → 422 campaign_variant_cap_exceeded. MCP twin: engage_campaign.

Org campaign list (dashboard). Not an MCP tool — agents use get_campaign after engage.

Run-group projection plus SKU-keyed variant statuses/outputs. MCP: get_campaign. Files via GET /files/{id}.

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.wavemaker.io/assets/...",
    "assets/scene-1/image_400w.jpg": "https://api.wavemaker.io/assets/...",
    "assets/scene-1/image_800w.jpg": "https://api.wavemaker.io/assets/...",
    "assets/scene-2/video.mp4": "https://api.wavemaker.io/assets/...",
    "assets/scene-2/video_web.mp4": "https://api.wavemaker.io/assets/...",
    "assets/scene-2/video_preview.mp4": "https://api.wavemaker.io/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.wavemaker.io/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.wavemaker.io/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.

Deprecated — superseded by GET /api/v1/image-styles below (the response carries a Link: rel="successor-version" header). Free catalog of ad-capable visual styles only (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. Both endpoints project off the same catalog, so a caller mid-migration never sees drift between the two responses.

Free catalog of every Image Style (~110 seeded looks) — the successor to /api/v1/ad-styles. Each row is { id, name, category, kind, applicable_purposes, use_case_guidance, platform_compatibility }. applicable_purposes governs where a style_id is valid: an "ad"-capable style (kind: "ad_layout") pins style_id on POST /api/v1/static-ads when purpose is the default "ad"; a "plain"-capable style (kind: "look") pins style_id when purpose: "image" (no ad copy). A style may declare both purposes. The MCP equivalent is the list_image_styles tool.

Edit a delivered image (the site's iteration loop). Body: action (edit / regenerate / change_style / adapt_ratio), instruction (required for edit), style_id (for change_style — from GET /api/v1/image-styles), target_format_id (for adapt_ratio — from /ad-formats), optional webhooks. Credits: edit 3; others 5. Versions are append-only. MCP: edit_static_ad. Returns 202 with run_id, credits_charged, and status_url.

Set-level edit (action defaults to set_edit): apply one instruction across every non-approved image of the set (≤12 images; 5 credits × image). Returns 202 with run_id, credits_charged, and status_url.

Dispatch one pack. Idempotency-Key header required (unique per org) — identical body replay returns the original run (200, Idempotent-Replayed); a different body under a reused key 409s. Body: kind, brief (required), hook_count (hook_variant, 3–8, default 5), still_count / style_id (photo_set), webhook_url. Whole-pack credits held up front and settled per-master. photo_set 403s NSFW-entitled callers toward generate_static_ad.

curl -X POST https://api.wavemaker.io/api/v1/creative-packs \
  -H "Authorization: Bearer mcp_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pack-order-8812" \
  -d '{
    "kind": "multi_ar_pmax",
    "brief": "Performance Max pack for https://acme.com — free shipping CTA"
  }'

{
  "pack_run": {
    "pack_run_id": "cpr_…",
    "kind": "multi_ar_pmax",
    "status": "pending",
    "credits_held": 120,
    "master_count": 4,
    "status_url": "/api/v1/creative-packs/cpr_…"
  }
}

Free catalog of the 4 pack kinds with their masters (role, aspect ratio, treatment id, duration / still count).

Poll. Overall status (pending / running / succeeded / partial / failed / cancelled; credits_held / credits_settled; zip_url when a photo_set ZIP is built; each master's own status + result_urls.

Cancel an in-flight pack. Cancels child kernel runs, refunds unused hold (completed masters keep their reserved share), marks the pack cancelled. No-op once terminal.

Dispatch one audio set. Credits are reserved from purpose × duration × variants (see credits_charged). Async: poll the status URL, or pass webhook_url for a signed tool_run.completed push.

curl -X POST https://api.wavemaker.io/api/v1/audio \
  -H "Authorization: Bearer mcp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "30-second radio ad for https://acme.com — free shipping CTA",
    "purpose": "spot",
    "duration_ids": ["spot_15", "spot_30"],
    "variants_per_duration": 2
  }'

{
  "run_id": "wtr_audio123",
  "credits_charged": 39,
  "status": "pending",
  "status_url": "/api/v1/audio/wtr_audio123"
}

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

Submit a run. Get an itemized quote first with POST /api/v1/workflows/:id/estimate (per-node credits, BYOK fees, and any creator premium). Poll GET /api/v1/kernel-runs/:run_id for per-node progress, costs, and artifact ids.

Send an Idempotency-Key header (≤255 chars, permanent per organization) to make submits retry-safe: a replay returns the original run with idempotent_replayed: true and the Idempotent-Replayed: true header — exactly one credit hold no matter how many times you retry.

202 { "run_id": "…", "status": "queued", "credits_held": N }

POST /api/v1/kernel-runs/:id/cancel — cancel; keeps actual node spend, refunds the rest

POST /api/v1/kernel-runs/:id/approval — decide a pending approval gate

GET /api/v1/kernel-artifacts/:id — artifact metadata + download URL

POST /api/v1/provider-credentials — BYOK vault (write-only; 20% platform fee, min 1 credit, on BYOK steps)

GET /api/v1/hub/workflows?q=… — search the public Hub catalog

GET /api/v1/w/:slug — run a workflow as a product by its Hub slug: detail + typed inputs as JSON Schema (Draft 2020-12), then POST /api/v1/w/:slug/runs or /estimate (same gates and billing as the id routes)

POST /api/v1/workflows/compile — stateless compile: validate a raw WorkflowSpec from CI or an editor without saving anything

GET /api/v1/kernel-runs?ids=a,b,c — batch-read up to 20 runs in one call

GET /api/v1/openapi.json — OpenAPI 3.1 document for the whole workflow-platform REST surface (unauthenticated, ETag-cached). Feed it to a codegen tool or hand it to your agent.

GET /api/v1/workflow-spec-schema — the WorkflowSpec JSON Schema (Draft 2020-12), for validating specs before you submit them.