API Documentation

Authentication

All API requests require an API key passed as a Bearer token. Create and manage keys from your dashboard API Keys page.

Authorization: Bearer mcp_your_api_key_here

Quick Start

Generate a video in three steps: create a job, poll for status, then retrieve the result.

curl -X POST https://wavemaker.adwave.com/api/v1/videos \
  -H "Authorization: Bearer mcp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 30-second ad for a coffee shop in Brooklyn",
    "aspect_ratio": "16:9",
    "platform": "youtube"
  }'

curl https://wavemaker.adwave.com/api/v1/videos/job_abc123 \
  -H "Authorization: Bearer mcp_your_api_key"

curl https://wavemaker.adwave.com/api/v1/videos/job_abc123/composition \
  -H "Authorization: Bearer mcp_your_api_key"

Or use webhooks to get notified automatically when the video is ready.

Videos

{
  "job_id": "job_abc123",
  "status": "queued",
  "message": "Video generation started",
  "webhook_url": "https://your-server.com/webhook"
}

{
  "job_id": "job_abc123",
  "status": "running",
  "phase": "generating_media",
  "progress_pct": 65,
  "composition_id": null,
  "output": null,
  "error": null
}

event: progress
data: {"phase":"generating_media","progress_pct":45,"message":"Generating scene 3 of 5"}

event: progress
data: {"phase":"composing","progress_pct":85,"message":"Composing final video"}

event: complete
data: {"composition_id":"comp_xyz","output":{"url":"https://..."}}

{
  "composition_id": "comp_xyz",
  "composition": {
    "scenes": [...],
    "style": {
      "colorPalette": {...},
      "typography": {...},
      "motionLanguage": "cinematic"
    },
    "audio": {
      "voiceover": {...},
      "music": {...}
    },
    "metadata": {
      "aspectRatio": "16:9",
      "totalDurationFrames": 900
    }
  }
}

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

{
  "urls": {
    "assets/scene-1/image.png": "https://...",
    "assets/scene-2/video.mp4": "https://..."
  }
}

Webhooks

Instead of polling, receive an HTTPS POST to your server when a video generation job completes or fails. Pass webhook_url (and optionally webhook_secret) when creating a job.

{
  "event": "video.completed",
  "job_id": "job_abc123",
  "status": "completed",
  "composition_id": "comp_xyz",
  "output": {
    "url": "https://..."
  },
  "created_at": "2026-04-01T12:00:00Z",
  "completed_at": "2026-04-01T12:03:45Z"
}

{
  "event": "video.failed",
  "job_id": "job_abc123",
  "status": "errored",
  "error": "Generation failed: insufficient scene content",
  "created_at": "2026-04-01T12:00:00Z",
  "completed_at": "2026-04-01T12:01:12Z"
}

Usage

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

MCP Integration

Wavemaker implements the Model Context Protocol, so you can use it as a tool in Cursor, Claude Desktop, Windsurf, or any MCP-compatible client. The MCP endpoint uses the same API key authentication.

Add this to your .cursor/mcp.json in any project:

{
  "mcpServers": {
    "wavemaker": {
      "url": "https://wavemaker.adwave.com/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your_api_key"
      }
    }
  }
}

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "wavemaker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://wavemaker.adwave.com/mcp",
        "--header",
        "Authorization:${MCP_API_KEY}"
      ],
      "env": {
        "MCP_API_KEY": "Bearer mcp_your_api_key"
      }
    }
  }
}

You can also call the MCP endpoint directly:

curl -X POST https://wavemaker.adwave.com/mcp \
  -H "Authorization: Bearer mcp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with an error field describing the issue.

{
  "error": "Monthly quota exceeded",
  "retryAfterSeconds": 3600
}