素材上传（/v1/files）

出片接口只认 https 链接，不认本地文件。这个接口负责把你电脑或服务器上的图片、视频、音频，换成一条能直接在出片请求里使用的 https 链接。

什么情况下需要它：

• 素材还在你本地（拖不进请求里）→ 先调这个接口，拿到 url，再填进出片请求。
• 素材已经在图床、CDN 或对象存储上，公网能直接打开 → 不用上传，直接把链接填进去。

如果调用时提示接口不存在或暂未开放，说明上传能力还没在你所在的环境上线；此时直接用已有的公网 https 链接出片即可。

一分钟上手

① POST /v1/files（form-data，文件字段名必须是 file）→ 返回 url
② 把 url 填进出片请求的 input_reference / first_frame / reference_media

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

# 1. 上传文件，换回链接
UPLOAD=$(curl -sS -X POST "$QX_BASE/v1/files" \
  -H "Authorization: Bearer $QX_API_KEY" \
  -F "file=@./ref.jpg")

FILE_URL=$(echo "$UPLOAD" | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
echo "$FILE_URL"

# 2. 用这条链接出片（图生视频）
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\",
    \"seconds\": 5,
    \"input_reference\": \"$FILE_URL\"
  }"

请求说明

项	值
地址	POST https://api.qingxiaocloud.com/v1/files
请求头	Authorization: Bearer sk-…
请求体	multipart/form-data
文件字段	名称必须叫 file（写成 image、file[] 之类都会报错）
可选字段	purpose=video_reference，可以不传

一次请求只传 1 个文件。需要多张参考图、多段参考视频，就多传几次，分别记下每次返回的 url。

支持的文件

类型	常见格式	单个文件上限
图片	jpg / png / webp	15MB
视频	mp4 / webm / mov	80MB
音频	wav / mp3 / m4a	20MB

出片时对参考素材还有数量限制（图片 9 个、视频 3 个、音频 3 个），上传时不校验，详见 视频生成。

返回内容

{
  "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 链接。链接自带访问凭据，出片时无需再带你的 sk-
expires_at	链接过期时间（Unix 秒）。默认在上传成功后 3 天 过期，过期后文件会被删除

其余字段（id、bytes、media_type、filename、created_at）用于自查和排查问题。

链接的有效期

• 上传成功后 3 天 内有效，足够把视频任务跑完。
• 任务还在排队或生成中（queued / in_progress）时，平台不会清理素材，避免生成中途取不到文件。
• 任务结束（completed / failed）或链接到期后，平台会清理对应文件。

如果隔了 3 天以上才出片，重新上传一次、换新链接即可。

主动删除

DELETE /v1/files/{id}

带上同一个 sk-，可以删除自己上传的文件。重复删除也会返回成功，不需要先查询是否存在。

curl -sS -X DELETE "$QX_BASE/v1/files/file_…" \
  -H "Authorization: Bearer $QX_API_KEY"

常见问题

提示缺少文件字段？ 字段名必须是 file（不是 image、file[]）。

能一次上传多个文件吗？ 不能，一次一个；多参考就多传几次。

可以用自己的图床链接吗？ 可以，只要是公网能直接访问的 https 链接。

上传后链接过期了怎么办？ 重新上传，用新链接；已经创建的任务不受影响。

出片时提示 multipart_not_allowed？ 说明你把文件直接塞进了出片请求。先上传拿链接，再用链接出片。

遇到其它报错，见 错误与限制。