视频 API 调用指南

使用本站绑定视频混合组的 API Key。所有入口共用本站余额、任务记录与权限；请求格式不会改变价格。模型名、分辨率、时长和价格以视频专区当前开放目录为准。

兼容范围：OpenAI Videos 基础格式、Seedance 任务格式、MiniMax V1 文生视频及 H3 V2 文本/参考图格式。不是厂商完整 API 的镜像，也不代表官方型号已经开通。不要直接复制厂商型号名；请填写本站公开模型名。

准备

统一服务地址为 https://api.qiyun.site，视频与其他 API 共用此域名。

export CHUSAPI_URL='https://api.qiyun.site'
export CHUSAPI_KEY='你的本站 API Key'
export MODEL='视频专区显示的公开模型名'

下面的 5 秒、768p 只是参数示例，必须匹配所选模型。密钥只放在自己的服务端或本机环境变量中。

1. OpenAI Videos 格式

curl "$CHUSAPI_URL/v1/videos" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"你的公开模型名","prompt":"湖面上的日出","seconds":"5","resolution":"768p"}'

返回 id，例如 task_...。支持 JSON、multipart 文本表单、URL 编码表单，seconds 可以为整数或整数字符串。

curl "$CHUSAPI_URL/v1/videos" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -F "model=$MODEL" -F 'prompt=湖面上的日出' \
  -F 'seconds=5' -F 'resolution=768p'

curl "$CHUSAPI_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $CHUSAPI_KEY"

新任务状态：queued → in_progress → completed / failed。历史任务可能仍返回 processing，客户端应将它视为未完成。响应含 id、object、model、status、progress、created_at、seconds、size；完成后含 completed_at 和 metadata.url。

参考图使用 input_reference: "https://你的素材地址/image.png"、URL 数组，或 {"image_url":"https://你的素材地址/image.png"}。也可使用本站字段 reference_images，但同一请求不要混用。暂不支持文件上传、Base64、file_id、remix、编辑或扩展。

2. Seedance 格式

curl "$CHUSAPI_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"你的公开模型名","content":[{"type":"text","text":"湖面上的日出"}],"duration":5,"resolution":"768p"}'

curl "$CHUSAPI_URL/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $CHUSAPI_KEY"

创建返回 {"id":"task_..."}；查询状态为 queued / running / succeeded / failed，成功结果位于 content.video_url。SDK 若自动追加路径，Base URL 填 https://api.qiyun.site/api/v3。

3. MiniMax 格式

V1 文生视频

curl "$CHUSAPI_URL/v1/video_generation" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"你的公开模型名","prompt":"湖面上的日出","duration":5,"resolution":"768P"}'

curl "$CHUSAPI_URL/v1/query/video_generation?task_id=$TASK_ID" \
  -H "Authorization: Bearer $CHUSAPI_KEY"

# Success 后，file_id 等于本站任务 ID
curl "$CHUSAPI_URL/v1/files/retrieve?file_id=$TASK_ID" \
  -H "Authorization: Bearer $CHUSAPI_KEY"

创建返回 task_id、base_resp；查询状态为 Queueing / Processing / Success / Fail。文件查询返回 file.download_url。V1 不支持 first_frame_image、subject_reference、prompt_optimizer 等厂商专属选项。

H3 V2

curl "$CHUSAPI_URL/v2/video_generation" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"你的公开模型名","content":[{"type":"text","text":"湖面上的日出"}],"duration":5,"resolution":"768P"}'

curl "$CHUSAPI_URL/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $CHUSAPI_KEY"

创建返回 task_id；查询返回 {"task":{"id":"task_...","status":"running"}}。状态为 queued / running / succeeded / failed；完成后读取 task.content.url。

参数与参考图

参数	规则
model	必填，本站启用的公开模型名；协议名称不是模型名。
prompt / content	必须有文本提示词；content 与 prompt/reference_images 不混用。
seconds / duration	二选一，省略使用模型默认值；不支持负数、自动时长或小数。
resolution	按目录选择；入口将 768P、2K 等统一为小写计费档位。
size	宽x高。未指定 resolution 时，仅按短边 480/720/768/1080/1440/2160 推导 480p/720p/768p/1080p/2k/4k；其他尺寸须明确档位。显式 resolution 是计费依据，size 为生成尺寸偏好，最终成品由模型决定。
ratio	Seedance/H3 可传 1:1、16:9、9:16、4:3、3:4、21:9，不能同时传 size；按 aspect_ratio 转发，实际支持取决于模型。
spec	本站按次计费扩展参数，默认为 default，须有对应定价。
n	仅支持 1；每个任务生成一个视频。

Seedance/H3 的参考图加入 content，顺序保留，最多 8 张：

{"type":"image_url","image_url":{"url":"https://你的素材地址/image.png"},"role":"reference_image"}

URL 须可被生成服务读取。当前不提供首帧/尾帧定位、参考视频/音频、上传文件、回调、取消任务或自动重试。含未知参数或无法保留语义的内容项会直接返回中文错误，不会默默丢弃。单次请求体最多 1 MiB。

轮询和下载

保存创建返回的任务 ID，每隔 5 秒查询，遇成功或失败立即停止。通常 30 分钟内结束。任何入口创建的任务，都可以使用统一下载接口：

curl "$CHUSAPI_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $CHUSAPI_KEY" -o video.mp4

# 断点读取，206 为部分内容，200 为完整内容
curl "$CHUSAPI_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $CHUSAPI_KEY" \
  -H 'Range: bytes=1024-' -o video-part.mp4

所有返回的视频地址均为本站相对路径，拼接本站域名后仍需携带 Authorization；不能当作匿名可访问的厂商 CDN URL。第三方 SDK 若自动匿名下载，需改为上述鉴权下载。任务只能由所属用户读取。API 与控制台共用任务记录。

扣费和错误

提交冻结预估金额，成功结算、失败释放；查状态和下载不再计费。各协议使用同一模型定价与分组视频倍率。没有可用模型、参数不支持、余额不足时不发起生成。

HTTP 错误统一为 {"error":{"type":"video_error","code":"VIDEO_...","message":"中文说明"}}，不是每个厂商原样的错误信封。任务已受理后的失败体按各协议状态返回。

错误码	处理方式
VIDEO_INVALID_PARAMS	检查时长、分辨率、字段类型和参数冲突。
VIDEO_UNSUPPORTED_PARAMETER / VIDEO_UNSUPPORTED_INPUT	删除未开放的参数或改用图片 URL。
VIDEO_PRICE_NOT_CONFIGURED	该规格未配置价格，请更换规格或联系管理员。
VIDEO_INSUFFICIENT_BALANCE	余额不足，请充值后再提交新任务。
VIDEO_UPSTREAM_SUBMIT_FAILED	生成服务未成功受理；查看任务记录，不要连续重复提交。
VIDEO_NOT_FOUND / VIDEO_NOT_READY	检查任务 ID、所属账号或是否已完成。

POST 暂不支持 Idempotency-Key 幂等重放。网络断开后先去视频专区核对任务，不要自动重发 POST，以免创建多个付费任务。格式兼容不保证任意厂商 SDK 的上传、列举、删除、匿名下载等辅助功能可用。