对接文档

文档信息

本次变更（2026-09-01）：素材接口（/v1/sd/assets、/v1/df/assets）已下线，参考素材改为在创建任务时直接传公网 URL，平台侧自动完成上传与预处理。视频接口路径、请求响应结构与既有模型名均保持不变，已有集成无需改造。

1. 接口概览

2. 鉴权与请求头

2.1 鉴权方式

使用 topview 平台签发的 API Key，通过 Authorization 头传递：

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

• Authorization: Bearer sk-... 为必传。
• API Key 不区分类型，任意有效 Key 均可调用本文档路由。
• Topview-Uid、Topview-Team-Id 均由平台根据 API Key 的归属自动注入，客户端无需传递。
• 出站鉴权由 topview-api 统一注入上游凭证，客户端无需关心上游 Key。

2.2 通用约定

• 除特别说明外，请求与响应均为 JSON（Content-Type: application/json）。
• 视频结果地址为 topview 平台可交付地址（已完成转存），可直接访问；转存目标默认为 S3，创建任务时传 storage: "oss" 可改为阿里云 OSS。

3. 推荐调用流程

1. 创建视频任务，content 中的参考素材直接填公网可访问的 URL；如需异步通知，创建时传入 callback_url。
2. 获取结果二选一：轮询任务详情接口直到 completed / failed；或在创建时传入 callback_url，由平台在任务状态变更时主动回调（见 5.4 回调通知）。

素材无需预先上传：平台会在创建任务时自动拉取并预处理 content 中的素材 URL，因此不再需要单独的素材上传与查询步骤。素材 URL 需在任务创建期间保持公网可访问。

说明：回调与轮询可同时使用。即便配置了 callback_url，也建议保留轮询作为兜底，避免回调网络异常导致漏单。

4. 素材接口（已下线）

以下四个素材端点自 2026-09-01 起下线，调用会返回错误，请从集成中移除：

迁移方式：把原先 asset://<素材Id> 的引用替换为素材本身的公网 URL，直接填在创建任务请求的 content[].image_url.url 中，其余字段不变。上传与预处理由平台在创建任务时自动完成。

- { "type": "image_url", "image_url": { "url": "asset://asset-20260704195242-5d79l" } }
+ { "type": "image_url", "image_url": { "url": "https://example.com/your-image.jpg" } }

素材 URL 需公网可访问，且在任务创建期间保持有效。此前上传的素材 ID 不再受理。

5. 视频任务接口

5.1 创建视频任务

接口

POST /v1/video/generate

请求字段

请求示例

curl -X POST 'https://api.topview.ai/v1/video/generate' \
  -H 'Authorization: Bearer sk-你的topviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "dreamina-seedance-2-0-260128-max",
    "content": [
      {
        "type": "text",
        "text": "这个人在跳舞"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/your-image.jpg"
        },
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "resolution": "480p",
    "ratio": "1:1",
    "generate_audio": false,
    "watermark": false
  }'

响应示例

{
  "task": {
    "id": "mvt-475330e24c864ec6",
    "status": "pending",
    "model": "dreamina-seedance-2-0-260128-max",
    "duration_seconds": 5,
    "outputs": [],
    "error": null,
    "created_at": "2026-07-04T16:41:41.705Z",
    "completed_at": null
  }
}

记录返回的 task.id，用于后续查询任务状态。

5.2 查询任务列表

接口

GET /v1/video/tasks

任务列表只返回当前 API Key 所属用户创建的任务，不会展示共享上游账号中的其他任务。

查询参数

请求示例

curl 'https://api.topview.ai/v1/video/tasks?page=1&pageSize=20' \
  -H 'Authorization: Bearer sk-你的topviewAPIKey'

响应示例

{
  "tasks": [
    {
      "id": "mvt-179197ccca01401a",
      "status": "completed",
      "model": "dreamina-seedance-2-0-260128-max",
      "duration_seconds": 4,
      "outputs": [
        "<video-download-url>"
      ],
      "error": null,
      "created_at": "2026-05-26T05:26:52.505Z",
      "completed_at": "2026-05-26T05:35:22.566Z",
      "usage": {
        "completion_tokens": 40594,
        "total_tokens": 40594
      }
    }
  ],
  "total": 1,
  "totalPages": 1
}

说明：dreamina-*-max 只返回平台已转存的可交付地址，上游已生成但仍在转存时状态显示为 processing 且 outputs 为空；doubao-*-max 直接交付上游原始链接，生成完成即可从 outputs 取到地址。

5.3 查询单个任务详情

接口

GET /v1/video/tasks/{taskId}

路径参数

请求示例

curl 'https://api.topview.ai/v1/video/tasks/{task_id}' \
  -H 'Authorization: Bearer sk-你的topviewAPIKey'

处理中响应示例

{
  "task": {
    "id": "mvt-179197ccca01401a",
    "status": "processing",
    "model": "dreamina-seedance-2-0-260128-max",
    "duration_seconds": 4,
    "outputs": [],
    "error": null,
    "created_at": "2026-05-26T05:26:52.505Z",
    "completed_at": null
  }
}

成功响应示例（status 为 completed 时从 outputs 取视频地址）

{
  "task": {
    "id": "mvt-179197ccca01401a",
    "status": "completed",
    "model": "dreamina-seedance-2-0-260128-max",
    "duration_seconds": 4,
    "outputs": [
      "<video-download-url>"
    ],
    "error": null,
    "created_at": "2026-05-26T05:26:52.505Z",
    "completed_at": "2026-05-26T05:35:22.566Z",
    "usage": {
      "completion_tokens": 40594,
      "total_tokens": 40594
    }
  }
}

重要：两条线路的交付形式不同。

• dreamina-*-max：上游生成完成但平台尚未完成结果转存时，接口会临时返回 processing 且 outputs 为空，请继续轮询；待转存完成后 status 变为 completed，outputs[0] 为 topview 平台可交付地址，长期有效。
• doubao-*-max：不等转存，上游生成完成即返回 completed，outputs[0] 是上游原始视频链接。该链接由上游在任务完成时一次性签发，有效期 24 小时且不可续期——重新查询同一任务拿回的是同一个链接，不会换发新的。超过 24 小时后重新查询，平台会自动改为返回 topview 平台留档地址，因此任何时候重查都能拿到可用地址，但请务必在收到 completed 后的 24 小时内下载。

5.4 回调通知

在创建视频任务时传入 callback_url，平台会在任务状态变更（如 processing / completed / failed）时，向该地址发起 POST 请求，推送最新任务快照。

• 回调请求体与查询单个任务详情的响应结构完全一致（task 信封）；其中 task.id 即你创建任务时返回的任务 ID，可直接对应本地记录，无需额外映射。
• task.status=completed 且 outputs 非空时为最终成功结果，outputs[0] 可直接访问：dreamina-*-max 给的是已完成转存的 topview 平台地址，doubao-*-max 给的是上游原始链接（见 5.3 的有效期说明）。
• callback_url 长度不得超过 1024 字符，必须是可从公网访问的 HTTP(S) 地址；不支持内网、环回、云元数据地址或依赖 HTTP 重定向的回调入口。
• 平台会过滤上游乱序或重复的非终态事件，确保对外状态不会倒退；客户端仍应按 task.id + task.status 对回调做幂等处理。
• 你的服务收到回调后应返回 2xx 表示接收成功；返回非 2xx 或超时，平台会按策略自动重试，多次失败后停止并告警。
• 回调仅用于状态通知，结果最终以 completed（且 outputs 非空）或 failed 为准；建议同时保留轮询作为兜底。

回调请求示例（平台 → 你的 callback_url）

POST {你的 callback_url}
Content-Type: application/json

{
  "task": {
    "id": "mvt-179197ccca01401a",
    "status": "completed",
    "model": "dreamina-seedance-2-0-260128-max",
    "duration_seconds": 4,
    "outputs": [
      "<video-download-url>"
    ],
    "error": null,
    "created_at": "2026-05-26T05:26:52.505Z",
    "completed_at": "2026-05-26T05:35:22.566Z"
  }
}

5.5 获取任务尾帧

尾帧指生成视频的最后一帧图片。仅当创建任务时传入 return_last_frame: true 才会额外产出；未开启该开关的任务不会生成尾帧。

接口

GET /v1/video/files/{taskId}/last-frame

路径参数

请求示例

curl 'https://api.topview.ai/v1/video/files/mvt-179197ccca01401a/last-frame' \
  -H 'Authorization: Bearer sk-你的topviewAPIKey' \
  --output last-frame.jpg

• 成功时直接返回尾帧图片二进制内容（Content-Type 为对应图片类型）。
• 该接口需任务计费完成后才可获取；创建时未开启 return_last_frame 或尾帧尚未就绪时，返回 404。
• 尾帧文件由 topview 平台代理返回，无需关心底层存储地址。

6. 模型列表

6.1 在售模型

上表模型均由本接口受理。两条线路（dreamina-*-max 与国内的 doubao-*-max）请求路径、请求体与响应结构完全一致，切换线路只需改 model 字段。差异只有两处：单价见 8.3 单价表；结果地址形式见 5.3——dreamina-*-max 交付平台长期地址，doubao-*-max 交付上游原始链接。

请区分带后缀与不带后缀的 doubao- 模型。 带 -max 后缀的四个模型由本接口受理；无后缀的 doubao-seedance-2-0-260128、doubao-seedance-2-0-fast-260128、doubao-seedance-2-0-mini-260615、doubao-seedance-2-5-260628 不由本接口受理，它们改由「Seedance（火山方舟中国区）」提供，路径 /cn/api/v3/contents/generations/tasks，协议是方舟 /api/v3（与本接口不同）。两者的上游账号、任务 ID 与价目相互独立，任务 ID 不能跨接口查询。

无后缀的 dreamina-seedance-2-0-260128 等 BytePlus 官方模型 ID 同样不属于本接口，请见「Seedance（方舟官方）」文档。

6.2 兼容别名（仍可调用，不建议新接入使用）

下列模型 ID 已停止售卖，但为兼容存量集成继续受理，平台会自动路由到同档位的 -max 模型，能力与单价不变。新接入请直接使用 6.1 的模型名。

使用别名时，任务创建与查询响应中的 model 仍原样返回你请求的模型 ID，无需改造解析逻辑。

无后缀的 dreamina-seedance-2-0-260128、dreamina-seedance-2-0-fast-260128、dreamina-seedance-2-0-mini-260615 不由本接口受理：它们是 BytePlus 官方模型 ID，改由「Seedance（方舟官方）」透传接口提供。仍走本接口的话请改用同档位的 -max 名，能力与单价不变。

7. 任务状态与轮询建议

建议：

• 轮询间隔：3~5 秒
• 建议超时时间：5~10 分钟
• 结果以 status=completed 且 outputs 非空为准

8. 计费说明

8.1 计费模式与时机

• 本视频中转使用账号通用/存量积分池，与 Topview 其他 API 共用余额；普通 API Key 可消费 type=0/1/14。
• 创建任务前检查通用可消费积分是否达到最低准入额度；这是准入检查，不会预占或预扣积分。
• 本通道采用后付费：任务成功后才扣费，不采用积分预占模式；因此创建后的实际费用可能高于创建时余额，但通用积分不会扣成负数，结算余额不足时会暂停交付结果。
• 计费在任务详情查询链路（status=completed）时触发，重复查询不会重复扣费（按 task.id + task_type 幂等）。
• 任务详情、任务列表和尾帧接口只有在计费完成后才交付视频结果。

8.2 计费公式

计费基于任务成功后返回的 usage.completion_tokens，按模型与分辨率的每百万 token 积分单价折算：

消耗积分
  = completion_tokens
  × 每百万 token 积分单价
  × 折扣率
  ÷ 1,000,000

• 结果保留 6 位小数；折扣率范围为 (0, 1]，最多 4 位小数。
• 每百万 token 积分单价由「模型 + 分辨率 + 是否带参考视频」共同决定，取值见 8.3 单价表。
• 是否带参考视频：创建请求 content 中包含 type=video_url 视为带参考视频，套用参考视频单价。

8.3 单价表

单价单位为「积分 / 每百万 completion_tokens」，标准 列表示未带参考视频，参考视频 列表示带参考视频。

说明：

• 标准版按分辨率分档计价；未命中 1080p / 4K 分档的分辨率（如 480p、720p）套用该模型默认单价。
• Fast / Mini 不区分分辨率，全分辨率统一单价。
• doubao-*-max 直接采用火山方舟中国区官网人民币刊例价，1 积分 = 1 元人民币，不做汇率折算。
• 单价可能随运营策略调整，请以对接时约定的最新版本为准。

8.4 折扣与错误码

• 运营可按 uid + model 配置中转折扣；未配置该模型、折扣停用或折扣异常时按原价计费。
• 你账号生效的模型折扣可在 Overview 页的 Model discounts 查看；单次调用实际应用的折扣见该任务的调用明细。
• 折扣只作用于本视频中转计费，不影响 Topview 其他模型和 API。
• 创建时未达到最低准入额度，或结算时明确返回通用积分不足时，接口返回 HTTP 402；为兼容现有客户端，错误码仍为 dreamina_credit_required。查询失败按服务错误返回，不会伪装成余额不足。

9. 错误响应与排障

9.1 常见 HTTP 状态

9.2 失败任务示例

{
  "task": {
    "id": "mvt-179197ccca01401a",
    "status": "failed",
    "model": "dreamina-seedance-2-0-260128-max",
    "outputs": [],
    "error": {
      "code": "failed",
      "message": "task failed"
    }
  }
}

10. 对接注意事项

1. 参考素材直接传公网可访问的 URL；asset://<素材Id> 与素材接口已下线，不再受理。
2. 请保存 task.id，便于后续查询与排障。
3. 结果获取支持轮询与 callback_url 异步回调两种方式，可同时使用（见 5.4 回调通知）；回调地址需公网可访问。
4. 本视频中转不再使用 type=16 专用积分，也不需要专用发放或扣费接口；账号应通过现有运营能力获得通用积分。
5. outputs[0] 请当作一次性地址使用、及时下载：doubao-*-max 交付的上游链接自任务完成起 24 小时有效且不可续期，dreamina-*-max 的平台地址也是签名地址。不要长期缓存 URL 本身——需要时重新查询同一任务，平台总会返回当前可用的地址（doubao-*-max 超过 24 小时后返回的是平台留档地址）。

11. Seedance 官方文档参考

模型能力由火山方舟 Seedance 提供，duration、resolution、ratio、参考图用法与提示词写法等参数语义与官方一致，可对照官方文档理解取值范围与效果：

• Seedance 官方接口文档：https://console.volcengine.com/ark/region:cn-beijing/docs/82379/1520757?lang=zh&projectName=default
• Seedance 官方使用教程：https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2607688?lang=zh

两个链接位于火山方舟控制台内，需登录火山引擎账号后访问。

本中转不透传官方协议：请求路径、请求体结构、鉴权方式、任务状态与计费口径一律以本文档为准，官方文档仅用于理解模型能力与参数取值。官方文档中出现的接口地址、模型 ID 与账号体系不适用于本通道。