# 创建视频

<a id="video-generation"></a>

<a id="视频生成"></a>

## 视频生成

`POST /v1/videos`

视频生成是异步任务。创建后立即返回 `queued`，轮询状态，完成后读取 URL 或下载内容。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `model` | `string` | 是 | 视频模型 ID。 |
 `prompt` | `string` | 文生视频必填 | 描述视频内容、动作、镜头和风格。 |
 `seconds / duration` | `string \| number` | 是 | 生成时长；duration 是兼容别名，必须是模型支持的时长。 |
 `size` | `string` | 否 | WIDTHxHEIGHT；短边决定分辨率档位，同时决定比例。 |
 `aspect_ratio` | `string` | 否 | 也可直接传比例，例如 16:9、9:16；size 优先映射。 |
 `resolution` | `string` | 否 | 也可直接传 720p、1080p 等模型支持的档位。 |
 `reference_mode` | `string` | 否 | asset=普通参考图；frame=首尾帧。字段本身也会触发自动识别。 |
 `reference_images` | `string[] \| file[]` | 否 | 普通参考图；JSON 用 URL、Data URI 或原始 Base64，multipart 可重复字段。 |
 `start_frame / end_frame` | `string \| file` | 否 | 首尾帧；end\_frame 必须搭配 start\_frame，且不能与普通参考图混用。 |
 `reference_videos` | `string[] \| file[]` | 否 | 传入参考视频：JSON 用 HTTP(S) 视频直链或 Data URI 数组；multipart 上传本地文件，多段视频重复同名字段。仅限支持参考视频的模型；完整传法、兼容字段 input\_video 和限制见下方“上传视频与传入参考视频”。 |
 `audio_reference(s)` | `string \| string[] \| file[]` | 否 | 参考音频；必须搭配模型支持的普通图像或视频参考。 |
 `audio` | `boolean` | 否 | 控制输出音轨；仅对支持该能力的模型生效。 |
 `response_format` | `string` | 否 | 仅支持 url；完成态返回公开临时 URL 和 expires\_at。 |

 **视频生成**  `POST /v1/videos · 创建 · 轮询 · 下载`

```bash
curl https://image.apixhm.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street, cinematic",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url"
  }'

# 轮询状态，完成后读取 url
curl https://image.apixhm.com/v1/videos/<VIDEO_ID> \
  -H "Authorization: Bearer YOUR_API_KEY"
curl '<RETURNED_URL>' -o output.mp4
```

```python
import time
import requests

base = "https://image.apixhm.com/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
job = requests.post(f"{base}/videos", headers=headers, json={
    "model": "seedance-2.5",
    "prompt": "a paper boat sailing down a rainy street",
    "seconds": "4",
    "size": "1120x480",
    "response_format": "url",
}).json()

while True:
    status = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

if status["status"] == "completed":
    open("output.mp4", "wb").write(requests.get(status["url"]).content)
```

<a id="video-reference-input"></a>

### 上传视频与传入参考视频

视频输入使用 `reference_videos`。传视频可用公网链接，也可直接上传本地文件；多段视频在同一个请求中提交。先确认所选模型支持参考视频，再按下面的 JSON 或 multipart 示例调用 `POST /v1/videos`。

`input_reference`、`start_frame` 和 `end_frame` 是图片首尾帧参数。参考视频使用素材模式 `reference_mode="asset"`，不能与首尾帧混用；`seconds` 表示生成视频的时长。

<a id="video-reference-models"></a>

### 支持参考视频的模型与限制

下表读取本站当前公开模型目录，只列出 `capabilities.max_reference_videos > 0` 的视频模型。未列出的模型请先核对其能力；当前 API Key 是否可调用，还需通过 `GET /v1/models` 确认。

 模型 ID | 最多视频数 | 生成时长 | 分辨率 | 参考素材限制 |
| --- | --- | --- | --- | --- |
 `minimax-h3-768p` | 3 | 4-15秒 | 以模型目录为准 | 目录未声明额外限制；仍须遵守素材格式及上传限制。 |
 `wan3.0-720p-mx10.5.0-gfapi` | 5 | 4-30秒 · 8个档位 | 720p | 目录未声明额外限制；仍须遵守素材格式及上传限制。 |
 `wan3.0-480p-mx10.5.0-gfapi` | 5 | 4-30秒 · 8个档位 | 480p | 目录未声明额外限制；仍须遵守素材格式及上传限制。 |
 `wan3.0-1080p-mx10.5.0-gfapi` | 5 | 4-30秒 · 8个档位 | 1080p | 目录未声明额外限制；仍须遵守素材格式及上传限制。 |
 `minimax-h3-optimized` | 3 | 4-15秒 | 以模型目录为准 | 目录未声明额外限制；仍须遵守素材格式及上传限制。 |

数量、单文件大小、总大小、参考素材总时长和可混用的图片数量可能因模型不同。链接必须可直接读取视频内容，不能是网页、需要登录的地址或本机路径；本地文件示例使用 MP4 和 `video/mp4`。这些是输入素材限制，不是生成结果的下载大小限制。

<a id="video-reference-url"></a>

### JSON：传视频链接与多段视频

`reference_videos` 是字符串数组，只有一段视频也要使用数组。每项填写一个 HTTP(S) 直链；也支持带视频 MIME 的 Data URI，例如 `data:video/mp4;base64,...`。本地路径请使用下一节的文件上传方式。

```bash
curl 'https://image.apixhm.com/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-h3-768p",
  "prompt": "参考视频中的主体动作和镜头运动，生成一段新的电影风格视频",
  "seconds": "4",
  "aspect_ratio": "1:1",
  "resolution": "720p",
  "reference_mode": "asset",
  "reference_videos": [
    "https://example.com/reference-1.mp4",
    "https://example.com/reference-2.mp4"
  ],
  "response_format": "url"
}'
```

<a id="video-reference-upload"></a>

### multipart：上传本地视频文件

每个文件重复一次同名字段 `reference_videos`，不要拼成一个文件名，也不要把文件路径放进 JSON。示例按模型支持数量传入一至两段视频；传一段时仅保留一个文件字段。让 curl 或 requests 自动生成包含 boundary 的 `Content-Type`。

```bash
curl 'https://image.apixhm.com/v1/videos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=minimax-h3-768p' \
  -F 'prompt=参考视频中的主体动作和镜头运动，生成一段新的电影风格视频' \
  -F 'seconds=4' \
  -F 'aspect_ratio=1:1' \
  -F 'resolution=720p' \
  -F 'reference_mode=asset' \
  -F 'response_format=url' \
  -F 'reference_videos=@./reference-1.mp4;type=video/mp4' \
  -F 'reference_videos=@./reference-2.mp4;type=video/mp4'
```

```python
from contextlib import ExitStack
import requests

url = "https://image.apixhm.com/v1/videos"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "model": "minimax-h3-768p",
    "prompt": "参考视频中的主体动作和镜头运动，生成一段新的电影风格视频",
    "seconds": "4",
    "aspect_ratio": "1:1",
    "resolution": "720p",
    "reference_mode": "asset",
    "response_format": "url"
}
paths = ["reference-1.mp4","reference-2.mp4"]

with ExitStack() as stack:
    files = [
        ("reference_videos", (path, stack.enter_context(open(path, "rb")), "video/mp4"))
        for path in paths
    ]
    response = requests.post(url, headers=headers, data=data, files=files, timeout=120)
    response.raise_for_status()
    job = response.json()
    print(job)  # 保存 id，使用 GET /v1/videos/{id} 继续查询
```

请求成功后保存返回的 `id`，按本页前面的示例轮询 `GET /v1/videos/{id}`；只有 `status="completed"` 才能下载结果，失败时读取返回的具体错误原因。

<a id="video-reference-protocols"></a>

### 兼容字段与其他视频协议

`POST /v1/videos` 推荐统一使用 `reference_videos`。JSON 也兼容 `input_video`（字符串或字符串数组）和 `video_references`（字符串数组）；multipart 也兼容 `input_video`、`input_video[]`、`reference_video`、`video_references`、`video_references[]`。同一批素材只选一种字段名，重复传入会合并计数。

使用 [Seedance 任务接口](https://image.apixhm.com/docs.md?page=seedance)或 [MiniMax v2 视频接口](https://image.apixhm.com/docs.md?page=minimax)时，视频放在 `content` 数组中，格式为 `{"type":"video_url","video_url":{"url":"https://example.com/reference.mp4"},"role":"reference_video"}`；具体路径、模型范围和其他必填项见各自文档，不要混用不同协议的字段。