Seedance 视频 API:鉴权、生成与任务结果
接入 sdanceai 当前视频 API:查询模型、获取报价、创建任务、查询结果,并正确处理不确定的提交。
最近更新: 2026-11-11
服务地址与鉴权
基础地址为 https://sdanceai.com。这些是 sdanceai 的接口,并非字节跳动或 Kling 的官方 API。接口路径不带语言前缀,阅读中文文档时也使用 /api/...。
登录后在API Key 设置创建密钥,保存在服务端环境变量,例如 SDANCE_API_KEY。请求头使用 Authorization: Bearer YOUR_API_KEY。生成与任务查询支持这种凭据;显式提供无效密钥时不会回退到浏览器登录态。
不要将密钥嵌入前端 JavaScript 或移动端安装包。这里的示例用于服务端调用。网页上传接口使用浏览器登录会话,不是本文承诺的 Bearer Key 上传接口。API 图生视频请提供生成服务可访问、且具备处理授权的 HTTP(S) 素材 URL。
响应格式
成功响应包含 code: 0、message: "ok" 和 data。应用错误通常使用 code: -1 与 message,可能没有 data。限流响应也可能使用 error、message,并提供 Retry-After 响应头。同时检查 HTTP 状态与业务 code,部分参数或余额错误目前会返回 HTTP 200 和 code: -1。
{
"code": 0,
"message": "ok",
"data": { "id": "example-task-id", "taskStatus": "queued" }
}
上面只说明格式,不是真实任务。HTTP 200 本身并不证明视频已经生成。
查询模型:GET /api/ai/router01/models
使用 ?type=video 获取当前可用的视频模型。目录接口不要求生成密钥;配置不同项目的站点,可用模型可能不同。
每条记录包含 slug、name、type 与 params。参数声明可能包含 type、options、default、min、max、maxItems、maxLength 和条件 requires。请原样使用返回的 slug,包括点号或连字符,不要根据介绍页 URL 猜测。
curl --fail-with-body --silent --show-error 'https://sdanceai.com/api/ai/router01/models?type=video'
fromMicros/fromUnit 是起始单位价格,不是当前任务的总积分。请将真实输入提交给报价接口。
获取报价:POST /api/ai/router01/quote
提交 JSON,包含 mediaType: "video"、目录中的 model、prompt,以及可选的 imageUrls、videoUrls、audioUrls 和 options。时长、分辨率、比例使用兼容的 options.duration、options.resolution、options.aspect_ratio。模型专用参数放在 options.params,名称以目录为准。
此接口不要求生成密钥,但有限流。报价不会创建生成任务。返回结果包含 credits、准备后的 input 及价格信息。参考素材可能影响费用,请对计划提交的相同请求报价。生成提交时服务端会重新计价,报价不是锁价承诺。
下面仅说明请求结构,模型 slug 和可选参数需替换为目录实际支持的值:
{
"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"
}
}
使用 generate_audio 等原生音频参数前,先确认当前目录是否声明该名称和取值。没有适用于所有模型的统一可选参数。
创建任务:POST /api/ai/generate
携带 Bearer Key,提交相同的生成输入,并按实际工作流将 mode 设置为 text-to-video 或 image-to-video。图生视频使用 imageUrls 提供可读取参考图,模型专用设置放入 options.params。不要自行提供价格、扣费、余额、服务商线路或上游任务 ID,服务端控制的计价和派发字段不能通过这种方式指定。
接受后的响应包含 id、dbId、taskId、taskStatus、costCredits、remainingBalance 和 taskInfo。请立即保存 data.id 作为稳定的本站任务标识。初始状态通常为 queued,并非成片已经完成。成功提交会创建消耗积分的任务。
此 API 目前没有承诺幂等键或调用方自定义回调 URL 协议。连接在返回 ID 前失败时,不要盲目重复 POST。先检查工作区历史,或联系支持核对这次结果不确定的提交。
查询任务:GET /api/ai/task
使用相同 Bearer Key,传入 ?taskId=YOUR_SAVED_SITE_TASK_ID。即使后续出现上游 taskId,仍可继续使用已保存的本站 ID。只能查询鉴权账号拥有的任务。
状态包括 queued、pending、processing、success、failed、canceled。前三种不是最终状态。成功时,可用视频链接位于 data.taskInfo.videos[].videoUrl。失败或取消时,公开结果提供经过清理的 taskInfo.userErrorCode,而非完整的服务商错误内容。
批量查询使用 ?taskIds=ID1,ID2,返回 data.tasks,单次最多接受 10 个去重 ID。缺失或无访问权的 ID 不能用于发现其他账号任务。Bearer Key 取消或删除任务不属于本文承诺的接口能力,当前 DELETE 处理器使用浏览器登录会话。
运行 Node.js 示例
示例要求 Node.js 20 或更新版本,默认只报价。没有提供 SDANCE_OPTIONS 时使用当前模型默认值,不会自动重发生成 POST。下载可运行示例,并在服务端环境中设置密钥。
# 将参数替换为目录返回的 slug。
SDANCE_MODEL='YOUR_CATALOG_SLUG' node video-api.mjs
# 核对报价后,下面的命令提交一次任务并查询进度。
SDANCE_MODEL='YOUR_CATALOG_SLUG' SDANCE_SUBMIT=1 node video-api.mjs
# 只恢复已有任务的查询,不创建新任务。
SDANCE_TASK_ID='YOUR_SAVED_SITE_TASK_ID' node video-api.mjs
可选环境变量为 SDANCE_BASE_URL、SDANCE_PROMPT、SDANCE_IMAGE_URL 和 JSON 格式的 SDANCE_OPTIONS。设置图片 URL 后切换为图生视频。签名 URL 的有效期应足以覆盖处理过程。查询出错时保留任务 ID,恢复查询,而非重新创建。
// 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.'
);
错误、等待与积分调整
401 表示鉴权失败。报价接口可能对无效输入返回 400、过大请求返回 413、限流返回 429、报价不可用返回 502。其他接口不保证完全相同的 HTTP 映射,所以始终检查业务响应。常见生成错误还包括不支持模型、服务商未配置和积分不足。
任务错误码包括 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、generation_failed。下一步操作见排错指南。
限流时退避,合理轮询,并区分本地超时与最终失败。示例的查询次数限制是客户端等待窗口,不是服务端完成时间保证。积分调整依最终状态和服务条款处理。已完成但不喜欢的成片,并不自动算作任务失败。
相关指南与支持
可以通过图生视频工作区、产品广告教程和价格页规划流程。联系 support@sdanceai.com 时,提供接口、HTTP 状态、业务错误码、模型 slug、任务 ID 和大致时间,不要发送密钥、完整鉴权头或保密素材。