SEEDANCE API / TEST

开发者中心

独立 API 服务 · Seedance 2.0 / 2.5

生成服务尚未启用：可查看文档、管理 Key 和测试鉴权，提交生成将返回 503。金额以人民币显示，API 使用微元整数（1 元 = 1,000,000 微元）。

接口调试

创建生成任务

查询任务

响应结果

等待请求…

接口文档

客户 API 默认端口 4100 · Bearer Key 鉴权 · JSON 请求与响应

HTTP API v0.2

客户与运维使用两个独立 HTTP 应用，不能通过客户端口访问 `/ops/*`。时间：创建/查询的 `created_at/updated_at` 为 Unix 秒；管理接口的 `expires_at/effective_from` 为 Unix 毫秒。金额字段为微元整数。

客户接口

所有客户请求带 `Authorization: Bearer sr_...`；不接受平台 PAT/JWT。RPM 包括创建和查询；余额用尽仍可查询已受理任务。`GET /healthz` 无需鉴权，只返回 `{ "status": "ok" }`。

方法 / 路径行为
POST `/api/v3/contents/generations/tasks`200 `{id}`；本服务持久化预占及任务后异步提交。建议带 `Idempotency-Key`（1–128 ASCII 可见字符）
GET `/api/v3/contents/generations/tasks/:id`200 快照；仅签发任务的 Key 可读，跨 Key/不存在均 404
GET `/api/v3/relay/quota`200 currency、money_scale、limit/used/reserved/available_micro_cny、expires_at、rpm、max_concurrent

2.0 最小 body：


{
  "model": "doubao-seedance-2-0-260128",
  "content": [{ "type": "text", "text": "一只猫走过花园" }],
  "ratio": "16:9",
  "duration": 5
}

2.5 最小 body：


{
  "model": "doubao-seedance-2-5-260628",
  "content": [{ "type": "text", "text": "一只猫走过花园" }]
}

2.5 默认 `duration=-1, ratio=adaptive`；两模型默认 `resolution=720p, generate_audio=true, return_last_frame=false, watermark=false`。不接受 Base64、上游 asset URI、首尾帧或隐式参数后缀。两模型均按能力白名单/已发布价格启用；不是配置中存在就默认可用。当前只接收单条 text，不附加提示词。

查询状态为 queued/running/succeeded/failed。内部 unknown/reconciling 不暴露为失败，仍返回 running。失败查询 HTTP 200，`error={code,message}`；只有元数据已验证、结果已转存并完成结算才返回 succeeded 与本服务 `content.video_url`。不返回上游任务 ID、供应商 URL、无依据的 token 用量或原始错误。

同步错误为 `{error:{code,message},request_id}`，并带本方生成的 `X-Request-Id`，不信任请求提供的同名头。错误词汇以 `src/errors.ts` 为唯一来源，包括参数/Key/额度/限流/幂等/内容安全/服务故障；不输出原始异常文本。429 带 Retry-After，所有返回 no-store。

参数速查

参数Seedance 2.0Seedance 2.5
modeldoubao-seedance-2-0-260128doubao-seedance-2-5-260628
content单条 text，必填单条 text，必填
duration4–15 秒，必填整数4–30 秒整数或 -1，默认 -1（自动时长）
ratio固定比例，必填固定比例或 adaptive，默认 adaptive
resolution480p / 720p / 1080p / 4k，默认 720p480p / 720p / 1080p，默认 720p
generate_audiotrue（默认），不接受 falsetrue（默认），不接受 false
watermark / return_last_framefalse（默认）false（默认）
output_format / omni_reference_task_type不接受mp4 / auto（默认）
draft / service_tier / priority / toolsfalse / default / 0 / []（默认）false / default / 0 / []（默认）
safety_identifier可选，1–64 位字母、数字、下划线或短横线同 2.0

固定比例支持 16:9、9:16、1:1、4:3、3:4、21:9。当前文本生成不支持图片、视频、音频参考输入；未列出的控制参数会被拒绝。

调用示例与计费


curl https://relay.lumenflow.net/api/v3/contents/generations/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-create-001' \
  -d '{"model":"doubao-seedance-2-0-260128","content":[{"type":"text","text":"海边日出"}],"ratio":"16:9","duration":5}'

创建响应包含任务 id。用同一个 Key 调用 GET /api/v3/contents/generations/tasks/任务ID 轮询；成功后使用 content.video_url 下载视频。下载 URL 有效 15 分钟，过期后重新查询任务获取新链接。

按模型、分辨率等价格维度计费，单价可配置。受理时按该模型最大时长预占额度（2.0 为 15 秒，2.5 为 30 秒）；实际产物验证成功后，费用 = 单价微元/秒 × 实际毫秒数 ÷ 1000，向上取整到微元，多余预占释放。明确失败释放预占；状态不确定时保留预占待核对，禁止重复提交。

本地演示价格为 0.10 元/秒，仅作演示。生成关闭时返回 503，不创建任务或扣费。

常见错误

HTTPcode处理建议
400InvalidParameter / InvalidParameter.Unsupported检查参数和模型支持范围
401AuthenticationError检查 Key 是否正确、过期或停用
403QuotaExceeded / AccessDenied.Model增加额度或开放对应模型
404ResourceNotFound检查任务 ID 及创建任务的 Key
409IdempotencyConflict相同幂等标识只用于相同请求
429RateLimitExceeded按 Retry-After 等待后重试
503ServiceUnavailable服务未启用或暂时不可用
504UpstreamTimeout查询已有任务状态，避免重复创建

v0.2 产物下载

任务成功 URL 现在由独立下载网关实际验签并流式返回私有存储产物，支持 GET/HEAD 与单段 Range；链接有效 15 分钟，环境和路径均纳入签名。缺失/过期/篡改的链接返回 401 MediaAuthenticationError，有效鉴权后的不存在对象为 404。媒体转存临时失败可自动重试，期间任务保持 running、额度保持预占；不会重复生成。详细契约见 [媒体执行器](media-executor.md)。

页面入口

- 客户服务 `/`：开发者中心，可输入客户 Key 查询额度、创建与查询任务；`/docs` 直接打开客户文档。

- 管理服务 `/`：轻量管理控制台；输入独立管理密钥后可查看和操作客户、Key、额度和价格。`/docs` 包含完整管理接口文档。

- 页面公开加载不代表管理鉴权放开。管理 API 仍逐请求校验 Bearer 管理密钥，客户 Key 不可访问。

- 密钥只保留在当前页面内存中，刷新清除；新 Key 明文只返回一次，请立即保存。管理控制台退出可清除页面内存和展示数据。