快速开始¶

1. 创建 API 密钥¶

登录闪绘控制台，打开「API 密钥」并创建新密钥。建议按环境分别创建，例如 seedance-dev 与 seedance-prod。

妥善保管密钥

API 密钥等同于密码。不要写入前端代码、公开仓库、截图或聊天记录。怀疑泄露时立即停用并重新创建。

在终端中设置环境变量：

macOS / LinuxWindows PowerShell

export SHANHUI_API_KEY='sk-your-api-key'

$env:SHANHUI_API_KEY = 'sk-your-api-key'

2. 提交任务¶

curl -sS -X POST 'https://ai.shanhui.tv/v1/video/generations' \
  -H "Authorization: Bearer $SHANHUI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "一只纸飞机飞过傍晚的城市天际线，电影感，柔和运镜",
    "metadata": {
      "duration": 5,
      "ratio": "16:9",
      "resolution": "720p",
      "generate_audio": false,
      "watermark": false
    }
  }'

典型响应：

{
  "id": "task_xxxx",
  "task_id": "task_xxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1781001293
}

3. 查询状态¶

curl -sS 'https://ai.shanhui.tv/v1/video/generations/task_xxxx' \
  -H "Authorization: Bearer $SHANHUI_API_KEY"

状态流转通常为：

queued → in_progress → completed
                     ↘ failed

完成后从 metadata.url 或响应中的结果 URL 字段读取视频地址。结果地址通常带签名并会过期，请及时下载或转存。

4. 上线前检查¶

API 密钥仅存在服务端环境变量或密钥管理系统中。
HTTP 客户端的请求超时不低于 60 秒；任务结果使用轮询，不要让提交请求长期阻塞。
为轮询设置最大等待时间、指数退避或固定 8–15 秒间隔。
记录 task_id，便于重试查询与问题定位。
对 429 与 5xx 做有限次数重试，不要无限快速重试。