# 图片与视频异步 API 接入指南（交给 AI 编程助手）

> 本文件适用于本平台的图片、视频生成 API。把它交给 AI 编程助手，并让它在你的项目中完成接入。本文中的模型值、令牌和回调域名都是占位符，不要直接用于生产。

## 给 AI 编程助手的任务

请先阅读当前项目，判断它是纯浏览器、桌面/移动客户端，还是有自己的服务端，然后按下面的协议实现图片和/或视频生成。复用项目已有的网络请求、鉴权和状态管理方式；完成创建、等待终态、获取结果、失败提示与必要的测试。不要猜测真实模型值、API 令牌或回调域名；如果项目配置中没有，请向用户索取。不要把 `sk-` 令牌写入源码、日志或浏览器发布包。

用户只需要提供：

- API Base URL，例如 `https://api.aik.cc`（其他站点请换成实际 API 域名）；
- 由平台签发的 `sk-...` 令牌；
- 要使用的图片或视频模型值，以及生成所需参数；
- 若选择服务端回调，还需一个可从公网访问的 HTTPS 回调地址。

所有示例都以 `API_BASE_URL=https://api.aik.cc` 为例。请求头为 `Authorization: Bearer sk-你的令牌`。以实际平台支持的模型值替换示例中的 `video-model-id` 和 `image-model-id`。

## 选择接入方式

| 项目形态 | 完成通知 | 状态兜底 |
| --- | --- | --- |
| 有自己的服务端 | 创建视频任务时传 `callbackUrl`，图片任务传 `callback_url`；服务端接收 Webhook，按事件 ID 去重，再用带令牌的状态查询核实结果；需要时由自己的服务端通知客户端 | 每 60 秒查询一次，直到终态 |
| 纯桌面或移动客户端 | 不传回调字段；对外 API 没有可用 API 令牌直接订阅的消息接口 | 每 60 秒查询一次；回到前台或网络恢复后立即查一次 |
| 纯浏览器前端 | 应由自己的服务端代理 API 请求并保管令牌；不要把长期 `sk-` 令牌放进网页代码 | 按上面有服务端的方式接入 |

获得 `completed`/`failed`（视频）或 `SUCCESS`/`FAILURE`（图片）后停止查询。多个任务分别保存任务 ID 和状态。回调可能重复或丢失，所以无论哪种方式都保留状态查询。用户查询频率不会加快平台对上游的生成或状态轮询；过密查询只会增加 API 负载。

## 视频：创建任务

```http
POST /v1/videos
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

```json
{
  "model": "video-model-id",
  "prompt": "黄昏海边，一架纸飞机从镜头前飞过",
  "seconds": 5,
  "aspectRatio": "16:9",
  "resolution": "720p",
  "generateAudio": true,
  "negativePrompt": "模糊、闪烁"
}
```

`generateAudio` 默认 `true`，显式传 `false` 关闭音频。支持双画质的线路可传 `"videoQualityMode": "native"`（原生画质）或 `"videoQualityMode": "enhanced"`（画质增强）；不传时使用线路默认画质。`resolution` 是最终输出分辨率；480p 不支持增强模式。

有服务端回调时，在请求体中增加 `"callbackUrl": "https://your-service.example/video-callback"`。`callbackUrl` 也适用于 `POST /v1/video/generations` 和 `POST /v1/videos/{video_id}/remix`，JSON 与 multipart 均支持；平台保存它，不转发供应商。回调地址只能是公网 HTTPS。

创建响应中的 `id` 是后续查询所需的视频任务 ID。任务创建后通常返回 `queued`；不要把创建响应当作最终视频结果。

```json
{
  "id": "task_xxx",
  "object": "video",
  "model": "video-model-id",
  "status": "queued",
  "progress": 0
}
```

同一模型有多条线路时，可用 `GET /api/platform/model-lines?model=video-model-id` 查询可用线路 ID；创建时可在 JSON 请求体中传 `"lineId": 12`。不传则由平台按当前策略选择。线路 ID 是正整数，不是模型值，也不是任务 ID。

## 视频：查询终态和内容

```http
GET /v1/videos/{task_id}
Authorization: Bearer sk-你的令牌
```

`status` 可能是 `queued`、`in_progress`、`completed`、`failed` 或 `unknown`。只有 `completed` 才读取结果。最终视频 URL 优先读取最外层 `url`，也可从 `metadata.url`、`metadata.video_url` 或 `metadata.videos[].url` 获取。执行视频增强且保存了原片时，最外层 `native_video_url` 是增强前已归档视频；原片可能是 480P 或 720P，临时签名链接过期后重新查询。`failed` 时显示 `error.message`。不要把 `unknown` 或一次网络错误当作任务失败。

```json
{
  "id": "task_xxx",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "url": "https://example.com/result.mp4",
  "native_video_url": "https://example.com/original.mp4",
  "metadata": {
    "url": "https://example.com/result.mp4",
    "video_url": "https://example.com/result.mp4",
    "videos": [{ "url": "https://example.com/result.mp4" }]
  }
}
```

若需要通过平台代理读取文件，仅在确认 `completed` 后调用 `GET /v1/videos/{task_id}/content`。该接口传输视频文件，**不能用于轮询状态**。媒体下载或完成后的归档可能依赖上游和对象存储可用性。

## 视频：服务端回调

平台在成功或失败后向 `callbackUrl` 发送 JSON `POST`，请求体与 `GET /v1/videos/{task_id}` 的终态对象同形。请求头 `X-Video-Event-Id` 形如 `video:task_xxx:SUCCESS` 或 `video:task_xxx:FAILURE`，同一终态重试时保持不变。接收方返回任意 HTTP 2xx 即视为收到；否则最多尝试 5 次并记录最终失败。

回调**没有签名或密钥**。接收端应先检查任务 ID 是否属于自己创建的任务，按事件 ID 去重，然后使用自己保存的 API 令牌调用 `GET /v1/videos/{task_id}` 核实终态。不要仅凭回调请求体结算或向用户展示结果。回调处理应快速返回 2xx；耗时操作放入自己的后台任务。平台不跟随回调地址重定向。

## 图片：创建异步任务

```http
POST /v1/images/generations
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

```json
{
  "model": "image-model-id",
  "prompt": "未来城市夜景，电影感"
}
```

有服务端回调时，可在 JSON 请求中加入 `"callback_url": "https://your-service.example/image-callback"`。异步创建可能返回 HTTP 202，响应中包含 `task_id`、`status`、`client_request_id`；部分图片模型也可能直接返回最终图片数据，须先判断响应结构。

```json
{
  "task_id": "task_image_xxx",
  "status": "QUEUED",
  "client_request_id": "request_xxx"
}
```

## 图片：查询与回调

```http
GET /v1/images/tasks/{task_id}
Authorization: Bearer sk-你的令牌
```

图片任务的 `status` 使用大写值，例如 `QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。成功时读取响应中的 `data.data[].url` 或 `result_url`；失败时读取 `fail_reason`。任务 ID 暂未拿到但有 `client_request_id` 时，可用 `GET /v1/images/tasks?client_request_id={client_request_id}` 找回。

图片回调是 JSON `POST`，只包含 `task_id`、`status`、`client_request_id` 等通知字段，不包含完整图片；头部 `X-Image-Event-Id` 形如 `image:task_image_xxx:SUCCESS`。按事件 ID 去重并返回 2xx 后，调用带令牌的图片任务查询接口获取最终结果。图片回调也没有签名或密钥，失败最多尝试 5 次。

## 查询与错误处理规则

1. 存储创建响应的任务 ID，避免页面或进程恢复后丢失正在处理的任务。
2. 每 60 秒对非终态任务查询一次；服务端收到回调后立即查询一次，纯客户端回到前台或网络恢复后可立即查询一次。
3. HTTP 超时、网络错误、`429` 或 `5xx` 表示本次查询未成功，不等于任务失败；稍后重试，不要重新创建同一任务。
4. 只有明确的终态 `completed`/`failed` 或 `SUCCESS`/`FAILURE` 才结束等待。显示错误时保留任务 ID，方便排查。
5. 下载图片或视频前检查结果 URL；临时签名 URL 过期时重新查询任务，以取得新 URL。
6. 不要把 `GET /v1/videos/{task_id}/content` 当状态接口，也不要每秒查询状态。

接入完成后，请用一个成功任务、一个失败任务和一次网络中断验证状态恢复；有回调服务端时还需验证重复回调不会重复处理。