API v1

快速开始

三步生成第一个视频:创建 API 密钥,提交任务,取回结果。

查看 Markdown
本页内容

你需要一个已开通的账户,余额够预留一次生成。下面以 Seedance 2.0 的文生视频为例,时长、分辨率和画幅都用默认值(5 秒、720p、自适应)。

接入地址

正在读取接入地址…

所有请求路径都接在这个地址后面,例如 POST /v1/video/generations。示例把它放在 CHENVOYA_BASE_URL 环境变量里,末尾不带斜杠。

创建 API 密钥

在控制台的「API 密钥」页点「创建 API 密钥」,把它和上面的接入地址存进服务器的环境变量。同一个 API 密钥可以调用全部模型。

环境变量
export CHENVOYA_BASE_URL="接入地址"
export CHENVOYA_API_KEY="你的 API 密钥"

注意:API 密钥只在服务器端使用,不要写进网页、App 或代码仓库,也不要贴进文档或日志。怀疑泄露时,在控制台停用它并新建一个。

提交生成任务

向 POST /v1/video/generations 发送模型和提示词。每次创建都带一个新的 Idempotency-Key:请求超时或断线时,用同一个键原样重试,不会重复创建任务,也不会重复扣费。

IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
printf '%s\n' "保存 IDEMPOTENCY_KEY,重试时原样复用:${IDEMPOTENCY_KEY}" >&2
curl --request POST "${CHENVOYA_BASE_URL}/v1/video/generations" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "A paper boat crossing a moonlit lake."
    }
  ]
}'

接口立即返回 202 和任务 ID,生成在后台进行。

响应202节选
{
  "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "object": "video.task",
  "model": "dreamina-seedance-2-0-260128",
  "status": "queued",
  "settlement_status": "reserved",
  "quote": {
    "currency": "USD",
    "reserved_amount": "0.782453",
    "estimated_usage_upper_bound": {
      "video_tokens": 111779
    }
  },
  "created_at": 1793167380
}

提示:金额先按请求的上限预留(quote.reserved_amount),完成后按实际用量结算,多出的部分释放;失败或取消的任务不收费。

取回结果

任务按下面的顺序推进,已成功、已失败和已取消都是终态。

轮询任务

每隔几秒查询一次 GET /v1/video/tasks/{task_id},直到 status 变成终态。

curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}"
响应200节选
{
  "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "object": "video.task",
  "status": "succeeded",
  "output": {
    "assets": [
      {
        "media_type": "video",
        "role": "result",
        "url": "https://media.example.invalid/download/result-0001?signature=example",
        "expires_at": 1793253785
      }
    ]
  }
}

成功后,output.assets[0].url 就是视频的下载地址,最长 24 小时有效,且不晚于 expires_at(默认结果准备好后 7 天);再次查询任务可拿到新地址,过期后为空。把视频下载到自己的存储:

curl --output video.mp4 "$VIDEO_URL"

接收回调

不想轮询,可以让我们通知你:在控制台的「回调」页添加并验证一个 HTTPS 地址,创建任务时放进请求体的 callback_url。任务结束后你会收到 task.completed,费用结算后再收到 task.billing_settled。处理前先验证签名。

"callback_url": "https://example.com/webhooks/chenvoya"

下一步