视频 LLM 与异步任务

当前调用结论

t2_minimax-h3_bf16_7k2p 是 MiniMax H3 视频生成模型，不是普通 Chat 模型。不要调用 /v1/chat/completions；应使用 /v1/videos 异步任务接口。模型 ID 固定，不需要先调用 /v1/models 获取。

竖屏快速验证建议使用 size=768x1024、seconds=4；如果当前网关不接受该尺寸，应以网关返回的参数错误为准，不要把横屏结果再裁成竖屏。响应中的 size 是实际输出尺寸，必须记录并核对。

创建视频任务

视频创建请求使用 multipart/form-data。seconds 按字符串传递，不能把它当作 Chat JSON 参数。

create=$(curl -sS "$HKGAI_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $HKGAI_API_KEY" \
  -F "model=t2_minimax-h3_bf16_7k2p" \
  -F "task=t2va" \
  -F "prompt=一只橘猫坐在窗边，镜头缓慢推进。" \
  -F "seconds=4" \
  -F "size=768x1024")

task_id=$(printf '%s' "$create" | jq -r '.id // .task_id')
printf 'task_id=%s\n' "$task_id"

图片转视频（fl2va）

fl2va 使用 multipart 文件字段 input_reference 传入首帧图片。图片应先按目标画幅等比例补边，不能拉伸人物。请求示例：

curl -sS "$HKGAI_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $HKGAI_API_KEY" \
  -F "model=t2_minimax-h3_bf16_7k2p" \
  -F "task=fl2va" \
  -F "prompt=固定机位，保持图片中人物的脸、发型、服装和身体比例；人物自然呼吸并眨眼，双脚和骨盆稳定，最后回到中性姿态。背景为纯绿色抠像幕，不新增人物或物体。" \
  -F "seconds=4" \
  -F "size=768x1024" \
  -F "input_reference=@portrait-768x1024.png"

这里的 input_reference 是 HKGAI 网关的 multipart 图片字段；不要同时把图片放进 JSON 或 prompt，也不要手动设置 Content-Type，让 curl 自动生成 multipart boundary。若接口返回“未知字段/不支持 fl2va”，说明当前网关未开启图片转视频适配，不能自行改名猜字段。

图片建议使用 JPEG、PNG 或 WebP，短边不低于 720 像素，并确认已获得人物肖像使用授权。图片输入、任务响应和成片下载均由调用方自行保存和管理，API Key 不要写入 prompt、文件名或日志。

注意：若直接调用 MiniMax 原生 https://api.minimaxi.com/v1/video_generation，参数不是本页的网关格式，图片字段为 JSON 中的 first_frame_image（公网 URL 或 Data URL）；不要把两套接口的字段混用。

参数说明

参数	说明
`model`	固定 `t2_minimax-h3_bf16_7k2p`。
`task`	`t2va` 文生视频；`fl2va` 图片首帧驱动。
`prompt`	动作、镜头、人物约束和声音描述；不要把 API Key 放入其中。
`seconds`	建议快速验证 4 秒；按网关允许范围填写。
`size`	竖屏优先 `768x1024`；实际输出以响应 `size` 为准。
`input_reference`	仅 `fl2va` 使用的 multipart 图片文件字段。

num_inference_steps 不是公开网关必选字段；只有后端明确支持透传时才传递。自部署服务可使用 5 步做构图冒烟、 9 步做质量母版，网关不支持时不要强行添加该参数。

查询状态

curl -sS "$HKGAI_BASE_URL/v1/videos/$task_id" \
  -H "Authorization: Bearer $HKGAI_API_KEY"

常见状态：

queued：任务已创建，等待执行。
in_progress：模型正在生成。
completed：可以下载成片。
failed / error：任务失败，读取 error 后再决定是否重试。

下载成片

curl -sS "$HKGAI_BASE_URL/v1/videos/$task_id/content" \
  -H "Authorization: Bearer $HKGAI_API_KEY" \
  --output hkgai-video.mp4

本项目的管理台视频探针会保存任务 ID、状态、进度和生成耗时；状态查询与成片下载通过服务端代理完成，浏览器不会接触 API Key。

超时和配额策略

视频生成耗时以分钟计，不能复用 Chat 的 60 秒同步超时。管理台的“测试筛选”和“测试全部”会跳过视频模型，只能在选中模型后手动执行一次视频探测，以免批量消耗上游配额。

调用方应：

创建任务后立即保存 id / task_id。
按 5～15 秒间隔轮询，并设置总等待上限。
只在 completed 时请求 /content。
遇到 queued 或 in_progress 不要重复创建任务；遇到 failed 再根据错误决定是否重试。

与 Chat 模型的区别

视频模型不返回 Chat 的 token 流和 usage.completion_tokens，页面不显示 token/s，而显示提交耗时、任务状态、进度和成片信息。视频探测成功表示任务接口和模型链路可用，不等同于画面、镜头或音频质量验收。