TopView T1 CN

TopView T1 CN 支持文生视频、单图首帧、首尾帧及图片、视频、音频参考输入。使用有 topview-t1-cn 权限的 Kapon 模型调用 Token 创建任务，查询成功后下载视频。

接口与认证

export BASE_URL="https://models.kapon.cloud"
export TOKEN="你的 Kapon 模型调用 Token"

功能	HTTP 方法与路径
创建视频任务	`POST /topview-t1-cn/api/v3/contents/generations/tasks`
查询视频任务	`GET /topview-t1-cn/api/v3/contents/generations/tasks/{id}`

所有请求使用 Kapon 模型调用 Token 进行 Bearer 认证，创建请求使用 JSON。

Authorization: Bearer <TOKEN>
Content-Type: application/json

请求体中的 model 填写 topview-t1-cn，填写其他模型名会返回 400。Kapon 原样转发请求体，并保留本接口的原始任务 ID、响应字段、HTTP 状态及 X-Topview-Request-Id 响应头。创建后保存 id 用于查询，任务 ID 按不透明字符串处理。

TopView T1 CN 任务只能通过本页的查询接口查询，不会出现在 /v1/videos 等其他视频接口中。

快速开始

1. 创建文生视频任务

curl -sS -D create.headers -o create.json \
  -X POST "$BASE_URL/topview-t1-cn/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topview-t1-cn",
    "content": [
      {"type": "text", "text": "电影级镜头，一艘飞船穿过深紫色星云"}
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5
  }'

创建响应保存在 create.json，HTTP 状态与响应头保存在 create.headers。创建成功时返回任务 ID。

{
  "id": "example-task-id"
}

创建成功表示任务已受理。继续查询，直到任务到达终态。

2. 查询任务

将 TASK_ID 替换为创建响应中的实际 id。

export TASK_ID="example-task-id"

curl -sS "$BASE_URL/topview-t1-cn/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

建议每 15 秒左右查询一次。成功响应的主要字段如下。

{
  "id": "example-task-id",
  "model": "topview-t1-cn",
  "status": "succeeded",
  "content": {
    "video_url": "https://media.example.com/video.mp4?signature=example"
  },
  "usage": {
    "total_seconds": 5
  },
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5
}

状态	含义与处理
`queued`	任务排队中，继续查询
`running`	正在生成，或等待交付与结算完成，继续查询
`succeeded`	视频已可交付，从 `content.video_url` 获取结果
`failed`	任务失败，读取 `error` 后停止轮询

3. 下载视频

将 VIDEO_URL 替换为本次成功查询返回的完整 content.video_url，包括签名参数。

export VIDEO_URL="查询返回的完整视频 URL"
curl -fL "$VIDEO_URL" -o output.mp4

video_url 会过期，每次查询都会向原渠道重新取得当前签名地址。任务记录保留 7 天，请在成功后及时下载到自己的存储。旧地址失效时，使用原任务 ID 重新查询并下载。

输入素材与参数

通用参数

字段	必填	取值与默认行为
`model`	是	`topview-t1-cn`
`content`	是	内容数组，包含文本或媒体输入
`resolution`	否	`720p`、`1080p`，默认 `720p`
`ratio`	否	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`，默认 `adaptive`
`duration`	否	4–30 的整数秒数，或 `-1` 自动时长，默认 5
`generate_audio`	否	布尔值，默认 `true`；设为 `false` 生成无声视频
`callback_url`	否	公网 HTTP(S) 回调地址，任务终态后接收结果

content[] 使用以下结构。

`type`	内容字段	用途
`text`	`text`	文本提示词，多段文本按顺序拼接
`image_url`	`image_url.url`	首帧、尾帧或参考图片，通过 `role` 指定
`video_url`	`video_url.url`	参考视频
`audio_url`	`audio_url.url`	参考音频

素材地址使用公网可访问的 HTTP(S) URL，图片最多 30 张，视频最多 10 个，音频最多 10 个。完整 JSON 请求体上限为 10 MB。参数校验和默认值由 TopView 执行，Kapon 不改写请求参数。

单图与首尾帧

图片的 role 可取以下值。

`role`	含义
`first_frame`	首帧，最多一张
`last_frame`	尾帧，最多一张，须同时提供首帧
`reference_image`	参考图片

只有一张图片且没有其他参考素材时，省略 role 会按首帧处理；其他情况下省略图片 role 会按参考图处理。下面是单图首帧请求体，提交到同一个创建接口。示例媒体 URL 均为占位符，使用前替换为你自己的公网素材直链。

{
  "model": "topview-t1-cn",
  "content": [
    {"type": "text", "text": "保留参考图中的红色帆船和蓝色灯塔，帆船向右缓慢航行"},
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {"url": "https://example.com/first-frame.png"}
    }
  ],
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": 4
}

有首帧时，视频画幅跟随首帧图片，ratio 按 adaptive 处理。需要固定比例时，先将首帧裁成目标比例。使用首尾帧时，在 content 中增加一项 role=last_frame 的图片。

图片、视频和音频参考

在同一个 content 数组中放入所需素材，并在提示词中描述素材用途。

{
  "model": "topview-t1-cn",
  "content": [
    {"type": "text", "text": "参考图片中的产品外观、视频的镜头运动和音频的节奏，生成产品短片"},
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "https://example.com/product.png"}
    },
    {
      "type": "video_url",
      "video_url": {"url": "https://example.com/motion.mp4"}
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://example.com/rhythm.wav"}
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

content 中包含 video_url 时，任务使用含视频输入的计费档，详见下文「用量与计费」。

自动时长与提示词参数

设置 "duration": -1 后，由模型决定生成时长。查询中的 duration=-1 表示请求采用自动模式，实际片长以视频为准，计费秒数以 usage.total_seconds 为准。 resolution、ratio 也可以写在提示词中，例如 一艘飞船穿过星云 --resolution 1080p --ratio 9:16。Kapon 原样转发，默认值及冲突处理由 TopView 决定。为使请求规格明确，建议同一字段选择一种写法。查询返回的 resolution、ratio、duration 用于回显请求字段；请求未传入的字段可能不返回。真实像素、画幅和片长以下载视频的媒体属性为准。

参数边界

本接口的素材输入使用公网 URL，asset://、内联 Base64 和 draft_task 会返回参数错误。seed、camera_fixed、watermark 等其他方舟字段按 TopView 规则忽略，传入这些字段不会获得对应控制效果。任务列表、删除、取消及素材库接口均未提供。

回调

需要接收终态通知时，在创建请求顶层增加 callback_url。

{
  "callback_url": "https://example.com/webhooks/topview"
}

该片段应与创建参数合并使用。回调地址须为公网 HTTP(S)，内网和回环地址会被拒绝。TopView 在任务终态后直接投递，回调体与查询结果使用相同结构，通过 id 关联任务。

回调不保证必达，应保留轮询作为结果获取方式。签名视频地址可能随查询时间变化，获取视频时使用当前查询返回的地址。

用量与计费

TopView T1 CN 按计费秒数收费，基准价格分为四档。

清晰度	不含视频输入	含视频输入
720p	¥1.51 / 计费秒	¥0.91 / 计费秒
1080p	¥3.74 / 计费秒	¥2.24 / 计费秒

视频输入档：content 中包含 type=video_url 时选择含视频输入档，否则为不含视频输入档。
清晰度档：以成功查询返回的 resolution 为准；未返回时使用请求中的 resolution，请求也未填写时按 720p 计费。
金额：usage.total_seconds × 任务创建时冻结的适用客户秒价。上表为基准价格，账户折扣或专属价格体现在适用客户秒价中，具体以控制台和消费记录为准。创建后调整价格不影响已创建的任务。

例如，无视频输入的 720p 任务返回 usage.total_seconds=5，基准金额为 5 × 1.51 = ¥7.55；若适用八折，金额为 ¥6.04。含视频输入的 720p 任务返回 total_seconds=7，基准金额为 7 × 0.91 = ¥6.37。计费数量采用查询返回的 usage.total_seconds，保留其数值。含视频输入时，该数量还包含输入视频的计费部分。请求时长、成片探测长度和计费秒数需分别理解，例如请求 4 秒、成片略长于 4 秒时，按返回的计费数量计算。创建任务时平台会先预留一部分额度，任务结束后按实际金额结算。成功任务结算一次，确定失败的任务不计费。成功响应暂缺有效用量，或在提示词中用 --resolution 指定清晰度但成功响应未返回 resolution 时，平台保留待核对计量，补齐后完成结算；视频仍按查询结果正常交付。更多说明见计费对账。

错误与恢复

TopView 返回的 HTTP 状态和错误体按本接口透传，Kapon 自身 Token、权限与额度检查沿用平台规则。

创建返回 5xx

创建请求返回 5xx 时，任务可能已经提交，结果仍在核对，不要直接重新 POST。按响应情况处理：

创建响应	后续处理
响应体中带有 `id`	使用该 `id` 调用原查询接口
响应体没有 `id`，但响应头带有 `X-Topview-Request-Id`	将该响应头的值作为任务 ID，调用原查询接口
既没有 `id` 也没有 `X-Topview-Request-Id`（例如 502 `upstream request failed`）	无法确认是否已提交；保存响应与 `X-Oneapi-Request-Id`，联系平台核查
503，`channel unavailable`、`TopView pricing unavailable` 或 `submission receipt storage unavailable`	平台在提交前已拒绝，任务未提交，可稍后重试

使用恢复 ID 查询时，可能出现以下结果：

查询结果	后续处理
返回正常任务对象	继续查询该任务直到终态
HTTP 503，提示 `task creation result is still being reconciled`	等待后继续查询原任务
`failed`，提示 `task creation result could not be confirmed`	该任务已放弃生成，可重新创建
返回与创建时相同的确定拒绝错误	按原错误处理，修正后重新创建

官方异常核对窗口最长约 60 分钟。仅因查询暂时失败或短时间没有结果就再次 POST，可能造成重复生成与计费。

其他常见情况

HTTP 状态或任务结果	处理方式
400	按 `error.code/message` 检查模型名、参数和素材 URL，修正后提交
401	检查 Kapon 模型调用 Token；令牌有效时联系平台核查鉴权状态
403	检查当前 Token 的模型权限与访问范围
创建返回 402	核查 Kapon 可用额度；账户余额低于 ¥10 时，同一时间只能有 1 个进行中的异步任务，等待已有任务结束或充值后再提交；额度正常时联系平台核查资源状态
查询返回 402 / `AccountOverdueError`	任务可能已生成，交付尚未完成；保留原任务 ID 并联系平台核查，处理完成后继续查询
404	检查 ID、任务归属（只能查询当前账户创建的任务）及 7 天保留期
429	降低提交或查询频率，使用退避后重试
查询 5xx/503	保留原任务 ID，退避后继续查询；客户端保留最后一次可信任务状态，避免将临时查询错误视为 `failed`
`status=failed`	读取任务 `error`，按原因处理后决定是否重新创建

排查时记录任务 id、X-Topview-Request-Id 和 Kapon 的 X-Oneapi-Request-Id。提交工单可提供这些标识及错误响应，密钥应通过平台的安全配置入口管理。平台请求 ID 的读取方式见请求追踪。

视频生成

接口与认证

快速开始

1. 创建文生视频任务

2. 查询任务

3. 下载视频

输入素材与参数

通用参数

单图与首尾帧

图片、视频和音频参考

自动时长与提示词参数

参数边界

回调

用量与计费

错误与恢复

创建返回 5xx

其他常见情况

相关文档