视频生成 · minimax-h3

面向第一次接清霄视频的开发者：按 鉴权 → 上传素材 → 创建任务 → 轮询 → 下载 顺序走通即可。

你需要准备什么

1. 控制台账号与 API Key（sk-…）：见 鉴权。
2. Base URL：https://api.qingxiaocloud.com
3. 公开 model id（二选一）：

model id	默认参考分辨率	标准计费（live 价目）
minimax-h3-480p	864×480	¥0.07 / 秒
minimax-h3-768p	1376×768	¥0.08 / 秒

合入后生效： 下文「上传素材 POST /v1/files」随 video-platform 合入与 edge 发布后可用。在此之前，可把已有公网 https 图/视频/音频 URL 直接填入出片字段（仍须通过 SSRF 校验）。

---

推荐流程（图生 / 首尾帧 / 多参考）

① Authorization: Bearer sk-…
②（有本地文件时）POST /v1/files  → 得到 https url
③ POST /v1/videos（JSON，媒体字段只填 URL）→ 得到 video_…
④ 轮询 GET /v1/videos/{id}，直到 completed / failed
⑤ completed 后 GET /v1/videos/{id}/content 下载成片

文生可跳过第 ② 步（不传媒体字段）。

POST /v1/videos 只接受 JSON + HTTPS URL，不再接受把图片文件直接 multipart 塞进出片接口。本地文件必须先走 /v1/files。

---

1. 鉴权

所有请求带：

Authorization: Bearer sk-YOUR_KEY

Key 在 清霄控制台 创建。不要把 Key 写进前端仓库或公开页面。

---

2. 上传素材 POST /v1/files

合入后生效。用于把本地文件换成 Worker 可拉取的 https 能力 URL。

请求

• URL：https://api.qingxiaocloud.com/v1/files
• Header：Authorization: Bearer sk-…
• Body：multipart/form-data，字段名必须为 file（单文件）
• 可选字段：purpose=video_reference（可忽略）

限额（与出片参考素材一致）

类型	格式	大小上限
图片	jpg / png / webp	15MB
视频	mp4 / webm / mov	80MB
音频	wav / mp3 / m4a	20MB

一次请求 1 个文件。多参考请多次上传。

成功响应示例

{
  "id": "file_…",
  "object": "file",
  "bytes": 123456,
  "media_type": "image",
  "filename": "ref.jpg",
  "url": "https://compute.qingxiaocloud.com/v1/files/file_…/content?token=…",
  "expires_at": 1761000000,
  "created_at": 1760740800
}

字段	说明
url	填进出片请求的 https 地址；Worker 无需再带你的 sk- 即可 GET
expires_at	Unix 秒；默认 上传成功起 3 天 后过期删除
media_type	image | video | audio

curl 示例

export QX_API_KEY='sk-YOUR_KEY'
export QX_BASE='https://api.qingxiaocloud.com'

UPLOAD=$(curl -sS -X POST "$QX_BASE/v1/files" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -F "file=@./ref.jpg" \
  -F "purpose=video_reference")
echo "$UPLOAD"
FILE_URL=$(echo "$UPLOAD" | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")

删除 DELETE /v1/files/{id}

同一 sk- 可主动删除自己的文件（幂等：已删也返回 deleted）。

过期或任务进入 completed / failed 后，平台会尽力清理本 API 签发的对象；任务进行中（queued / in_progress）不会删，以免 Worker 拉不到。

---

3. 创建任务 POST /v1/videos

• Content-Type：application/json
• 媒体字段只能是 https URL（本上传 API 返回的，或你自备且通过 SSRF 校验的公网 https）

公共字段

字段	类型	必填	说明
prompt	string	*	非空；最长 10000 码点
model	string		minimax-h3-480p 或 minimax-h3-768p
seconds	number | string		默认 5。整数 4–15
size	string		省略用档位默认；须与 model 档位一致
n	number | string		可选；仅允许 1

size 常用值

864x480, 480x864, 640x640, 736x576, 576x736, 1376x768, 768x1376, 1024x1024, 1184x896, 896x1184

建议省略或传该档默认（480P → 864x480，768P → 1376x768）。

四种模式（媒体字段互斥）

模式	判定	媒体字段
文生	不传媒体	—
图生	input_reference	单个 https URL
首尾帧	first_frame / last_frame	各为 https URL，可只一侧
多参考	reference_media	[{ type, url }]

冲突（例如同时传 input_reference 与 first_frame）→ 400 media_fields_conflict。

若误用 multipart 把文件直接打进出片接口 → 400 multipart_not_allowed（请先 /v1/files）。

文生

curl -sS -X POST "$QX_BASE/v1/videos" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "雨中散步的猫",
    "model": "minimax-h3-768p",
    "size": "1376x768",
    "seconds": 5,
    "n": 1
  }'

图生

curl -sS -X POST "$QX_BASE/v1/videos" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"镜头缓缓推进，光影自然变化\",
    \"model\": \"minimax-h3-768p\",
    \"size\": \"1376x768\",
    \"seconds\": 5,
    \"n\": 1,
    \"input_reference\": \"$FILE_URL\"
  }"

首尾帧

curl -sS -X POST "$QX_BASE/v1/videos" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "从清晨过渡到黄昏",
    "model": "minimax-h3-768p",
    "size": "1376x768",
    "seconds": 8,
    "n": 1,
    "first_frame": "https://example.com/first.jpg",
    "last_frame": "https://example.com/last.jpg"
  }'

至少提供一侧；仅支持图片。

多参考

curl -sS -X POST "$QX_BASE/v1/videos" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "角色按参考图风格走动，环境参考视频氛围",
    "model": "minimax-h3-768p",
    "size": "1376x768",
    "seconds": 8,
    "n": 1,
    "reference_media": [
      { "type": "image", "url": "https://example.com/char.png" },
      { "type": "video", "url": "https://example.com/mood.mp4" },
      { "type": "audio", "url": "https://example.com/sfx.mp3" }
    ]
  }'

类型	数量上限
image	9
video	3
audio	3

音频不可单独成组：请至少再加一张图或一段视频。上传 API 不管个数；个数在出片时校验。

---

4. 轮询 GET /v1/videos/{id}

创建成功后响应含 id（形如 video_…）与 status（多为 queued）。

VIDEO_ID='video_…'

curl -sS "$QX_BASE/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $QX_API_KEY"

建议每隔 2–5 秒查询，直到 status 为 completed 或 failed。progress 为 0–100 的进度提示。

---

5. 下载 GET /v1/videos/{id}/content

仅在 completed 后调用；未就绪通常 409。

curl -sS -L -o out.mp4 \
  "$QX_BASE/v1/videos/$VIDEO_ID/content?variant=video" \
  -H "Authorization: Bearer $QX_API_KEY"

可能直接返回二进制，或 302 到可下载地址；使用 -L 跟随跳转。

---

其它端点

方法	路径	说明
GET	/v1/videos	列表
DELETE	/v1/videos/{id}	删除任务记录

---

端到端脚本（文生）

BASE=https://api.qingxiaocloud.com
KEY=sk-YOUR_KEY

CREATE=$(curl -sS -X POST "$BASE/v1/videos" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"雨中散步的猫","model":"minimax-h3-768p","seconds":5}')
VIDEO_ID=$(echo "$CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "id=$VIDEO_ID"

while true; do
  ST=$(curl -sS "$BASE/v1/videos/$VIDEO_ID" -H "Authorization: Bearer $KEY")
  STATUS=$(echo "$ST" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))")
  echo "status=$STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 3
done

curl -sS -L -o out.mp4 \
  "$BASE/v1/videos/$VIDEO_ID/content?variant=video" \
  -H "Authorization: Bearer $KEY"

图生时：先 /v1/files 得到 url，再在 JSON 里加 "input_reference": "<url>"。