对接文档

文档信息

• 适用环境：生产环境
• Base URL：https://api.topview.ai
• 路径前缀：/jimeng-cn/jimeng-agent/v1
• 模型：jimeng-agent-seedance20-mini、jimeng-agent-seedance20-fast、jimeng-agent-seedance20、jimeng-agent-seedance25
• 协议：即梦原生 {model, input} 任务协议与素材库协议
• 更新时间：2026-11-02

本通道沿用即梦原生的请求体、响应体和错误信封，用 Topview API Key 鉴权。和 Seedance 各通道相比有这些差别：路径带 /jimeng-cn/jimeng-agent/v1 前缀，请求体是 {model, input} 而不是方舟的 content 数组，按实际消耗的 token 计费，素材库是即梦原生接口。

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

1. 接口概览

POST /jimeng-cn/jimeng-agent/v1/tasks              创建视频生成任务
GET  /jimeng-cn/jimeng-agent/v1/tasks/{task_id}    查询任务

POST /jimeng-cn/jimeng-agent/v1/asset_group/create     创建素材组
POST /jimeng-cn/jimeng-agent/v1/asset_group/list       查询素材组列表
POST /jimeng-cn/jimeng-agent/v1/asset_group/get        查询素材组详情
POST /jimeng-cn/jimeng-agent/v1/asset_group/update     更新素材组
POST /jimeng-cn/jimeng-agent/v1/asset_group/delete     删除素材组
POST /jimeng-cn/jimeng-agent/v1/asset_group/reconcile  核对素材组
POST /jimeng-cn/jimeng-agent/v1/asset/create           从 URL 导入素材
POST /jimeng-cn/jimeng-agent/v1/asset/list             查询素材列表
POST /jimeng-cn/jimeng-agent/v1/asset/get              查询素材详情
POST /jimeng-cn/jimeng-agent/v1/asset/update           更新素材名称
POST /jimeng-cn/jimeng-agent/v1/asset/delete           删除素材

不提供任务列表和任务取消。GET /jimeng-cn/jimeng-agent/v1/tasks（不带任务 ID）返回 404 task_not_found。不提供真人认证。

2. 鉴权与通用约定

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

• 只接受 Topview API Key（sk-）。不要传 Topview-Uid。
• 请求与响应都是 JSON，UTF-8 编码。
• 创建成功时，data.task_id 是查询用的任务 ID。请按不透明字符串保存，不要校验前缀或长度。
• 响应头 X-Topview-Request-Id 也是平台任务 ID。创建失败时用它排查。
• 外层 code 为 "0" 只表示请求被受理，不代表视频生成成功。任务结果看 data.status。

3. 推荐调用流程

1. 创建任务，保存 data.task_id。
2. 用 task_id 查询，建议每 10–15 秒查一次。这是建议值，不是限流阈值，限流见第 8 节。
3. data.status 为 SUCCESS 时，从 data.video_artifact.url 下载。链接 24 小时有效，见 5.5。
4. data.status 为 FAILED 或 CANCELED 时停止轮询。

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

带了 callback_url 时，平台会在任务进入终态后回调你的公网地址。即梦上游本身不回调，回调由平台在终态时主动投递。回调不保证必达，请保留轮询。

4. 创建视频生成任务

4.1 接口

POST https://api.topview.ai/jimeng-cn/jimeng-agent/v1/tasks

4.2 模型

model 必填，填完整模型名。不传或传其他值返回 400 invalid_request，请求不会发出。

不传 duration 时默认 15 秒，不传 resolution 时默认 720P。表外的分辨率返回 400 invalid_request，不生成、不扣费。4K 与超过 15 秒的组合暂无模型支持。

4.3 请求字段

顶层只接受 model、input、callback_url。出现其他字段返回 400 invalid_request，message 为 unknown field: 字段名。

input 必须是 JSON 对象，只接受下表字段：

格式要求：

• 整数用 JSON 数字，布尔值用 true / false，不接受字符串代替。
• 默认值只在省略字段时生效。传 null 与省略相同；空字符串不会按默认值处理，不要用它代替省略。
• URL 列表始终是数组，元素是非空字符串；无素材时省略或传 []。
• 不支持本地 / 内网地址、Base64，以及需要登录、Cookie 或额外请求头才能下载的链接。
• 带临时签名的链接，签名要在任务处理期间一直有效，过期会导致任务失败。
• asset:// 只能引用本通道素材库里属于你的素材，见 6.6。

callback_url 可选，必须是公网 HTTP(S)，内网和回环地址会被拒绝。

4.4 参考素材要求

参考图片每张都要满足：

数量与时长上限：

任务受理后仍可能因素材规格、下载失败或内容审核失败，请检查查询结果的 status、err_code、err_msg。

4.5 视频编辑与延长

只有 jimeng-agent-seedance25 支持。ratio 只能是 adaptive，省略时自动补齐。

-1 只能是 JSON 数字。其他模型传 -1 或 task_type 返回 400 invalid_request。

两者都省略时，普通生成默认 15 秒，编辑跟随原视频时长。平台不会根据提示词改写任务类型：传了正数时长、但即梦把任务识别为编辑时，任务可能失败（err_code 为 20020）。确定是编辑时请显式传 task_type=edit。

4.6 请求示例

curl -X POST \
  'https://api.topview.ai/jimeng-cn/jimeng-agent/v1/tasks' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "jimeng-agent-seedance20-mini",
    "input": {
      "prompt": "海边日出，镜头缓慢推进，写实电影质感",
      "duration": 5,
      "resolution": "480P",
      "ratio": "16:9",
      "image_url_list": ["https://example.com/first.png"]
    },
    "callback_url": "https://example.com/jimeng/callback"
  }'

创建成功响应：

{
  "code": "0",
  "message": "success",
  "data": {
    "task_id": "示例任务ID",
    "status": "CREATED",
    "Jimeng_id": "7701186827004663065"
  }
}

• task_id 是平台任务 ID，查询只认它。
• Jimeng_id 是即梦任务 ID，用于排查和样片转成片（见 4.8）。字段名区分大小写，是字符串，请勿转成数字。创建时即梦还没分配时不返回，查询时再补上。

创建失败时：

{
  "code": "invalid_request",
  "message": "错误详情",
  "request_id": "排查标识"
}

失败响应不返回 data 字段。这类失败不扣费。错误码见第 9 节。

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

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

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

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

4.8 样片与样片转成片

只有 jimeng-agent-seedance25 支持，分两步，两步各是一条独立任务、分别计费。

第一步，生成样片：在 input 里加 "draft": true。样片固定 480P，resolution 省略或传 480P；传其他分辨率返回 400 invalid_request。

{
  "model": "jimeng-agent-seedance25",
  "input": {
    "prompt": "黄昏的海边，一只海鸥掠过镜头",
    "ratio": "16:9",
    "draft": true
  }
}

第二步，样片 SUCCESS 后转成片：input 只放 draft_task_id，值为样片的 Jimeng_id（不是平台 task_id）。提示词、素材、时长、比例、种子、声音都沿用样片，不能再传；成片固定 1080P。

{
  "model": "jimeng-agent-seedance25",
  "input": {
    "draft_task_id": "7701186827004663065"
  }
}

draft_task_id 只能引用本账号已成功的样片任务。引用别人的样片、未成功的样片或普通任务，返回 400 invalid_request，不生成、不扣费。callback_url 照常可传。

5. 查询任务

5.1 接口

GET https://api.topview.ai/jimeng-cn/jimeng-agent/v1/tasks/{task_id}

{task_id} 是创建响应里的 data.task_id。Jimeng_id 和其他通道的任务 ID 在这里返回 404。

5.2 请求示例

curl -X GET \
  'https://api.topview.ai/jimeng-cn/jimeng-agent/v1/tasks/示例任务ID' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey'

5.3 任务状态

5.4 响应示例

成功：

{
  "code": "0",
  "message": "success",
  "data": {
    "task_id": "示例任务ID",
    "status": "SUCCESS",
    "Jimeng_id": "7701186827004663065",
    "video_artifact": {
      "url": "https://示例地址/result.mp4",
      "cover_url": "https://示例地址/cover.jpg",
      "duration": 5,
      "width": 864,
      "height": 496
    },
    "start_at": 1793600000,
    "elapsed_seconds": 180,
    "consume_credits": 0.255
  }
}

失败：

{
  "code": "0",
  "message": "success",
  "data": {
    "task_id": "示例任务ID",
    "status": "FAILED",
    "Jimeng_id": "7701186827004663065",
    "err_code": "20020",
    "err_msg": "下游任务执行失败"
  }
}

consume_credits 偶尔会比 SUCCESS 晚出现，之后再查会补上。响应不返回 model 和 token 用量，需要关联时自行保存 model 与 task_id。

平台自己判定的失败使用下面的 err_code：

失败和取消的任务不扣费。

5.5 时效

• video_artifact 里的视频、封面和尾帧链接自生成起 24 小时有效，平台不转存、不重新签发。过期后查询仍返回原来的 SUCCESS 结果，但链接已无法下载。收到 SUCCESS 后请尽快下载到自己的存储。
• 任务记录保留 7 天。超过保留期仍未结束的任务按 FAILED 收尾，err_code 为 task_not_found。

5.6 任务不存在

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

{
  "code": "task_not_found",
  "message": "The specified resource `被查询的ID` is not found.",
  "request_id": "排查标识"
}

5.7 回调

创建时传了 callback_url，平台在任务进入 SUCCESS、FAILED 或 CANCELED 后向该地址 POST 一次，回调体与查询响应相同。投递失败会重试，但不保证必达，请保留轮询。回调里没有 consume_credits 时，说明投递时扣费还没完成，之后查询可以看到。

6. 素材库

6.1 使用流程与归属

创建素材组 → 从公网 HTTP(S) URL 导入图片 / 视频 / 音频 → 保存素材 Id → 在生成任务里用 asset://素材Id 引用。普通 URL 也可以直接用于生成，不必先导入。

• 全部接口都是 POST + JSON，鉴权同第 2 节。字段区分大小写，直接放在请求体顶层，不套 input。只接受各接口列出的字段。
• 素材库按 Topview 账号隔离。其他账号的素材组和素材，即使知道 ID 也只会收到和「不存在」完全相同的 20030 / 20031。
• 本通道的素材与「Seedance（火山方舟中国区）」等通道的素材互不相通，不能互相引用。
• 素材管理不扣积分。素材组数、素材数和素材接口并发由运营按账号开通，未开通时所有素材接口返回 429 asset_quota_exceeded。

成功响应：

{
  "code": "0",
  "message": "success",
  "request_id": "排查标识",
  "data": { "Id": "group-example" }
}

创建与更新通常只返回 data.Id，完整对象通过详情接口获取。失败时不返回 data 字段，错误码见 6.7。

6.2 对象字段

素材组：

素材：

素材导入同步完成校验与审核后才返回 ID，不需要轮询状态。

6.3 素材组接口

创建 asset_group/create

curl -X POST \
  'https://api.topview.ai/jimeng-cn/jimeng-agent/v1/asset_group/create' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{ "Name": "产品素材", "Description": "产品短片参考图", "GroupType": "AIGC" }'

详情 asset_group/get：{ "Id": "group-example" }。data 为素材组对象，不含组内素材。

更新 asset_group/update：Id 必填；Name、Description 可选，省略表示不改，Description 传空字符串表示清空。不能修改 GroupType。

删除 asset_group/delete：{ "Id": "group-example" }，成功时 data 为 {}。会删除组内全部素材，已受理的生成任务不受影响。

列表 asset_group/list：参数见 6.5。

核对 asset_group/reconcile：见 6.9。

6.4 素材接口

导入 asset/create

curl -X POST \
  'https://api.topview.ai/jimeng-cn/jimeng-agent/v1/asset/create' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "group-example",
    "URL": "https://example.com/product.jpg",
    "AssetType": "Image",
    "Name": "产品正面"
  }'

导入没有幂等字段。超时或返回 upstream_result_unknown 时不要自动重试，先按 6.9 核对原组。

导入规格（按下载后的媒体校验，不看 URL 后缀）：

详情 asset/get：{ "Id": "asset-example" }。预览链接过期时用它刷新 URL。

更新 asset/update：Id 必填，只能改 Name（传空字符串表示清空）。不能改 URL、AssetType、GroupId，换文件请重新导入。

删除 asset/delete：{ "Id": "asset-example" }，成功时 data 为 {}。

列表 asset/list：参数见 6.5。

6.5 列表筛选与分页

• 页码模式与游标模式不能混用；全部省略时按游标模式返回前 10 条。
• 单页最多返回 50 条，实际条数以响应为准。
• 页码模式中，组列表 PageNumber × PageSize 不超过 10,000，素材列表不超过 20,000；更深的数据用游标模式。
• 页码模式返回 Items、PageNumber、PageSize、TotalCount；游标模式返回 Items，有下一页时返回 NextToken。
• NextToken 24 小时有效，续页时用户、接口、筛选、排序和每页条数必须与首页一致，原样回传，不要解析或修改。失效时返回 10001，从首页重查。

{ "Filter": { "GroupType": "AIGC", "GroupIds": ["group-example"] }, "MaxResults": 20 }

6.6 在生成任务中引用素材

引用格式是 asset://素材Id，Id 必须是导入返回的完整字符串，例如 asset://asset-example。素材组 ID 不能代替素材 ID。

同一列表可以混合 URL 与素材引用，顺序不变，数量上限不变。引用的素材必须属于当前账号且状态为 Active，否则创建返回 400 invalid_asset_reference，不扣费。

6.7 素材错误码

6.8 Unavailable 状态

平台核对时发现上游素材组或素材已无法访问，会标记为不可用：素材 Status 为 Unavailable，素材组返回 Unavailable: true。

• 这是可恢复状态，不等于删除。记录和归属都保留，列表、详情、更新、删除照常可用。
• 不可用期间不能在生成任务中引用，引用会返回 invalid_asset_reference。
• 上游恢复后，调用详情接口或 6.9 的核对接口即可恢复为 Active。

6.9 核对素材组

asset_group/reconcile 用于导入超时后找回已导入但未登记的素材。只能核对自己的组。

{ "Id": "group-example", "PageNumber": 1 }

PageNumber 默认 1，取 1–1000。响应：

{
  "code": "0",
  "message": "success",
  "request_id": "排查标识",
  "data": { "Recovered": 2, "Checked": 20, "Unavailable": 1, "NextPage": 2 }
}

有 NextPage 时用同一 Id 继续。失败可以重试当前页，不要重新导入。

7. 计费规则

原价积分 = actual_token ÷ 1,000,000 × 10
最终扣费积分 = 原价积分 × 账号折扣率

• actual_token 是即梦在任务完成后返回的实际消耗 token 数。平台按它原样计费，不在响应里返回；扣费结果在查询响应的 consume_credits 里，见 5.4。
• 四个模型单价相同，都是 10 积分 / 百万 token，即 100,000 token = 1 积分。不同模型、分辨率、时长以及是否带参考视频的差别，已经体现在 actual_token 里。
• 参考：jimeng-agent-seedance20-mini、480P、5 秒、不带参考视频，实测 actual_token 为 25,500，扣 0.255 积分（未计折扣）。其他组合以实际 actual_token 为准。
• 保留 6 位小数，四舍五入。1 平台积分 = 1 元人民币。没配折扣时折扣率为 1。
• actual_token 为 0 时不扣费。
• 创建时不预扣、不冻结积分，只在 SUCCESS 后按实际用量扣一次，扣上费才交付：扣上才返回 SUCCESS 与视频地址、发送成功回调，扣费未完成时查询仍返回 RUNNING。FAILED、CANCELED 和创建失败不扣费。
• 创建前检查余额：低于 20 积分时返回 HTTP 402 insufficient_balance。这只是门槛，不扣、不冻结。
• 扣费时余额不足：查询返回 HTTP 402 insufficient_balance，不返回视频。充值后再查询即补扣并交付，成功回调也在扣上费后发送。
• 账号折扣在 Overview 的 Model discounts 查看。未列出的模型按标准价。
• 每条任务的扣费可在控制台 Usage 页查看和导出，页面显示 4 位小数，以 consume_credits 为准。

8. 并发与限流

• 本通道的视频并发单独计算，必须由运营开通。没有开通时创建返回 HTTP 429 rate_limit_exceeded。任务进入终态即释放。
• 并发用满返回 HTTP 429 rate_limit_exceeded。
• 查询按团队限流，每个团队每秒最多 200 次，超出返回 HTTP 429 rate_limit_exceeded。
• 余额低于 20 积分时创建返回 HTTP 402 insufficient_balance，见第 7 节。
• 素材接口的额度与并发见 6.1 和 6.7。

9. 错误响应

任务接口失败时的信封：

{
  "code": "错误码",
  "message": "错误详情",
  "request_id": "排查标识"
}

失败响应不返回 data 字段，请先判断 code。

请求失败的 code 与查询结果里的 data.err_code 是两回事：前者表示这次请求没成功，后者表示任务执行失败。

排查时提供 task_id、X-Topview-Request-Id 或 request_id。不要提供 API Key。

10. 接入注意事项

• 路径必须带 /jimeng-cn/jimeng-agent/v1，model 必填。
• 外层 code="0" 不代表视频成功，看 data.status。
• 查询只用平台 task_id；Jimeng_id 用于排查和样片转成片的 draft_task_id。
• 视频链接 24 小时有效，SUCCESS 后尽快下载。
• 不支持真人认证。
• 创建返回 502 不要直接重建，先按 4.7 查询。
• 400、401、402、404 不要自动重试。429 用指数退避。