API documentation

Authentication

Create an account and verify your email. Create an API key in Account. Browser requests use the HttpOnly session cookie; server requests use Bearer authentication. Never put API keys in frontend code.

Connect an AI assistant with MCP

Use a client that supports Streamable HTTP and a custom Authorization header. Connect to the endpoint below with your account API key. OAuth sign-in is not supported.

URL: https://paddle-sandbox.superseedance.si/api/mcp
Transport: Streamable HTTP
Authorization: Bearer YOUR_STUDIO_API_KEY

list_models · quote_video · get_credit_balance · list_videos · get_video · create_video

Reading models, quotes, balance and tasks does not spend credits. Before creating a video, ask the assistant to show the prompt, settings and credit quote for your approval. Paid creation requires confirmCharge: true, the matching confirmedCredits and an idempotencyKey. Keep the same key and request when recovering an interrupted submission.

POST /api/quote

Send model, duration, resolution, aspectRatio, mode, nativeAudio and draft. The response contains credits, confirmed (studio price) and generationAvailable (current service availability). Prices are quoted in studio credits.

Seedance 2.5 supports 4–30 seconds, 480p/720p/1080p and audio on/off. Drafts require 480p. First-frame image mode follows the image ratio; text and single-image reference modes also offer 21:9 and automatic aspect. Five seconds at 16:9 costs 83 / 187 / 462 credits for 480p / 720p / 1080p. Automatic aspect uses a fixed quote based on the largest listed canvas in that resolution tier.

{
  "model": "seedance-2.5",
  "duration": 4,
  "resolution": "480p",
  "aspectRatio": "16:9",
  "nativeAudio": false,
  "draft": false,
  "mode": "text"
}

POST /api/generate

A verified account, an available generation service and sufficient credits are required. Reuse the same idempotencyKey only when retrying the exact same request. Returns HTTP 202 with {job}. For image and reference modes, upload a file to POST /api/assets first and send its assetId.

curl https://paddle-sandbox.superseedance.si/api/generate \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $STUDIO_API_KEY" \
  -d '{"model":"seedance-2.5","duration":4,"resolution":"480p","aspectRatio":"16:9","nativeAudio":false,"draft":false,"mode":"text","locale":"en","prompt":"A cup on a stone table, slow camera push-in, soft morning light.","idempotencyKey":"replace-with-a-new-uuid"}'

POST /api/analyze

Send six JPEG frame data URLs with locale and a unique idempotencyKey. Each frame must be at most 1 MB and 1280 × 720 pixels. Verified accounts are charged the quoted analysis credits; confirmed failures return those credits. Only sampled frames are analyzed, not audio or the full video.

Use GET /api/analyze?id=ID or ?idempotencyKey=KEY to recover results after a connection failure. Do not automatically repeat an uncertain submission.

Track, cancel and download

Poll GET /api/jobs/{id} every 5–10 seconds. Status progresses through queued → submitting → running → saving → succeeded. Confirmed failures and jobs cancelled while queued return reserved credits once. Only queued jobs can be cancelled using POST /api/jobs/{id}/cancel.

Download your saved result from GET /api/jobs/{id}/video?download=1. Files require owner authentication and support Range requests. An attention status means the task result is being checked; wait for it to be resolved before submitting the same work again.

Errors and limits

400 · Invalid input　401 · Sign in required　402 · Insufficient credits　403 · Verification or origin check failed　409 · State or idempotency conflict　429 · Rate limited　503 · Service unavailable

Up to three active jobs per account. Images: JPG/PNG/WebP, ≤10 MB, 300–6000 px per side and aspect ratio 0.4–2.5. Up to 100 assets / 100 MB per account.