Get started

Quickstart

Base URL: https://clipwave.ai Versioning: /api/v1/ Auth: Authorization: Bearer cw_live_<your_key> Format: JSON request and response bodies (UTF-8) Rate limit: 60 requests/minute per API key (in-memory; Redis-backed multi-instance coming)

The Clipwave public API exposes Seedance 2.0 video generation and Nano Banana 2 image generation as authenticated REST endpoints. It's the same engine that powers the Clipwave web app and Media Forge, billed against the same credit balance.

Quick start

# 1. Get an API key
#    Sign in → Dashboard → API Keys → Create

# 2. List available models (and their credit costs)
curl https://clipwave.ai/api/v1/models \
  -H "Authorization: Bearer cw_live_..."

# 3. Submit a Seedance 2.0 video generation
curl https://clipwave.ai/api/v1/video/seedance-2/generate \
  -H "Authorization: Bearer cw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cinematic dolly zoom on a luxury watch dropping into frame",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'
# → 202 { "job_id": "abc123", "status": "processing", "credits_consumed": 75, ... }

# 4. Poll for the result
curl https://clipwave.ai/api/v1/jobs/abc123 \
  -H "Authorization: Bearer cw_live_..."
# → 200 { "status": "completed", "result": { "video": "https://..." } }

Documents

Authentication — API keys, Bearer header, scopes, rate limits
Endpoints — full reference for /api/v1/*
Errors — error codes and recovery
Examples — curl
Examples — TypeScript
Examples — Python

Models exposed (Phase 1)

Model	Type	Endpoint	Credits
Seedance 2.0	video	`POST /api/v1/video/seedance-2/generate`	227cr/s (audio included) — 5s = 1,135cr
Seedance 2.0 Fast	video (text-to-video only)	`POST /api/v1/video/seedance-2/generate` (`fast: true`)	181cr/s (audio included) — 5s = 905cr
Nano Banana 2	image	`POST /api/v1/image/nano-banana/generate`	50cr/image

More models (Kling V3, Veo 3.1, Sora 2) shipping in Phase 2.

AI Video Editor (Phase 2)

Beyond raw generation, the API also exposes the full chat-driven multi-scene Video Editor: create a project, drive an autonomous agent in a loop, then export the finished mp4. See the endpoints reference for the 5 endpoints (/api/v1/media-studio/projects/...) and the matching video_editor_* MCP tools.

# Sketch — full curl example in examples/curl.md
curl -X POST https://clipwave.ai/api/v1/media-studio/projects \
  -H "Authorization: Bearer cw_live_..." \
  -d '{"name":"Cozy candle UGC","aspect_ratio":"9:16"}'

# Drive the agent (one step per call; loop until done)
curl -X POST https://clipwave.ai/api/v1/media-studio/projects/vp_abc/instruct \
  -d '{"instruction":"Plan a 3-scene UGC ad for candles."}'

# Export the final mp4
curl -X POST https://clipwave.ai/api/v1/media-studio/projects/vp_abc/export

Pricing model

API calls bill against your existing Clipwave credit balance. No markup vs. UI usage — a 5s Seedance 2.0 video costs the same 1,135 credits whether generated through Media Forge in the web app or through POST /api/v1/video/seedance-2/generate.

If a generation fails after credit deduction (provider error, timeout, cancellation), credits are automatically refunded to your balance.

MCP server

Calling Clipwave from Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible client? The hosted MCP server is live — nothing to install. Point your client at the endpoint and authenticate with the same cw_live_ key (or OAuth):

claude mcp add clipwave \
  --transport http https://clipwave.io/api/mcp \
  --header "Authorization: Bearer cw_live_…"

17 tools: model catalog (list_models), image/video generation (media_forge_generate, job_status), and the full Media Studio editor (video_editor_* — create a project, instruct it scene by scene, export one MP4). The endpoint self-briefs on connect via initialize.instructions, so agents learn the workflow automatically. Full setup for every client, the tool catalog and an example run: clipwave.io/mcp.

A local stdio variant (@clipwave/mcp, source in mcp-server/) exists for stdio-only setups; npm publish is pending — the hosted endpoint is the recommended path.

Status

✅ Bearer auth
✅ Rate limiting (60 req/min in-memory)
✅ Credit accounting + automatic refund on failure
✅ Audit log (api_requests table)
✅ Seedance 2.0 (image-to-video, text-to-video, Fast variant)
✅ Nano Banana 2 (text-to-image, edit)
✅ Job lifecycle (submit, status, cancel)
✅ AI Video Editor (create / instruct / get state / export) — multi-video projects, shared library + context
✅ Hosted MCP server (/api/mcp, 17 tools, streamable HTTP, Bearer + OAuth) — clipwave.io/mcp
✅ Webhooks for job completion (per-key URL + HMAC-SHA256 signature, 3 retries)
🟡 Multi-instance rate limiter (Redis) — currently in-memory per process
🟡 Additional models (Kling V3, Veo 3.1, Sora 2)
🟡 OpenAPI / Swagger spec