> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapon.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# TopView T1 CN

> 通过 Kapon 原生任务接口调用 TopView T1 CN，完成视频生成、查询、回调与按秒计费。

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

## 接口与认证

```bash theme={null}
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。

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

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

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

## 快速开始

### 1. 创建文生视频任务

```bash theme={null}
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。

```json theme={null}
{
  "id": "example-task-id"
}
```

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

### 2. 查询任务

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

```bash theme={null}
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 秒左右查询一次。成功响应的主要字段如下。

```json theme={null}
{
  "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`，包括签名参数。

```bash theme={null}
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 均为占位符，使用前替换为你自己的公网素材直链。

```json theme={null}
{
  "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` 数组中放入所需素材，并在提示词中描述素材用途。

```json theme={null}
{
  "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`。

```json theme={null}
{
  "callback_url": "https://example.com/webhooks/topview"
}
```

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

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

## 用量与计费

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` 时，平台保留待核对计量，补齐后完成结算；视频仍按查询结果正常交付。更多说明见[计费对账](https://docs.kapon.cloud/guide/billing-reconciliation.md)。

## 错误与恢复

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 的读取方式见[请求追踪](https://docs.kapon.cloud/guide/request-id.md)。

## 相关文档

* [API 认证](https://docs.kapon.cloud/guide/authentication.md)
* [错误码与响应说明](https://docs.kapon.cloud/guide/errors.md)
* [计费对账](https://docs.kapon.cloud/guide/billing-reconciliation.md)
* [TopView T1 CN 官方接口文档](https://www.topview.ai/partner-console/docs?model=topview-t1-cn)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.