# 用户侧统一视频接口文档

**接口版本**：Video API v1  
**文档版本**：2026-08-19  
**适用对象**：中转站用户、插件和第三方客户端

## 1. 用户只需要使用这一套接口

所有公开视频模型都使用同一套用户侧接口，不需要区分渠道、适配器或上游平台。

| 操作 | 方法 | 地址 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询任务 | `GET` | `/v1/videos/{task_id}` |
| 获取视频 | `GET` | `/v1/videos/{task_id}/content` |

完整地址示例：`https://api.aicopy.top/v1/videos`

请求头：

```http
Authorization: Bearer <你的中转令牌>
Content-Type: application/json
Accept: application/json
```

旧版 `/v1/video/generations` 仍兼容，但新客户端统一使用 `/v1/videos`。

## 2. 统一创建请求

最小请求：

```json
{
  "model": "公开模型名",
  "prompt": "海边日落，镜头缓慢推进"
}
```

通用完整请求：

```json
{
  "model": "公开模型名",
  "prompt": "保持人物身份和服装一致，动作自然连续",
  "seconds": 8,
  "size": "1280x720",
  "input_reference": {"url": "https://cdn.example.com/first.jpg"}
}
```

这是通用基础请求，不代表每个模型都支持下面的扩展字段。仅在模型能力明确支持时，才添加 `generate_audio`、`fps`、`seed`、参考视频、参考音频、水印等字段。`generate_audio` 默认不要自动发送 `true`。

### 2.1 字段说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 控制台当前提供的公开模型名 |
| `prompt` | string | 是 | 视频内容描述 |
| `seconds` | integer/string | 否 | 生成时长，按秒传入 |
| `size` | string | 否 | `宽x高`，如 `1280x720` |
| `input_reference` | object/string | 否 | 单首帧参考图；支持 `url`、`image_url`、`file_id` |
| `extra.aspect_ratio` | string | 否 | 画幅，如 `16:9`、`9:16`、`1:1` |
| `extra.resolution` | string | 否 | `480p`、`720p`、`1080p`、`2k` 等模型支持的档位 |
| `extra.fps` | integer | 否 | 仅在上游模型支持时传入 |
| `extra.reference_images` | array | 否 | 多参考图、首尾帧图片 |
| `extra.reference_videos` | array | 否 | 参考视频 |
| `extra.reference_audios` | array | 否 | 参考音频 |
| `extra.watermark` | boolean | 否 | 是否添加水印 |
| `extra.generate_audio` | boolean | 否 | 是否生成音频；仅音频能力已确认的模型可用，默认不要发送 |
| `extra.seed` | integer | 否 | 随机种子 |
| `extra.negative_prompt` | string | 否 | 反向提示词 |
| `extra.request_id` | string | 否 | 用户自定义追踪号 |

### 2.1.1 等价类型兼容

统一入口会先做类型归一化，再交给具体适配器。以下写法语义相同：

- `seconds`、`duration`、`fps`：数字或数字字符串；例如 `15` 和 `"15"`。
- `size`、`resolution`、`ratio`、`aspect_ratio`：字符串，或只包含 `value` 的对象包装。
- `image`、`input_reference`：字符串，或包含 `url`、`image_url`、`file_id` 的对象。
- `images`、`videos`、`audios` 及对应的 `*_references`：数组元素可以是 URL 字符串，也可以是包含对应 URL 字段的对象。
- `reference_images`、`reference_videos`、`reference_audios`：数组元素可以是字符串或对象；对象中的 `role` 会保留。

只对上述语义明确的等价形式做转换。提示词、模式对象、镜头控制、遮罩轨迹等真正结构化字段不会被强行转换；类型不符合时返回明确的参数错误。

未传的字段由对应上游模型使用默认值。中转会把统一字段转换为对应上游字段；模型不支持的字段由上游返回实际错误，不会改成另一个参数静默提交。

Channel 280 的 `ai-video-v1`（公开模型 `sd-720满血-900（不售后）`）不支持生成音频，请勿发送 `extra.generate_audio:true`。

### 2.2 参考素材

```json
{
  "extra": {
    "reference_images": [
      {"url": "https://cdn.example.com/first.jpg", "role": "first_frame"},
      {"url": "https://cdn.example.com/last.jpg", "role": "last_frame"}
    ],
    "reference_videos": [{"url": "https://cdn.example.com/motion.mp4"}],
    "reference_audios": [{"url": "https://cdn.example.com/voice.wav"}]
  }
}
```

支持的图片角色：`first_frame`、`last_frame`、`reference_image`。首尾帧不能和普通参考图混用；`last_frame` 必须和 `first_frame` 同时出现。素材 URL 必须是公网 HTTP(S) 地址，也可以先调用 `/v1/uploads` 上传后使用返回地址。

## 3. 模型字段规则

用户只需在 `model` 中填写控制台当前提供的公开模型名。模型名是路由选择参数，不需要知道它对应的渠道、适配器、Base URL 或上游真实模型名。服务端会根据当前映射自动选择适配器并转换请求。

模型名可以由管理员调整或重新映射；用户侧接口格式不随模型或渠道变化。模型实际不支持的参数由上游返回明确错误。

## 4. 五种统一生成模式

### 文生视频

```json
{"model":"公开模型名","prompt":"夜晚城市，镜头缓慢推进"}
```

### 首帧生视频

```json
{"model":"公开模型名","prompt":"人物抬头并向前走","input_reference":{"url":"https://cdn.example.com/first.jpg"}}
```

### 首尾帧生视频

```json
{"model":"公开模型名","prompt":"自然过渡并保持人物一致","extra":{"reference_images":[{"url":"https://cdn.example.com/first.jpg","role":"first_frame"},{"url":"https://cdn.example.com/last.jpg","role":"last_frame"}]}}
```

### 多参考图生视频

```json
{"model":"公开模型名","prompt":"保持三张参考图的人物和服装","extra":{"reference_images":[{"url":"https://cdn.example.com/a.jpg","role":"reference_image"},{"url":"https://cdn.example.com/b.jpg","role":"reference_image"},{"url":"https://cdn.example.com/c.jpg","role":"reference_image"}]}}
```

### 全能参考

```json
{"model":"公开模型名","prompt":"参考人物、运镜和声音节奏","extra":{"reference_images":[{"url":"https://cdn.example.com/person.jpg","role":"reference_image"}],"reference_videos":[{"url":"https://cdn.example.com/motion.mp4"}],"reference_audios":[{"url":"https://cdn.example.com/voice.wav"}]}}
```

## 5. 响应和错误

创建成功返回统一任务 ID：

```json
{"id":"task_xxx","object":"video","status":"queued","model":"公开模型名"}
```

查询成功后返回：

```json
{"id":"task_xxx","object":"video","status":"completed","video_url":"https://api.aicopy.top/static-custom/generated-videos/task_xxx.mp4"}
```

用户侧不会返回上游域名、渠道号、适配器名或上游真实模型名。常见错误码：`invalid_parameter`、`invalid_reference`、`model_not_available`、`upstream_task_failed`、`upstream_timeout`。错误正文会尽量保留上游原因并转换成易懂中文。