---
name: h3-video
description: 用 MiniMax H3 生成视频（文生 / 首尾帧 / 参考图），通过 H3 Console 的 HTTP API 提交任务并取回结果。Use when：用户要生成视频、把想法/参考图写成 H3 提示词并提交。
---

# H3 视频生成

完整接口文档：同域名下的 `/docs/api.md`（公网：`http://qwen.wudaima.com/console/docs/api.md`）。
**只打 console 的 `/v1/*`，不要直连底层 raylight 端口。**

- 公网 Base URL：`http://qwen.wudaima.com/console`（所有路径带 `/console` 前缀）
- 局域网 Base URL：`http://192.168.110.67:8080`
- 鉴权：`Authorization: Bearer <token>`，token 向服务器管理员索取，**不要写进提示词或日志**。

## 流程

1. **定模式**（按传的字段自动判断）：只有文字 → 文生；有首/尾帧图 → fl2va（`first_frame_url`/`last_frame_url`）；有人物/场景/风格参考图、参考视频、参考音频 → ref2va（`reference_*_urls`）。
2. **写提示词**，见下节。
3. **给用户看草稿并等确认**。一条 1344×768、10–15s 的视频要跑 30–55 分钟，别未经确认就提交。
4. 有本地素材先上传：`curl -H "Authorization: Bearer $T" -F file=@a.jpg $BASE/v1/assets` → 返回 `url`。
5. 提交：
   ```bash
   curl -X POST $BASE/v1/videos -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
     -d '{"prompt":"…","width":1344,"height":768,"frames":300,"reference_image_urls":["<url>"]}'
   ```
   **永远返回 HTTP 202，必须检查响应体 `status`**：`"failed"` 表示校验没过，原因在 `error`。
6. 轮询 `GET $BASE/v1/videos/{id}`，状态 `queued → running → done/failed/cancelled`；完成后 `GET $BASE/v1/videos/{id}/file` 取 mp4。
   给用户的详情页链接：`$BASE/task.html/{id}`。

## 参数要点

- `frames` 为 24fps 帧数，秒数 = frames / 24。默认建议 1344×768、300 帧（≈12.5s）。
- 各分辨率帧数上限以 `GET /v1/models` 为准（1344×768 目前 412 帧）。超限直接判失败。
- 4 张卡是一个集群，**同一时刻只跑 1 条任务**，其余排队；多提交不会更快。
- `turbo` / `cfg_scale` / `negative_prompt` 当前不生效。

## 提示词写法

```
完整提示词 = 参考素材说明 + 核心创意 + 画面过程说明
```

- **参考素材说明**（没素材就跳过）：用 `@图片1` / `@视频1` / `@音频1` 编号并写清用途（人物参考、场景参考、风格参考、首帧……），编号顺序与实际传入顺序一致。
- **核心创意**：一句话写清主体 + 地点 + 事件 + 风格 + 运镜。运镜写具体（如 `truck left + pan right`），不要自相矛盾（有推近就别写"固定机位"）。
- **画面过程**：按时间轴/shot 分段，每段写景别、内容、运镜、动作、台词、声音。
- **时长一致**：提示词里的总时长和分镜时间戳必须与提交的 `frames / 24` 一致。
- **每个 shot 都带声音**：画内环境声/拟音 + 配乐，不要把声音全堆在结尾一句。
- **材质与微动作**：画面里可见的主要元素都给材质词；静态 shot 也要有光影/蒸汽/织物等细微动态。
- **画面里要出现的文字/Logo** 必须逐字写出。
- 不需要人物说话时，加"人物保持安静、嘴巴自然闭合"，避免模型自动念白。
- 比喻改成具体可视描述；不要写"不要字幕"（负向词对字幕无效甚至反效果）；避免"亮度分区"一类词，只描述具体光源照到哪里。
- 想要角色一致，务必传人物参考图。