Seedance 2.0 按秒计费视频 API

本文面向通过 AnyRoute 调用 Seedance 2.0 按秒计费模型的开发者，介绍视频任务的创建、查询、结果读取和回调。

本服务只提供视频生成能力，不提供素材库、素材组、真人授权或公域人物接口。图片、视频和音频素材应直接通过公网 HTTPS URL 传入；图片和音频也可以使用受支持的 Base64 Data URL。

本本服务可过人脸，通过公网 HTTPS URL 或者 Base64 Data URL的形式传入参考素材。

视频生成采用异步任务模式：提交任务后保存任务 ID，再查询任务状态，并通过平台结果接口读取视频。

1. 基础信息

1.1 Base URL

https://biz.anyroute.io

也可以使用管理员提供的其他 AnyRoute 接入域名。本文示例统一使用环境变量：

1.2 鉴权

所有接口均使用 Bearer Token：

发送 JSON 时还需要：

客户只使用 AnyRoute API Token 进行鉴权。

1.3 任务 ID

平台返回不透明任务 ID：

task_xxx

只能使用平台返回的完整 ID，不要自行构造或修改。任务按用户隔离；同一用户创建的多个 API Token 可以读取该用户自己的任务，但不能读取其他用户的任务。

2. 模型与计费方式

该产品将档位和分辨率编码在模型名称中，因此请求中不再单独传 resolution。

常见模型名称包括：

Seedance-2.0-480p
Seedance-2.0-720p
Seedance-2.0-1080p
Seedance-2.0-4k
Seedance-2.0-fast-480p
Seedance-2.0-fast-720p
Seedance-2.0-mini-480p
Seedance-2.0-mini-720p

实际可调用模型、公开别名和单价以 AnyRoute 价格页面及当前 API Token 权限为准。本文示例使用：

Seedance-2.0-mini-480p

视频费用按以下方式计算：

模型每秒单价 × 请求 duration × 分组倍率

duration 未提供时按 4 秒创建和计费。

duration 只接受 4-15 秒内的整数。

不支持 duration: -1 或通过帧数推导时长。

任务提交超过 24 小时仍没有明确终态时，平台会将任务置为 expired 并退还该任务的全部预扣额度。

调用方应以价格页面和账户消费记录为准。接口通常不返回 token usage，因为该产品按请求时长结算。

3. 视频输入能力

推荐的视频入口为：

3.1 内容类型

`type`	载荷字段	支持的 `role`
`text`	`text`	不传 `role`
`image_url`	`image_url.url`	`reference_image`、`first_frame`、`last_frame`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`

未显式传入媒体 role 时，平台会按媒体类型补为 reference_image、reference_video 或 reference_audio。文本不允许设置 role。

3.2 素材地址

支持以下输入：

图片：公网 HTTPS URL，或受支持的图片 Base64 Data URL。

视频：公网 HTTPS URL。

音频：公网 HTTPS URL，或受支持的音频 Base64 Data URL。

不支持以下输入：

asset:// 素材引用。

裸 Base64 字符串。

Base64 视频。

multipart/form-data 文件上传。

带有用户名、密码或 URL fragment 的素材地址。

图片 Data URL 示例：

data:image/jpeg;base64,<BASE64_DATA>

允许 jpeg、png、webp、bmp、tiff、gif，格式名必须小写。单张图片解码后必须小于 30 MB。

音频 Data URL 示例：

data:audio/mpeg;base64,<BASE64_DATA>

允许 wav、mp3、mpeg，格式名必须小写。单段音频不超过 15 MB，最多 3 段。参考音频不能作为唯一参考输入，必须同时提供至少一张参考图片或一个参考视频。

单次请求体及内联媒体总量不得超过 64 MB。

3.3 参考素材数量

当前模型合同支持：

素材	最大数量
参考图片	9
参考视频	3
参考音频	3

首尾帧、素材格式以及多种参考素材组合仍需满足所选模型的生成规则。超过模型能力或不兼容的组合可能在任务执行阶段失败。

3.4 Prompt 中引用素材

普通参考素材按其在 content 中的同类型出现顺序编号。Prompt 可以使用：

@image1  @image2
@video1  @video2
@audio1  @audio2

例如，第一张 reference_image 对应 @image1，第二张对应 @image2。first_frame 和 last_frame 不参与普通参考图片编号。

4. 请求参数

4.1 支持的顶层参数

字段	类型	必填	说明
`model`	string	是	公开模型名称
`content`	array	是	1-64 项，至少包含一项非空文本
`duration`	integer	否	4-15 秒；缺省为 4
`ratio`	string	否	画面比例，以当前模型校验结果为准
`callback_url`	string	否	接收平台任务回调的公网 HTTPS URL

ratio 是生成偏好。使用首帧或尾帧时，最终画面比例还可能受到输入图片比例影响，因此不应仅依赖 ratio 推断成片尺寸。

4.2 不支持的顶层参数

以下字段不属于该产品合同：

frames
resolution
seed
camera_fixed
generate_audio
watermark
return_last_frame
service_tier
execution_expires_after
priority
draft
tools

提交这些字段会返回 400 unsupported_video_parameter，不会静默忽略。即使字段值为 0 或 false，只要显式传入仍会被拒绝。

请求使用严格 JSON 校验。未知字段返回 400 invalid_request。

5. 创建视频任务

该接口支持 Idempotency-Key。建议每个业务订单使用一个稳定且唯一的 Key。

5.1 文生视频

5.2 单张参考图片

5.3 多张参考图片

{
  "model": "Seedance-2.0-mini-480p",
  "content": [
    {
      "type": "text",
      "text": "让 @image1 中的人物走入 @image2 的城市街景，保持人物外貌一致"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/person.jpg"},
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/city.jpg"},
      "role": "reference_image"
    }
  ],
  "duration": 8,
  "ratio": "16:9"
}

5.4 参考图语义标注

需要明确参考图名称及画面用途时，可以在对应 reference_image 上增加 reference_options：

{
  "model": "Seedance-2.0-mini-480p",
  "content": [
    {
      "type": "text",
      "text": "人物一在城市背景中向镜头走来"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/person.jpg"},
      "role": "reference_image",
      "reference_options": {
        "name": "人物一",
        "role": "subject"
      }
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/city.jpg"},
      "role": "reference_image",
      "reference_options": {
        "name": "城市背景",
        "role": "background"
      }
    }
  ],
  "duration": 8,
  "ratio": "16:9"
}

reference_options 规则：

只能用于 image_url + reference_image。

至少提供 name 或 role 之一。

name 必须是有效 UTF-8，去除首尾空白后不能为空，最长 256 bytes，不能包含控制字符。

role 只允许 subject 或 background。

使用语义标注时，建议为请求中的每张普通参考图都提供清晰的 name 和 role。

5.5 首尾帧

{
  "model": "Seedance-2.0-mini-480p",
  "content": [
    {
      "type": "text",
      "text": "从第一帧平滑过渡到最后一帧，动作自然"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/first.jpg"},
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/last.jpg"},
      "role": "last_frame"
    }
  ],
  "duration": 4,
  "ratio": "16:9"
}

reference_options 不能用于 first_frame 或 last_frame。

5.6 图片、视频和音频混合参考

{
  "model": "Seedance-2.0-mini-480p",
  "content": [
    {
      "type": "text",
      "text": "以 @image1 为主体，参考 @video1 的运动节奏，并使用 @audio1 作为声音与节奏参考"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/subject.jpg"},
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {"url": "https://media.example.com/motion.mp4"},
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://media.example.com/music.mp3"},
      "role": "reference_audio"
    }
  ],
  "duration": 4,
  "ratio": "16:9"
}

5.7 Base64 图片和音频

{
  "model": "Seedance-2.0-mini-480p",
  "content": [
    {
      "type": "text",
      "text": "参考图片主体和音频节奏生成短视频"
    },
    {
      "type": "image_url",
      "image_url": {"url": "data:image/png;base64,<IMAGE_BASE64>"},
      "role": "reference_image"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "data:audio/mpeg;base64,<AUDIO_BASE64>"},
      "role": "reference_audio"
    }
  ],
  "duration": 4,
  "ratio": "16:9"
}

Base64 必须是标准、无空白、无换行的 canonical Base64，且声明的媒体格式必须与解码后的文件头一致。

5.8 创建响应

提交结果确定时返回 200：

{
  "id": "task_xxx"
}

如果平台已建立任务，但暂时无法确认提交结果，可能返回 202，响应中仍包含同一个 task_xxx。此时不要重新提交，应查询该任务。

平台不会因超时、断连、429 或 5xx 自动重新发送同一个创建请求。

6. 查询视频任务

成功任务示例：

{
  "id": "task_xxx",
  "model": "Seedance-2.0-mini-480p",
  "status": "succeeded",
  "progress": 100,
  "error": null,
  "created_at": 1783670400,
  "updated_at": 1783670580,
  "content": {
    "video_url": "https://biz.anyroute.io/v1/videos/task_xxx/content"
  },
  "duration": 4,
  "ratio": "16:9"
}

平台状态固定为：

queued | running | cancelled | succeeded | failed | expired

progress 为 0-100 的归一化整数。所有终态均为 100；非终态最多为 99。只有成功任务才会返回视频结果地址。

该产品不支持 return_last_frame，因此任务不会返回 last_frame_url。任务详情也不会返回 Prompt、输入媒体 URL、Base64 内容、内部处理信息或原始结果地址。

失败任务示例：

{
  "id": "task_xxx",
  "model": "Seedance-2.0-mini-480p",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "video_generation_failed",
    "message": "video generation failed"
  },
  "created_at": 1783670400,
  "updated_at": 1783670580,
  "duration": 4,
  "ratio": "16:9"
}

7. 查询视频任务列表

查询参数：

参数	说明
`page_num`	默认 1，范围 1-500
`page_size`	默认 20，范围 1-500
`filter.status`	可重复，筛选任务状态
`filter.task_ids`	可重复，最多 100 个任务 ID
`filter.model`	按公开模型名称筛选

{
  "items": [],
  "total": 0
}

列表只返回当前用户最近 7 天的任务。更早的任务仍可通过任务详情接口查询。

8. 获取生成视频

结果接口必须携带属于任务 owner 的 Bearer Token，支持标准 HTTP Range 请求，并使用 private, no-store 缓存策略。

结果已过期且无法安全刷新时返回：

410 video_result_expired

调用方不应保存或依赖任务详情之外出现的临时媒体地址，应始终使用平台返回的 content.video_url。

9. 视频任务回调

创建任务时可以提供公网 HTTPS callback_url。平台在任务状态变化时向该地址发送 POST 回调。

回调是至少一次投递，接收方必须按 event_id 去重。回调失败不会改变任务状态、结果或计费。

{
  "event_id": "evt_xxx",
  "type": "succeeded",
  "created_at": 1783670580,
  "data": {
    "id": "task_xxx",
    "model": "Seedance-2.0-mini-480p",
    "status": "succeeded",
    "error": null,
    "created_at": 1783670400,
    "updated_at": 1783670580,
    "version": 4,
    "content": {
      "video_url": "https://biz.anyroute.io/v1/videos/task_xxx/content"
    },
    "duration": 4,
    "ratio": "16:9"
  }
}

回调头：

X-New-Api-Event-Id
X-New-Api-Task-Id
X-New-Api-Timestamp
X-New-Api-Signature: v1=<hex hmac-sha256>

签名密钥由创建任务使用的 API Token 通过 HKDF-SHA256 派生，info 为 new-api-video-callback-v1，无 salt。签名内容为：

timestamp + "\n" + event_id + "\n" + raw_request_body

建议校验时间戳窗口、使用常量时间比较签名，并在验签成功后再按 event_id 去重处理。

10. `/v1/videos` 兼容接口

V3 是推荐入口。需要 OpenAI 风格视频对象时，可以使用：

10.1 简单创建

简单参考图可以使用 input_reference、image 或 images。seconds 可以是整数或整数字符串；也可以改用整数 duration。同时传 seconds 和 duration 时，两者必须相等。

不要传 size、resolution 或其他第 4.2 节列出的字段。

10.2 复杂输入

首尾帧、参考视频、参考音频或 reference_options 应通过 content 表达：

{
  "model": "Seedance-2.0-mini-480p",
  "prompt": "人物一自然转身并看向镜头",
  "content": [
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/person.jpg"},
      "role": "reference_image",
      "reference_options": {
        "name": "人物一",
        "role": "subject"
      }
    }
  ],
  "duration": 4,
  "ratio": "16:9"
}

也可以将 content 放在 metadata.content 中，但不能同时在顶层和 metadata 中提供。V1 同样只接受 JSON，不支持 Multipart。

10.3 查询响应

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "Seedance-2.0-mini-480p",
  "status": "completed",
  "progress": 100,
  "created_at": 1783670400,
  "completed_at": 1783670580,
  "seconds": "4",
  "metadata": {
    "url": "https://biz.anyroute.io/v1/videos/task_xxx/content",
    "video_url": "https://biz.anyroute.io/v1/videos/task_xxx/content"
  }
}

V1 状态为：

queued | in_progress | completed | failed

V1 和 V3 共用同一个任务系统。V1 创建的任务可以使用 V3 查询，V3 创建的任务也可以使用 V1 查询。

11. 幂等

以下创建接口支持 Idempotency-Key：

POST /api/v3/contents/generations/tasks

POST /v1/videos

Key 必须是有效 UTF-8，最长 64 bytes，并且请求中只能出现一次。

相同用户、相同操作、相同 Key 和相同请求会返回原任务或原稳定错误。

相同 Key 对应不同请求时返回 409 idempotency_conflict。

原操作仍在竞争或暂时不能重放时返回 409 idempotency_in_progress。

未提供 Key 时不保证跨 HTTP 请求去重。

客户端遇到连接中断时，应使用原 Key 重试或查询已经取得的 task_xxx，不要为同一业务订单生成新 Key。

12. 计费与任务终态

平台在任务提交前按 duration 预扣额度。正常终态处理规则如下：

终态	计费结果
`succeeded`	按请求 `duration` 结算
`failed`	退还该任务的全部预扣额度
`expired`	对 24 小时未确定任务执行全额退款

生成文件的容器时长可能因编码边界略高于或低于请求整数秒数，计费仍以经过校验的请求 duration 为准，不按媒体容器元数据反向调整。

13. 当前不支持的接口和操作

接口或操作	说明
`/v1/assets`	不提供私有素材库
`/v1/asset-groups`	不提供素材组
`/v1/assets/public`	不提供公域人物目录
真人授权会话	不提供独立真人授权接口
`asset://...`	不能在视频请求中引用平台素材 ID
`multipart/form-data`	不接收文件上传
`DELETE /api/v3/contents/generations/tasks/{task_id}`	不支持取消或删除任务，返回 `task_delete_not_supported`
`GET /v1/videos/{task_id}/last-frame`	不生成独立尾帧结果

不支持的操作不会改变已有任务状态。

14. 错误格式

统一错误响应：

{
  "error": {
    "message": "request contains an unsupported parameter",
    "type": "unsupported_video_parameter",
    "code": "unsupported_video_parameter"
  }
}

客户端应优先判断稳定的 error.code，不要依赖 message 文案。

常见错误：

HTTP	`code`	含义
400	`invalid_request`	JSON、字段、参数范围、Base64 或 URL 不合法
400	`unsupported_video_parameter`	当前模型不支持该字段、role 或参数组合
400	`invalid_idempotency_key`	幂等 Key 不合法
400	`task_delete_not_supported`	当前产品不支持取消或删除任务
404	`task_not_found`	任务不存在或不属于当前用户
409	`idempotency_conflict`	同一个幂等 Key 对应不同请求
409	`idempotency_in_progress`	幂等操作尚不能安全重放
410	`video_result_expired`	视频结果已过期且无法刷新
409	`asset_binding_unavailable`	当前模型服务暂时不可用或配置不完整
429	`video_concurrency_limit_exceeded`	当前用户的视频任务并发数已达到上限
502	`video_upstream_error`	视频生成服务返回异常响应

异步生成失败时，任务详情中的 error.code 可能包含更具体的安全错误码；如果没有可公开的稳定详情，平台统一返回 video_generation_failed。

15. 推荐调用流程

1. 从价格页面取得当前 Token 可用的按秒计费模型名称
2. 准备公网 HTTPS 素材地址，或生成合规的图片/音频 Data URL
3. POST /api/v3/contents/generations/tasks，并保存 task_xxx
4. 使用 callback_url 接收状态变化，或定时查询任务详情
5. queued/running：继续等待，不要重复创建
6. succeeded：访问 content.video_url
7. failed/expired：读取 error.code，并按业务策略处理

轮询建议使用退避间隔，不要高频查询。无论使用回调还是轮询，都应以平台任务详情为最终状态来源。

16. 安全与合规建议

只提交自己有权使用的图片、视频、音频和人物素材。

生成涉及真人身份特征的内容前，应取得素材权利人及生成用途所需的合法授权。

不要把 API Token 写入前端代码、公开仓库、素材 URL 或日志。

回调接收端必须使用 HTTPS、验签并按 event_id 去重。

不要记录 Base64 正文；必要时只记录内容哈希、媒体类型和字节数。

不要依赖生成结果中的临时地址或内部错误文案，只使用平台公开任务 ID、状态、错误码和结果接口。

Seedance 海外线路 - 3 （特殊渠道）

Seedance 2.0 按秒计费视频 API#

1. 基础信息#

1.1 Base URL#

1.2 鉴权#

1.3 任务 ID#

2. 模型与计费方式#

3. 视频输入能力#

3.1 内容类型#

3.2 素材地址#

3.3 参考素材数量#

3.4 Prompt 中引用素材#

4. 请求参数#

4.1 支持的顶层参数#

4.2 不支持的顶层参数#

5. 创建视频任务#

5.1 文生视频#

5.2 单张参考图片#

5.3 多张参考图片#

5.4 参考图语义标注#

5.5 首尾帧#

5.6 图片、视频和音频混合参考#

5.7 Base64 图片和音频#

5.8 创建响应#

6. 查询视频任务#

7. 查询视频任务列表#

8. 获取生成视频#

9. 视频任务回调#

10. /v1/videos 兼容接口#

10.1 简单创建#

10.2 复杂输入#

10.3 查询响应#

11. 幂等#

12. 计费与任务终态#

13. 当前不支持的接口和操作#

14. 错误格式#

15. 推荐调用流程#

16. 安全与合规建议#