对接文档

文档信息

• 适用环境：生产环境
• Base URL：https://api.topview.ai
• 路径前缀：/topview-t1-cn
• 模型：topview-t1-cn
• 协议版本：方舟 /api/v3 内容生成任务协议
• 更新时间：2026-10-20

本通道沿用「Seedance（方舟官方）」的请求体、响应体和错误信封，用 Topview API Key 鉴权。和 Seedance 通道相比有这些差别：路径带 /topview-t1-cn 前缀，模型名是 topview-t1-cn，按生成视频的秒数计费，没有素材库。

平台负责上游鉴权、任务归属隔离、并发控制与积分扣费。1 平台积分 = 1 元人民币。本通道与 Seedance 各通道的任务、并发额度和价格互不相通。

1. 接口概览

POST /topview-t1-cn/api/v3/contents/generations/tasks          创建视频生成任务
GET  /topview-t1-cn/api/v3/contents/generations/tasks/{id}     查询任务

不提供任务列表、任务删除和素材库。GET /topview-t1-cn/api/v3/contents/generations/tasks（不带任务 ID）返回 404。

2. 鉴权与通用约定

Authorization: Bearer sk-你的TopviewAPIKey
Content-Type: application/json

• 只接受 Topview API Key（sk-）。不要传 Topview-Uid。
• 请求与响应都是 JSON。请求体上限 10 MB。图片、视频、音频只能传公网 HTTP(S) 地址。
• 创建成功时，响应体里的 id 就是查询用的任务 ID。请按不透明字符串保存，不要校验前缀或长度。
• 响应头 X-Topview-Request-Id 也是平台任务 ID。创建失败时用它排查。

3. 推荐调用流程

1. 创建任务，保存响应体里的 id。
2. 用 id 查询，建议每 15 秒左右查一次。这是建议值，不是限流阈值，限流见第 7 节。
3. status 为 succeeded 时，从 content.video_url 下载。
4. status 为 failed 时停止轮询。

创建返回 502 时不要直接重新创建，先按 4.6 查询确认。

带了 callback_url 时，平台会在任务进入 succeeded 或 failed 后回调你的公网地址。回调不保证必达，请保留轮询。

4. 创建视频生成任务

4.1 接口

POST https://api.topview.ai/topview-t1-cn/api/v3/contents/generations/tasks

4.2 请求字段

model

必填，固定为 topview-t1-cn，不区分大小写。其他模型名返回 400 InvalidParameter，请求不会发出。

content

必填，数组。支持以下四种元素：

图片 role 的取值：

数量上限：图片 30 张、视频 10 个、音频 10 个。

不支持 asset:// 素材引用、data: 内联 base64 和 draft_task，传了返回 400 InvalidParameter。

resolution

可选，720p 或 1080p，不传按 720p。可以放在顶层，也可以写在提示词里的 --resolution。其他值返回 400 InvalidParameter，不生成、不扣费。

ratio

可选，取 21:9、16:9、4:3、1:1、3:4、9:16、adaptive，不传按 adaptive。也可以写在提示词里的 --ratio。

有首帧（first_frame，或按上文规则被当作首帧的单张图）时，成片比例跟随首帧图片，ratio 按 adaptive 处理，传其他值不报错。需要固定比例时，请先把首帧图裁成目标比例。

duration

可选，整数，单位秒，取 4 到 30，或传 -1 由模型自动决定时长。不传按 5 秒。超出范围返回 400 InvalidParameter，不扣费。

generate_audio

可选，布尔值，默认 true。传 false 生成无声视频。

callback_url

可选。必须是公网 HTTP(S)，内网和回环地址会被拒绝。平台在任务终态后回调，回调体与查询结果相同。

seed、camera_fixed、watermark 等其他方舟字段会被忽略，不报错。

4.3 请求示例

curl -X POST \
  'https://api.topview.ai/topview-t1-cn/api/v3/contents/generations/tasks' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "topview-t1-cn",
    "content": [
      {
        "type": "text",
        "text": "电影级镜头，一艘飞船穿过深紫色星云"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://example.com/first.png" }
      }
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5
  }'

4.4 创建成功响应

{
  "id": "示例任务ID"
}

4.5 创建失败响应

失败时使用顶层 error：

{
  "error": {
    "code": "InvalidParameter",
    "message": "错误详情",
    "param": "",
    "type": "BadRequest"
  }
}

这类失败不扣费。请用响应头里的 X-Topview-Request-Id 排查。

4.6 创建返回 502：结果不确定

创建返回 HTTP 502 时，任务可能已经建好，只是平台没拿到结果。不要直接重新创建，否则可能重复生成、重复扣费，还会多占一份并发。

先用响应头里的 X-Topview-Request-Id 查询：

平台最长核对约 60 分钟。核对超时后任务按 failed 收尾，error.code 为 InternalServiceError；传了 callback_url 时会收到同样内容的失败回调。这个任务不会再产出视频，也不会扣费。

5. 查询任务

5.1 接口

GET https://api.topview.ai/topview-t1-cn/api/v3/contents/generations/tasks/{id}

{id} 是创建响应里的 id。其他通道的任务 ID 在这里返回 404。

通道暂停服务时，创建和查询都返回 HTTP 503，恢复后可以继续查询原有任务。

5.2 请求示例

curl -X GET \
  'https://api.topview.ai/topview-t1-cn/api/v3/contents/generations/tasks/示例任务ID' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey'

5.3 任务状态

queued、running、succeeded、failed。

视频生成完成后，平台要先把视频存到自己的存储，再返回 succeeded。所以生成完成后还会有一小段时间显示 running，这是正常的。

5.4 成功响应

{
  "id": "示例任务ID",
  "model": "topview-t1-cn",
  "status": "succeeded",
  "content": {
    "video_url": "https://签名地址/video.mp4"
  },
  "usage": {
    "total_seconds": 5
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "created_at": 1787000000,
  "updated_at": 1787000300
}

usage.total_seconds 是计费秒数，见第 6 节。它以模型实际计费秒数为准：无参考视频时一般等于请求的 duration；带参考视频时还包含参考视频的时长，会大于 duration。

resolution、ratio、duration 回显创建请求里传入的值，请求没传的字段不返回。

5.5 失败响应

{
  "id": "示例任务ID",
  "model": "topview-t1-cn",
  "status": "failed",
  "error": {
    "code": "SensitiveContentDetected",
    "message": "失败原因"
  }
}

失败任务不扣费。

5.6 时效

content.video_url 是签名地址，会过期，每次查询都会重新签发。任务记录保留 7 天，超期后查询返回 404。收到 succeeded 后请尽快下载到自己的存储。

5.7 任务不存在

不存在、不属于当前账号、或属于其他通道，统一返回 HTTP 404：

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The specified resource `被查询的ID` is not found.",
    "param": "",
    "type": "NotFound"
  }
}

6. 计费规则

原价积分 = usage.total_seconds × 每秒单价
最终扣费积分 = 原价积分 × 账号折扣率

保留 6 位小数，四舍五入。1 平台积分 = 1 元人民币。没配折扣时折扣率为 1。

单位是积分 / 秒。

• 表里没有的分辨率直接 400，不生成、不扣费。
• 不传 resolution 时按 720p 计费。
• 计费秒数以查询返回的 usage.total_seconds 为准。它取模型实际计费秒数，平台按它原样扣费，不再另行取整。
  • 无参考视频：按请求的 duration 计。成片实际时长常比 duration 略长，多出的零点几秒不计费（例如请求 4 秒、成片 4.06 秒，按 4 秒计）。
  • 带参考视频：包含成片与参考视频两部分的秒数，具体秒数以返回值为准。
• content 里出现 type: "video_url" 时使用「含视频输入」单价。
• failed 和创建失败不扣费。
• 只在 succeeded 之后扣一次，扣上费才交付：扣上才返回 succeeded 与视频地址、发送成功回调，扣费未完成时查询仍返回 running。
• 扣费时余额不足，查询返回 HTTP 402 AccountOverdueError，不返回视频。充值后再查询即补扣并交付。
• 账号折扣在 Overview 的 Model discounts 查看。未列出的模型按标准价。

示例：topview-t1-cn、720p、成片 5 秒、无参考视频、无折扣，usage.total_seconds 为 5：

5 × 1.05 = 5.250000 积分

示例：topview-t1-cn、720p、参考视频 2 秒、请求 duration 为 4、成片 4.06 秒、无折扣，返回的 usage.total_seconds 为 7：

7 × 0.63 = 4.410000 积分

8 折则再乘 0.8。

7. 并发与限流

本通道的视频并发单独计算，必须由运营开通。没有额度行时创建返回 429。视频生成结束即释放，不等平台交付完成：交付期间显示 running 的任务不占并发。

并发用满返回 HTTP 429，RateLimitExceeded。

查询按团队限流，每个团队每秒最多 200 次，超出返回 HTTP 429，RateLimitExceeded。轮询建议每 15 秒左右一次。

8. 错误响应

排查时提供创建返回的 id 或 X-Topview-Request-Id。不要提供 API Key。

9. 接入注意事项

• 路径必须带 /topview-t1-cn，模型名必须是 topview-t1-cn。
• 素材只能传公网 HTTP(S) 地址，不支持 asset:// 和 base64。
• succeeded 后尽快下载视频。
• 建议每 15 秒左右轮询一次。
• 创建返回 502 不要直接重建，先按 4.6 查询。
• 400、401、402、404 不要自动重试。429 用指数退避。