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 和大致时间,不要发送密钥、完整鉴权头或保密素材。