创建视频

视频生成

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 · 创建 · 轮询 · 下载

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

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)

上传视频与传入参考视频

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

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

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

下表读取本站当前公开模型目录，只列出 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。这些是输入素材限制，不是生成结果的下载大小限制。

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

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

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"
}'

multipart：上传本地视频文件

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

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'

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" 才能下载结果，失败时读取返回的具体错误原因。

兼容字段与其他视频协议

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

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