Seedance Video API: Authentication, Generation, and Task Results
Integrate the current sdanceai video API: discover models, quote inputs, create a task, poll results and handle uncertain submissions.
Last updated: 2026-11-11
Service and authentication
Base URL: https://sdanceai.com. These are sdanceai endpoints, not ByteDance’s or Kling’s official API. API paths have no language prefix: use /api/... even when reading this page in Chinese.
Create a key after signing in at API key settings. Keep it in a server-side environment variable such as SDANCE_API_KEY. Send it as Authorization: Bearer YOUR_API_KEY. Generation and task queries support this credential. An invalid explicit key is rejected; it does not fall back to a browser session.
Do not embed the key in client JavaScript or mobile app binaries. This is a server-to-server example. The web upload endpoints use a signed-in browser session; they are not documented as Bearer-key uploads. For API image-to-video, supply licensed HTTP(S) media URLs accessible to the generation service.
Response envelope
Successful responses have code: 0, message: "ok" and data. Application errors normally use code: -1 and message; data may be absent. Rate-limit responses can instead use error and message, with a Retry-After header. Check both the HTTP status and code. Some validation or balance errors currently return HTTP 200 with code: -1.
{
"code": 0,
"message": "ok",
"data": { "id": "example-task-id", "taskStatus": "queued" }
}
The values above illustrate the shape, not an actual task. Do not treat HTTP 200 alone as proof that a video was generated.
Discover models: GET /api/ai/router01/models
Use ?type=video to list currently available video models. This catalog endpoint does not require the generation API key. A configured project can have a different model list from another deployment.
Each entry includes slug, name, type and params. Parameter declarations can include type, options, default, min, max, maxItems, maxLength and conditional requires. Use the returned slug exactly, including dots or hyphens. Do not infer it from an overview page URL.
curl --fail-with-body --silent --show-error 'https://sdanceai.com/api/ai/router01/models?type=video'
The fromMicros/fromUnit fields describe a starting unit price, not the credit total for your request. Use the quote endpoint with the actual inputs instead.
Quote a task: POST /api/ai/router01/quote
Send JSON with mediaType: "video", a catalog model slug, prompt and optional imageUrls, videoUrls, audioUrls and options. For duration, resolution and ratio, use compatible options.duration, options.resolution and options.aspect_ratio. Model-specific controls belong in options.params, using names declared in the catalog.
This endpoint does not require a generation key and is rate-limited. A quote does not create a generation task. Its result includes credits, input and pricing information for the prepared request. Reference media can affect cost; quote the same request you intend to submit. The server prices generation again before accepting it, so a quote is not a price lock.
The following request shape is illustrative. Replace the model slug and choose only settings offered by that model:
{
"mediaType": "video",
"model": "REPLACE_WITH_CATALOG_SLUG",
"prompt": "The uploaded bottle stays still while the camera slowly pushes in.",
"imageUrls": ["https://your-media-host.example/product.jpg"],
"options": {
"duration": 5,
"resolution": "720p",
"aspect_ratio": "9:16"
}
}
For a native-audio control such as generate_audio, first confirm that name and its allowed values in the selected model’s catalog. No single optional parameter works for every model.
Create a task: POST /api/ai/generate
Authenticate with the Bearer key and send the same generation inputs. Set mode to text-to-video or image-to-video as appropriate. For image-to-video, include a reachable reference in imageUrls. Use options.params for supported model-specific controls. Do not send your own price, cost, balance, provider route or upstream task ID; server-owned pricing and dispatch fields cannot be selected this way.
An accepted response includes id, dbId, taskId, taskStatus, costCredits, remainingBalance and taskInfo. Save data.id immediately as the durable site task identifier. Acceptance usually starts at queued; it is not the finished video. A successful submission creates a credit-consuming task.
This API does not advertise an idempotency-key or caller-supplied callback-URL contract. If the connection fails before an ID returns, do not blindly resend the POST. Check the workspace history or contact support to reconcile the uncertain submission.
Poll a task: GET /api/ai/task
Send the same Bearer key and ?taskId=YOUR_SAVED_SITE_TASK_ID. Keep using the saved site ID even if an upstream taskId later appears. You can query only tasks owned by the authenticated account.
States are queued, pending, processing, success, failed and canceled. The first three are not terminal. On success, video links are available in data.taskInfo.videos[].videoUrl when present. On failure or cancellation, the public response includes a sanitized taskInfo.userErrorCode, rather than the provider’s full error payload.
Batch lookup uses ?taskIds=ID1,ID2 and returns data.tasks. It accepts at most 10 unique IDs per request. Missing or inaccessible IDs are not a way to discover another account’s jobs. Bearer-key task cancellation/deletion is not part of this documented contract; the current DELETE handler uses a browser session.
Run the Node.js example
The example below requires Node.js 20 or later. It defaults to quote-only mode, uses current model defaults unless you provide SDANCE_OPTIONS, and never automatically repeats the generation POST. Download the runnable example and set the API key in your server environment.
# Replace the value with a slug returned by the catalog.
SDANCE_MODEL='YOUR_CATALOG_SLUG' node video-api.mjs
# After reviewing the quote, this submits one task and polls it.
SDANCE_MODEL='YOUR_CATALOG_SLUG' SDANCE_SUBMIT=1 node video-api.mjs
# Resume querying an existing task without creating another.
SDANCE_TASK_ID='YOUR_SAVED_SITE_TASK_ID' node video-api.mjs
Optional environment values are SDANCE_BASE_URL, SDANCE_PROMPT, SDANCE_IMAGE_URL and JSON SDANCE_OPTIONS. An image URL changes the example to image-to-video. Keep any signed URL valid long enough for processing. On a polling error, preserve the task ID and resume querying rather than rerunning creation.
// Node.js 20+. Run on your server. Quotes only unless SDANCE_SUBMIT=1.
const base = (process.env.SDANCE_BASE_URL || 'https://sdanceai.com').replace(
/\/+$/,
''
);
const key = process.env.SDANCE_API_KEY;
if (!key) throw new Error('Set SDANCE_API_KEY in your server environment.');
async function api(path, init = {}) {
const response = await fetch(`${base}${path}`, {
...init,
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${key}`,
},
});
const body = await response.json();
if (!response.ok || body.code !== 0) {
throw new Error(
`HTTP ${response.status}: ${body.message || 'Request failed'}`
);
}
return body.data;
}
let taskId = process.env.SDANCE_TASK_ID;
if (!taskId) {
const model = process.env.SDANCE_MODEL;
if (!model)
throw new Error('Set SDANCE_MODEL to a slug from the current catalog.');
const catalog = await api('/api/ai/router01/models?type=video');
if (!catalog.some((item) => item.slug === model)) {
throw new Error('The selected model is not in the current video catalog.');
}
const request = {
mediaType: 'video',
model,
mode: process.env.SDANCE_IMAGE_URL ? 'image-to-video' : 'text-to-video',
prompt:
process.env.SDANCE_PROMPT ||
'A ceramic cup stays still while the camera slowly pushes in.',
imageUrls: process.env.SDANCE_IMAGE_URL
? [process.env.SDANCE_IMAGE_URL]
: [],
options: JSON.parse(process.env.SDANCE_OPTIONS || '{}'),
};
const quote = await api('/api/ai/router01/quote', {
method: 'POST',
body: JSON.stringify(request),
});
console.log('Estimated credits:', quote.credits);
if (process.env.SDANCE_SUBMIT !== '1') {
console.log('Quote only. Set SDANCE_SUBMIT=1 to submit one billable task.');
process.exit(0);
}
let created;
try {
created = await api('/api/ai/generate', {
method: 'POST',
body: JSON.stringify(request),
});
} catch (error) {
throw new Error(
'Submission did not return a confirmed task ID. Check history before submitting again.',
{ cause: error }
);
}
taskId = created.id;
if (!taskId)
throw new Error('Missing task ID. Check history before submitting again.');
console.log('Save this task ID to resume polling:', taskId);
}
for (let attempt = 0; attempt < 60; attempt += 1) {
const task = await api(`/api/ai/task?taskId=${encodeURIComponent(taskId)}`);
console.log('Task status:', task.taskStatus);
if (task.taskStatus === 'success') {
const urls = (task.taskInfo?.videos || [])
.map((video) => video.videoUrl)
.filter(Boolean);
if (!urls.length)
throw new Error(
'Task succeeded without a video URL. Contact support with the saved task ID.'
);
console.log('Video URLs:', urls);
process.exit(0);
}
if (['failed', 'canceled'].includes(task.taskStatus)) {
throw new Error(
`Task ended: ${task.taskInfo?.userErrorCode || task.taskStatus}`
);
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log(
'Polling window ended. The task may still be running. Resume with SDANCE_TASK_ID; do not create it again.'
);
Errors, waiting and credit adjustments
A 401 means authentication failed. Quote requests can return 400 for invalid input, 413 for an oversized request, 429 when limited, and 502 when a quote is unavailable. Other endpoints do not promise this same HTTP mapping, so always inspect the envelope. Common generation messages include an unsupported model, unavailable provider or insufficient credits.
Task error codes include reference_media_invalid, reference_media_duration_invalid, too_many_images, too_many_videos, too_many_audios, prompt_too_long, service_busy, content_safety_rejected, copyright_restricted and generation_failed. See the troubleshooting guide for next steps.
Back off when limited, poll conservatively, and distinguish a local timeout from a terminal task failure. The example’s polling window is a client limit, not a server completion guarantee. Credit adjustments follow the final task state and Terms of Service. A completed video you dislike is not automatically a failed task.
Related guides and support
Use the image-to-video workspace, product-ad tutorial and pricing page to plan your workflow. Send endpoint, HTTP status, business code, model slug, task ID and approximate request time to support@sdanceai.com. Never send your key, full authorization header or confidential references.