视频生成

TopsDyne 在对话模型之外提供AI 视频生成能力：文生视频与图生视频，通过 HTTP API 或控制台页面使用，费用从你的账户额度中扣减。

视频模型

模型 ID	说明
your-video-model	在售视频模型以控制台模型广场 / 视频生成页实时展示为准

各模型支持的分辨率 / 时长 / 画幅不同，以模型广场实时展示为准；费用以控制台实时配置为准。

API 调用

视频生成是异步任务：提交后立即返回任务 ID，轮询查询直到拿到视频链接。

Base URL：

• 通用 HTTP 调用：https://api.topsdyne.com/v1/videos
• 火山方舟 SDK / 生态插件（如 ComfyUI 系生态插件）：https://api.topsdyne.com/api/v3（见下方「方舟协议兼容入口」）

鉴权：Authorization: Bearer sk-xxx（你的 API Key）

端点	说明
POST /v1/videos	提交生成任务
GET /v1/videos/{id}	查询任务状态与结果

1. 提交任务

curl https://api.topsdyne.com/v1/videos \
  -H "Authorization: Bearer $TOPSDYNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "content": [
      { "type": "text", "text": "一只橘猫在草地上追蝴蝶，阳光明媚" }
    ]
  }'

响应：

{ "id": "task_xxx", "status": "queued" }

请求参数：

参数	必填	说明
model	✅	视频模型 ID（见上表）
content	✅	内容数组；type=text 携带提示词
duration	❌	时长（秒）；可省略，默认 5s
resolution	❌	分辨率（如 720p / 1080p）；可省略，默认 720p
ratio	❌	画幅（如 16:9 / 9:16）；可省略，默认 16:9
idempotency_key	❌	幂等键；同一 Key 重复提交相同幂等键不会重复计费

图生视频：在 content 数组中追加 type=image_url 条目（支持 https:// 图片地址或 base64 data:image/... URI），首帧由图片决定：

{
  "model": "your-video-model",
  "content": [
    { "type": "image_url", "image_url": "https://example.com/first-frame.jpg" },
    { "type": "text", "text": "让画面中的角色缓缓转身微笑" }
  ]
}

2. 轮询查询

curl https://api.topsdyne.com/v1/videos/task_xxx \
  -H "Authorization: Bearer $TOPSDYNE_API_KEY"

响应（完成后）：

{
  "id": "task_xxx",
  "status": "succeeded",
  "video_url": "https://...",
  "video_url_expires_at": "2026-09-10T12:00:00Z"
}

任务状态：queued（排队）→ running（生成中）→ succeeded / failed；另有 cancelled / expired 终态。

轮询建议：每 5~15 秒查询一次即可，无需高频轮询（查询接口有频率限制，超限返回 429）。

⚠️ video_url 是带时效的临时链接，过期后重新调用查询接口即可获取新链接，无需重新生成或重复计费。

方舟协议兼容入口

使用火山方舟 SDK 或其生态工具（如 ComfyUI 系生态插件）时，把 base URL 配置为 https://api.topsdyne.com/api/v3 即可——SDK 会自动在其后拼接 /contents/generations/tasks 子路径，与调用方舟官方 API 完全同构（注意：base URL 须含 /api/v3，只填裸域名会 404）：

完整端点	说明
POST /api/v3/contents/generations/tasks	提交生成任务
GET /api/v3/contents/generations/tasks/{id}	查询任务状态与结果

请求体、鉴权与 /v1/videos 完全一致，全部视频模型通用；仅查询响应会额外携带 content.video_url 嵌套字段（video_url 平铺字段仍保留），供方舟方言的工具读取。

控制台方式

不想写代码？登录控制台的视频生成页，可直接提交任务、查看进度与下载成片，与 API 共用同一额度体系。

常见报错

报错	原因	处理
402 Insufficient balance	余额不足（视频按任务预扣）	充值后重试
429	提交/查询触发频率或并发限制	稍后重试，降低轮询频率
400 ... NOT_SUPPORTED	分辨率 / 时长 / 画幅超出该模型能力	换用模型支持的参数组合

下一步

• Token 使用 — 额度与扣费说明
• 错误码速查 — 全量报错对照