Seedance 2.5.
Inside your product.

Your first video, in a few requests.

Save your key as SEADANCE_API_KEY on your server. Set SEADANCE_REQUEST_KEY to a unique value for this video (for example, uuidgen), and keep that value for retries. Make sure your account has enough credits. This example reserves 350 credits for a 5-second 720p video. Copy the returned id to query its status.

export SEADANCE_API_KEY="sd_live_your_key"
# Keep this value for retries; choose a new value for a new video.
export SEADANCE_REQUEST_KEY="${SEADANCE_REQUEST_KEY:-$(uuidgen)}"

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos" \
  -H "Authorization: Bearer $SEADANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SEADANCE_REQUEST_KEY" \
  --data '{
  "model": "seedance-2.5",
  "mode": "text-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

This documentation never runs a generation automatically. Sending a create request uses your credits.

Authenticate from your server.

Every API call uses Authorization: Bearer sd_live_…. Keep keys out of browsers, mobile apps, public repositories and client-side bundles. The full key is shown once; you can revoke it in the API dashboard.

Default key scopes: videos:write for uploads and generation; videos:read for models and task status; account:read for credits. Account access and limits apply across all keys.

Create a video task.

Use Content-Type: application/json and a unique Idempotency-Key for each intended generation. The server may take time to accept the upstream task. If your connection times out, repeat the same body with the same key. HTTP 202 means accepted, not finished. Idempotency-Key accepts 1–128 printable ASCII characters without spaces.

Seedance 2.5 supports text, first/last frames, multimodal references, video editing and extension through these fields. GET /models is the current source of truth for available capabilities and pricing.

{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "firstFrameUrl": "YOUR_UPLOADED_PUBLIC_OBJECT_URL"
}

{
  "model": "seedance-2.5",
  "mode": "reference-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "referenceImageUrls": [
    "YOUR_UPLOADED_IMAGE_URL"
  ],
  "referenceVideoUrls": [
    "YOUR_UPLOADED_VIDEO_URL"
  ]
}

Upload once. Reference by URL.

POST /uploads with fileName, contentType, size (bytes) and kind (image, video or audio). PUT the raw file bytes to uploadUrl using requiredHeaders before expiresAt. After the upload succeeds, use publicObjectUrl in the generation request. References must belong to the same account; arbitrary external URLs and base64 inputs are not accepted.

// Node.js 20+ · upload once, then use publicObjectUrl
import { readFile } from "node:fs/promises";

const bytes = await readFile("./first-frame.jpg");
const signed = await fetch("https://seedance3ai.dev/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEADANCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fileName: "first-frame.jpg", contentType: "image/jpeg",
    size: bytes.length, kind: "image",
  }),
});
const upload = await signed.json();
if (!signed.ok) throw new Error(JSON.stringify(upload));
const stored = await fetch(upload.uploadUrl, {
  method: "PUT", headers: upload.requiredHeaders, body: bytes,
});
if (!stored.ok) throw new Error("Upload failed");
console.log(upload.publicObjectUrl);
// Use this URL as firstFrameUrl in an image-to-video request.

The declared size and content type must match the uploaded file. Upload URLs expire; request another if needed. Media duration, dimensions and format are validated before generation.

Follow the task to completion.

GET /videos/:id returns the current task. Poll every 5–10 seconds, stop at succeeded or failed, and back off when Retry-After is present. Queries are restricted to API tasks owned by your account. The current integration uses polling.

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

{
  "id": "a1b2c3d4-1234-4567-8901-abcdef123456",
  "status": "succeeded",
  "credits_reserved": 350,
  "created_at": "2026-10-27T00:00:00.000Z",
  "output": {
    "url": "https://your-result-host.example/video.mp4"
  },
  "error": null,
  "refund_status": "not_applicable"
}

output is null until a video is available. A failed task includes an error; check refund_status for the credit refund state. Download successful results promptly. Deleting a video does not reset its request: replaying that Idempotency-Key returns 410 video_deleted and cannot create it again.

Know the credit cost before you build.

API generation uses the same account credits and Seedance 2.5 rates as the website. Credits are reserved when a request is accepted. Failed generations return those credits to your one-time balance. A validation failure before task creation does not create a billable video.

Cost = output duration × output rate, plus any reference-video duration × reference rate. Reference video time is measured on the server; the total is rounded down to whole seconds for billing. Native audio is included. For example, 5 seconds at 720p costs 350 credits, or 600 credits with a 5-second reference video.

curl --fail-with-body "https://seedance3ai.dev/api/v1/models" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

curl --fail-with-body "https://seedance3ai.dev/api/v1/credits" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

See the API dashboard for available credits, request history and account limits. Add credits through the website pricing page using the same account; there is no separate API balance or API top-up endpoint. An active subscription is not required when you have enough available credits. Subscription expiration and one-time credit rules are the same as website usage.

Adding credits does not raise API rate, concurrency or daily limits, or re-enable a disabled account. The daily limit counts all reserved credits, including refunded failures, and resets at 00:00 UTC. Contact support if your application needs higher limits.

Retry safely. Avoid duplicate charges.

Use one Idempotency-Key per intended video and preserve it with the exact request body until the result is known. New keys represent new generations. An error response contains error.code, error.message and request_id; include the request ID when contacting support.