# 视频工厂 · 供应商参数速查（经验复用表）

> **用途**：动手写代码前先查这里；查不到再查 `docs/api/raw/qwen/`（206 页官方文档）；**都没有才考虑花钱实测**。
> 最后更新：2026-10-04

---

## 🔴 血泪教训（先读这段）

| 日期 | 教训 | 代价 |
|:--|:--|:--|
| 2026-10-04 | **原生音频字段`sound`/`audio` 在官方文档里就有**，我却直接花钱实测试 | **¥33** |
| 2026-10-04 | 探测"不存在的字段"时用了**合法参数** → 请求通过校验 → 真实生成 | 含在上面 |
| 2026-10-03 | `image2video/video-synthesis` 对**空 input 也会创建任务**（需手动 cancel） | ¥2.2 |

**正确顺序**：
```
① 查本文档 → ② 查 docs/api/raw/qwen/ → ③ 查 git log -S"字段名"
→ ④ 零成本探测（非法值，必须在**参数校验阶段**失败）
→ ⑤ 最后才真实调用（先跟用户报费用）
```

**零成本探测的正确姿势**：
- ✅ 传**非法枚举值**（`sound="INVALID"` → 报错列出合法值 `on/off`，不建任务）
- ✅ 传**非法 model 名**（`"no-such-model"` → 报 "Model not exist"）
- ❌ **不要**用"合法值 + 假字段名"——假字段被忽略后请求就合法了，会真扣费

---

## 一、可灵（Kling）视频生成

**⚠️ 两条通道字段名不同，别混用：**

### 通道 A：可灵官方直连
`https://api-beijing.klingai.com` · auth = Bearer

| 字段 | 值 | 说明 |
|:--|:--|:--|
| `sound` | `"on"` / `"off"` | **原生音频开关**（实测确认） |

**实测证据（2026-10-04）**：
```
sound="on"  → 输出含 Audio: aac 44100Hz stereo 128kb/s
              mean_volume -28.0dB / max -11.7dB（真实语音，非空轨）
sound 不传  → 只有 Video 流
提示词里写 Audio: 层但 sound 不传 → 无效（不发音频）
```

### 通道 B：千问AI平台代理
`https://maas.qianwenaiapi.com/api/v1` · auth = Bearer（同一个 DASHSCOPE_API_KEY）

**模型 ID**（注意带 `kling/` 前缀）：
```
kling/kling-v3-turbo-video-generation   文生 + 图生（首帧）
kling/kling-v3-video-generation         文生 + 图生（首帧/首尾帧）+ 多镜头叙事
kling/kling-v3-omni-video-generation    全部（+ 参考生视频 + 视频编辑）
```

**parameters**：
| 字段 | 类型 | 说明 |
|:--|:--|:--|
| `mode` | `"std"` / `"pro"` | 分辨率 std=720P / pro=1080P |
| `duration` | int 3–15（默认 5） | 时长；omni 且传视频时 `type=base` 则跟随原视频 |
| **`audio`** | **boolean（默认 false）** | **是否自动生成配音** ← 与官方 `sound` 等价 |
| `aspect_ratio` | `"16:9"` / `"9:16"` / `"1:1"` | 宽高比 |
| `watermark` | boolean（默认 false） | 含水印版（返回 `watermark_video_url`） |

**input**：
| 字段 | 说明 |
|:--|:--|
| `prompt` | 提示词（可用 `<<<element_1>>>` 引用元素 / `<<<image_1>>>` 引用图） |
| `multi_shot` / `shot_type` / `multi_prompt` | 多镜头叙事模式 |
| `media[]` | `{url, type, keep_original_sound}`；type = `first_frame` / `last_frame` / `refer` / `base`（omni 参考视频）/ `feature` |
| `element_list[]` | `{element_id}` — **角色元素绑定**（跨镜头一致性） |
| `media[].keep_original_sound` | `"yes"` / `"no"`（默认 no）—— 仅 omni 且 type=base/feature 有效 |

**查询结果返回**：`audio: boolean`（是否包含音频）、`video_count`、`SR`

**文档位置**：`docs/api/raw/qwen/api-reference-video-generation-kling-video-generation-create-task.md`

---

## 二、百炼 / 千问AI平台 图像能力

（base_url：百炼 `dashscope.aliyuncs.com`；千问 `maas.qianwenaiapi.com`）

| 模型 | 用途 | 价格 | 状态 |
|:--|:--|:--|:--|
| `wan2.7-image-pro` | 文生图 / **多图参考融合**（9 图输入） | ¥0.2/张 | ✅ 实测可用 |
| `qwen-image-edit-plus` | 指令图像编辑（**保结构重绘**） | ¥0.2/张 | ✅ 可用 |
| `qwen-image-edit` | 基础编辑（输入图 ≤3） | ¥0.2/张 | ✅ 可用 |
| `wan2.7-image` | 文生图 / 编辑 | ¥0.2/张 | ✅ 实测可用 |

**字段结构**（同步接口，`multimodal-generation/generation`）：
```json
{
  "model": "wan2.7-image-pro",
  "input": {"messages": [{"role": "user", "content": [
      {"text": "指令"},
      {"image": "<URL 或 data:image/png;base64,...>"}
  ]}]},
  "parameters": {"size": "1024*1024", "n": 1, "watermark": false}
}
```
- `size` 格式 = **`宽*高`**（不是 `1K`/`2K`！见 `keyframe_gen.py: SIZE_PRESETS`）
- **content 顺序有讲究**：qwen-image 系列 **先 image 后 text**；wan 系列 **先 text 后 image**
  （`keyframe_gen.py: IMAGE_FIRST_PREFIXES` 自动切换）
- 参考图可直传 base64 data URL，**无需先上传 OSS**

---

## 三、常用价格表

| 项目 | 价格 |
|:--|:--|
| 可灵 kling-v3 无声 720P | ¥0.6/秒 |
| 可灵 kling-v3 有声（sound=on） | 同上（**不加价**） |
| 可灵 kling-v2-5-turbo | ¥0.3/秒 |
| 百炼 wan2.2-kf2v-flash（首尾帧） | ¥0.1/秒 480P |
| 百炼 wan2.6-r2v-flash（参考生视频） | ¥0.3/秒 720P |
| 百炼图像（wan2.7 / qwen-image-edit） | ¥0.2/张 |
| 百炼 VideoRetalk（对口型） | ¥0.08/秒（1800 秒免费额度） |
| 可灵视频生音效 | ¥0.25/次 |

---

## 四、待补（下次去查，别实测）

- [ ] 万相 3.0（wan30-video）的 `audio` 参数细节与 30 秒限制
- [ ] 可灵 `element_list` 元素管理的创建接口（跨视频一致性）
- [ ] 可灵 `multi_shot` / `shot_type` 的完整取值表

**补充方式**：`fetch_url` 抓 `platform.qianwenai.com/docs/llms.txt` 找页面 →
抓 `openapi-*.json`（OpenAPI 规格，零费用）→ 追加到本文档。

---

## 🆕 2026-10-05 追加：可灵「两条通道」的字段差异（重要，别混用）

**同一个可灵，有两个入口，字段名完全不同**：

| | 可灵官方（**我们在用**） | 千问AI平台（千问代理） |
|---|---|---|
| base_url | `api-beijing.klingai.com` | `maas.qianwenaiapi.com` |
| 鉴权 | `Bearer api-key-kling-…` | `Bearer sk-…`（同一个百炼 key） |
| 原生有声 | **`sound: "on"/"off"`** | **`parameters.audio: true/false`** |
| 首尾帧 | `image` + `image_tail`（顶层字段） | `input.media[] = [{type:first_frame},{type:last_frame}]` |
| 时长 | 5 / 10 秒 | **3–15 秒** |
| 分辨率 | 720P / 1080P | std / pro / **4k** |
| 多镜头叙事 | ❌ | ✅ `multi_shot` + `shot_type` + `multi_prompt`(≤6) |
| 参考生视频 | ❌ | ✅ omni 模型的 `refer` |

> ❌ 把 `sound="on"` 发给千问代理 → 字段不存在，静默被忽略（可能白花钱）
> ❌ 把 `audio=true` 发给可灵官方 → 同上

### 百炼（万相）视频模型的两个端点（**不同模型走不同端点**）

```
wan2.2-kf2v-flash   首尾帧    → /services/aigc/image2video/video-synthesis
wan2.6-r2v-flash    多图参考  → /services/aigc/video-generation/video-synthesis
```

**字段差异**：
```
KF2V: input.first_frame_url ★ + input.last_frame_url ★ + prompt(可选)
      parameters{resolution, prompt_extend, seed, template, watermark}
      ⚠️ duration **固定 5 秒不可传**（传了有被拒风险）
      ⚠️ 输出宽高比跟随首帧

R2V:  input.media[] ★ [{type, url}] + input.prompt ★（**必填**）
      media.type = first_frame | reference_image | reference_video
      最多 5 个参考
```

### 本次踩的三个坑（已修）

1. **KF2V 端点写错** → 走成 `video-generation`（那是 R2V 的）→ 第一次生成必定 404
2. **KF2V 传了 `duration`** → 官方明确「固定 5 秒，不可修改」
3. **R2V 的 `prompt` 做成可选** → 官方是 ★必填