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/..."
  }
}

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.