API VERSION 2026-09-20

Seedance API 文档

对接一次，底层供应商可以由 CreativeFly Token Platform 路由切换，客户侧请求契约保持稳定。

Production Base URLhttps://token-api.creativefly.ai

快速开始

所有生成任务均为异步任务。创建任务后会返回 task_id，请按 poll_after_seconds 建议间隔查询结果。

身份验证

在每个请求的 Authorization Header 中发送 API Key。请只在服务端保存 Key，不要放入网页、移动端或公开仓库。

Authorization: Bearer $CTP_API_KEY

价格

GET/v1/prices

返回当前账户可用规格的人民币预估价格。金额统一使用整数分；价格按火山 token 成本乘以 CTP 独立定倍率计算。任务创建时按请求规格冻结，成功后优先使用火山响应明确返回的真实 token 结算并释放差额；如果供应商没有返回 token，会按创建时的请求估算价结算并在管理端标记“火山未返回”。

{
  "object": "list",
  "currency": "CNY",
  "pricing_basis": "volcengine_tokens",
  "data": [{
    "logical_model": "seedance-2.5",
    "duration_seconds": 5,
    "resolution": "720p",
    "has_input_video": false,
    "output_count": 1,
    "price_fen": 1361,
    "upstream_price_fen_per_million_tokens": 7000,
    "multiplier": 1.8
  }]
}

上传和管理素材

客户只使用 CTP asset_id；供应商 Asset ID 不会出现在公开契约中。上传分两步完成，预签名 URL 有效期为 15 分钟。

POST/v1/assets/uploads

curl -X POST https://token-api.creativefly.ai/v1/assets/uploads \
  -H "Authorization: Bearer $CTP_API_KEY" \
  -H "Idempotency-Key: asset-order-20260919-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "产品参考图",
    "kind": "image",
    "mime_type": "image/png",
    "size_bytes": 184320,
    "usage_type": "generic_reference"
  }'

# 1. 按创建响应中的 upload.method、upload.url、upload.headers 上传原始文件
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @product.png

# 2. 通知 CTP 校验对象大小、类型及可选 SHA-256
curl -X POST https://token-api.creativefly.ai/v1/assets/{asset_id}/complete \
  -H "Authorization: Bearer $CTP_API_KEY"

完成接口返回 active 后可用于生成。还可调用 GET /v1/assets、GET /v1/assets/{asset_id} 和 DELETE /v1/assets/{asset_id}。

在生成请求中引用

{
  "model": "seedance-2.5",
  "content": [
    { "type": "text", "text": "让图片中的产品缓慢旋转" },
    {
      "type": "image_url",
      "asset_id": "<CTP asset_id>",
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p"
}

素材组、虚拟人像与真人授权

POST/v1/asset-groups

type 可为 generic、virtual_human 或 verified_human。普通参考素材可直接上传；虚拟人像和真人素材必须属于对应素材组，并完成供应商入库。真人组在创建后为 pending_authorization，未完成人脸认证、本人授权及供应商绑定前不能用于生成。

当前客户测试阶段不会把普通含人脸文件自动视作已授权真人素材，也不会通过 URL 方式绕过供应商的人像审核。

创建视频

POST/v1/video/generations

必须携带唯一的 Idempotency-Key。网络重试时复用同一个 Key，可避免重复创建任务和重复冻结金额。图片、首尾帧、参考视频和参考音频均使用已激活的 CTP asset_id。

字段	类型	必填	说明
`model`	string	是	seedance-2.0、seedance-2.0-fast 或 seedance-2.5
`prompt`	string	是	生成提示词，1–12000 字符
`duration`	integer	否	视频时长（秒）；当前测试 SKU 为 5
`ratio`	string	否	画面比例，默认 16:9
`resolution`	string	否	480p、720p 或 1080p；默认 720p
`output_count`	integer	否	输出数量，1–8；默认 1
`generate_audio`	boolean	否	是否生成音频
`watermark`	boolean	否	是否添加水印
`output_format`	string	否	mp4 或 mov

curl -X POST https://token-api.creativefly.ai/v1/video/generations \
  -H "Authorization: Bearer $CTP_API_KEY" \
  -H "Idempotency-Key: order-20260916-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "一杯冰咖啡放在晨光中的木桌上，商业广告质感",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "output_count": 1,
    "generate_audio": false,
    "watermark": false,
    "output_format": "mp4"
  }'

成功响应 · 202

{
  "id": "9516dad2-55c9-4a19-bcee-5234bfb83fdd",
  "task_id": "9516dad2-55c9-4a19-bcee-5234bfb83fdd",
  "object": "video_generation",
  "status": "queued",
  "poll_after_seconds": 10,
  "billing": { "currency": "CNY", "amount_fen": 1361, "reserved_amount_fen": 1361, "status": "reserved" }
}

查询与取消任务

GET/v1/video/generations/{task_id}

curl https://token-api.creativefly.ai/v1/video/generations/{task_id} \
  -H "Authorization: Bearer $CTP_API_KEY"

成功后，响应会同时返回稳定的 CTP asset_id 和有效期 15 分钟的预览、下载 URL。URL 过期后重新查询任务或素材详情即可刷新。

{
  "id": "9516dad2-55c9-4a19-bcee-5234bfb83fdd",
  "status": "succeeded",
  "billing": { "currency": "CNY", "amount_fen": 1361, "reserved_amount_fen": 1361, "status": "settled" },
  "result": { "outputs": [{
    "asset_id": "<CTP asset_id>",
    "mime_type": "video/mp4",
    "size_bytes": 4551294,
    "preview_url": "<15-minute signed URL>",
    "preview_url_expires_at": "2026-09-20T10:00:00.000Z",
    "download_url": "<15-minute signed URL>"
  }] }
}

POST/v1/video/generations/{task_id}/cancel

取消排队中或处理中的任务。未结算的冻结金额会自动原路退回。

账户与人民币余额

GET/v1/balance

返回现金、赠送测试余额和冻结金额。所有金额字段均为人民币分（fen）的整数，避免浮点误差。CTP 余额与 CreativeFly.AI 的个人/企业 Credit 相互独立。

{
  "object": "balance",
  "currency": "CNY",
  "available_fen": 10000,
  "cash_available_fen": 0,
  "trial_available_fen": 10000,
  "reserved_fen": 0
}

/v1/credits 暂时保留为兼容别名，新接入请使用 /v1/balance。

GET/v1/account

查看客户代码、“今日可提交输出”上限、并发限制和每日消费上限。三项均为独立风控限制；余额不是每日额度。

错误处理

错误响应统一包含 request_id、错误码、信息和是否建议重试。不要盲目重试 4xx 请求；仅在 retryable: true 时使用退避策略。

{
  "request_id": "...",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient CNY balance",
    "retryable": false
  }
}