@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation/MiniMax-H3-Max/MiniMax-H3-Max_Fal.md

@@ -0,0 +1,62 @@
+# MiniMax H3 Max（含 Max Turbo）· Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-07 |
+| 模态 | 视频 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `minimax/h3-max/{text-to-video,image-to-video,reference-to-video}`、`minimax/h3-max-turbo/{同上}` |
+| 痕迹AI 模型 ID | `fal-ai-minimax-h3-max`（canonical `minimax-h3-max`），Max / Max Turbo 用「版本」切换 |
+| 接口形态 | Fal 队列异步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+## 1. 请求参数（OpenAPI，2026-11-07 读取；Max 与 Turbo 字段基本相同）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `prompt` | string | 是 | — | ≤50000 字；参考模式用「Image 1 / Video 1 / Audio 1」指代 |
+| `prompt_expansion_mode` | string | **是** | `balanced` | `disabled` / `balanced`（约 1 秒）/ `quality`（最多约 30 秒） |
+| `duration` | number | 否 | `5` | 0.92–15 秒，输出可能比请求长约 0.7 秒 |
+| `resolution` | string | 否 | `768P` | `480P` / `768P` / `1080P`（1080P 为 768P 原生结果的潜空间精修） |
+| `aspect_ratio` | string | 否 | 文生 `16:9`，参考 `adaptive` | 文生 `21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`；参考另有 `adaptive`；图生无此字段（跟随图片） |
+| `image_url` / `end_image_url` | string | 否 | — | 图生首帧 / 尾帧；只给尾帧也可 |
+| `reference_image_urls` | array | 否 | — | ≤9 |
+| `reference_video_urls` | array | 否 | — | ≤3，每段 2–15 秒，合计 ≤15 秒 |
+| `reference_audio_urls` | array | 否 | — | ≤3，每段 2–15 秒，合计 ≤15 秒；图片、视频、音频合计 ≤12 个 |
+| `target_audio_url` | string | 否 | — | 钉住输出配乐，未接入 |
+| `reference_conditions` / `middle_image_url` / `middle_frame_time` | | 否 | | 仅 Max 参考端点部分支持；未接入 |
+| `sync_mode` / `enable_safety_checker` | | 否 | | 不展示、不下发 |
+
+响应：`{ "video": { "url" }, "expanded_prompt", "timings" }`；参考端点另有 `reference_tokens`。
+
+## 2. 价格（模型页 pricingInfoOverride / publicEndpointBilling，2026-11-07 读取）
+
+| 版本 / 端点 | 480P | 768P | 1080P |
+|---|---|---|---|
+| Max 文生 / 图生 / 参考（标准价） | $0.05/秒 | $0.08/秒 | $0.16/秒 |
+| Max Turbo 文生 / 图生（标准价） | $0.025/秒 | $0.04/秒 | $0.08/秒 |
+| Max Turbo 参考生视频 | $0.05/秒 | $0.08/秒 | $0.16/秒 |
+
+- 2026-11-01 至 11-15 文生 / 图生有 7 折促销（Max $0.035/$0.056/$0.112，Turbo $0.0175/$0.028/$0.056），11-16 起恢复标准价；痕迹AI 按标准价估算。
+- 参考生视频含 4096 个参考 token，超出部分另计（Turbo 页面为 $0.016/千 token），无法在提交前预估。
+
+## 3. 适配要点
+
+- 与现有 `fal-ai-minimax-h3`（H3，480P/768P/2K/4K，canonical `minimax-h3`）分辨率档、价格、端点都不同，新建模型而不是并进 H3 文件。
+- 两个主选择器：「版本」（Max / Max Turbo，切端点前缀）与「模式」（文/图生视频、参考生视频）。
+- 文/图生按图片数自动路由：0 张文生、1 张首帧、2 张首尾帧。
+- `prompt_expansion_mode` 是必填字段，始终下发。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Max 文生 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=minimax/h3-max/text-to-video | 否 |
+| Max 图生 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=minimax/h3-max/image-to-video | 否 |
+| Max 参考 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=minimax/h3-max/reference-to-video | 否 |
+| Turbo 文生 / 图生 / 参考 schema | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=minimax/h3-max-turbo/text-to-video （另两个端点同理） | 否 |
+| Max 价格 | https://fal.ai/models/minimax/h3-max/text-to-video | 否 |
+| Max 参考价格 | https://fal.ai/models/minimax/h3-max/reference-to-video | 否 |
+| Turbo 价格 | https://fal.ai/models/minimax/h3-max-turbo/text-to-video | 否 |
+| Turbo 参考价格 | https://fal.ai/models/minimax/h3-max-turbo/reference-to-video | 否 |

package/docs/model-adaptation/MiniMax-Speech/MiniMax-Speech_/346/264/276/346/254/247/344/272/221.md

@@ -1,170 +1,170 @@
-# MiniMax Speech · 派欧云 PPIO
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-30 |
-| 模态 | 音频（语音合成 + 声音克隆） |
-| 供应商 | 派欧云 PPIO |
-| 平台路由 | `/v3/[async/]minimax-speech-2.8-{hd,turbo}`、`/v3/minimax-voice-cloning` |
-| 接口形态 | 同步与异步双版本；声音克隆为同步 |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
-
-## 1. 能力与价格
-
-| 接口 | 路由 | 价格 |
-|---|---|---|
-| Speech 2.8 HD 同步 | `POST /v3/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
-| Speech 2.8 HD 异步 | `POST /v3/async/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
-| Speech 2.8 Turbo 同步 | `POST /v3/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
-| Speech 2.8 Turbo 异步 | `POST /v3/async/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
-| 声音克隆 | `POST /v3/minimax-voice-cloning` | **¥9.9 / 音色**（试听另计） |
-
-定价页还列着 `MiniMax speech-2.6-hd` ¥3.5/万字符 与 `speech-2.6-turbo` ¥2/万字符，说明 **2.6 仍在售**，但文档站已不再提供 2.6 的 API 参考页，**路由无法确认**（PPIO 对所有未知路径统一返回 400，无法靠探测区分）。
-
-计费字符数以响应里的 `extra_info.usage_characters` 为准。PPIO 公开商品注册表给出的结算表达式为 `(单价 × 字符数 + 999999) / 1000000`，即每次请求按实际字符费**向上取整到人民币分**；不能只做“最低 ¥0.01”而保留分以下的小数。
-
-## 2. 声音克隆 `/v3/minimax-voice-cloning`
-
-### `model` 字段枚举（已核实）
-
-```
-speech-2.6-hd | speech-2.6-turbo | speech-2.8-hd | speech-2.8-turbo
-```
-
-> ⚠️ **该文档页底部的 curl 示例里写的是 `"model": "speech-01-hd"`，那是 PPIO 没同步更新的过期示例，不要照抄。** 以正文参数表的枚举为准。曾有一次排查因为参照了含旧示例的过期资料，误判项目代码写错——项目当前的 4 个枚举值是正确的。
-
-### 参数
-
-| 字段 | 类型 | 必填 | 默认 | 约束 |
-|---|---|---|---|---|
-| `audio_url` | string | ✅ | — | mp3/m4a/wav；时长 10 秒 ~ 5 分钟；≤20MB |
-| `clone_prompt` | object | | — | `{ prompt_audio_url 必填（示例音频 <8s）, prompt_text 必填（对应文本，句末需有标点）}`，提升音色相似度与稳定性 |
-| `text` | string | | — | 复刻试听文本，≤2000 字符 |
-| `model` | string | 传 `text` 时必填 | — | 上述 4 个枚举值 |
-| `accuracy` | float | | `0.7` | 文本校验准确率阈值 `[0, 1]` |
-| `need_noise_reduction` | boolean | | `false` | 降噪 |
-| `need_volume_normalization` | boolean | | `false` | 音量归一化 |
-
-响应：`{ demo_audio_url, voice_id }`
-
-### 两个业务硬约束
-
-1. ⚠️ **仅个人认证 / 企业认证用户可调用**（需实名认证）
-2. ⚠️ **复刻出的是临时音色，必须在 168 小时（7 天）内在任意 T2A 合成接口中实际使用一次（试听不算），否则音色被删除**
-
-### 计费
-
-¥9.9 / 音色。**试听单独计费**——文档明确写「试听将根据字符数正常收取语音合成费用，定价与 T2A 各接口一致」，即传了 `text` 会额外按 HD ¥3.5/万字符或 Turbo ¥2/万字符扣费。试听字符费也按单次请求向上取整到分，再与 ¥9.9 音色费相加；例如 Turbo 60 字符原始金额 ¥0.012，实际计为 ¥0.02，总计 ¥9.92。
-
-## 3. 语音合成（同步）
-
-**模型版本在路由里，请求体没有 `model` 字段。**
-
-| 字段 | 类型 | 必填 | 默认 | 约束 |
-|---|---|---|---|---|
-| `text` | string | ✅ | — | < 10000 字符（>3000 建议流式）；支持换行分段、`<#x#>` 停顿标记、语气词标签 |
-| `stream` | boolean | | `false` | |
-| `output_format` | string | | **`hex`** | `url` / `hex`；仅非流式生效，流式只能 hex；返回的 url 有效期 24 小时 |
-| `voice_setting` | object | | — | 见下 |
-| `audio_setting` | object | | — | 见下 |
-| `voice_modify` | object | | — | `pitch` / `timbre` / `intensity` 各 `[-100, 100]`；`sound_effects` 枚举 `spacious_echo` / `auditorium_echo` / `lofi_telephone` / `robotic`（单次仅一种） |
-| `timber_weights` | object[] | | — | 混合音色 `{ weight 必填 integer, voice_id 必填 string }` |
-| `subtitle_enable` | boolean | | `false` | |
-| `aigc_watermark` | boolean | | `false` | |
-| `language_boost` | string | | `null` | 41 个枚举值（`Chinese`、`Chinese,Yue`、`English`、`Japanese`、…、`auto`） |
-| `pronunciation_dict` | object | | — | `tone` string[]，如 `["燕少飞/(yan4)(shao3)(fei1)", "omg/oh my god"]` |
-| `stream_options` | object | | — | `exclude_aggregated_audio` boolean 默认 false |
-
-### `voice_setting`
-
-| 字段 | 默认 | 约束 |
-|---|---|---|
-| `voice_id` | — | **必填**；系统音色 / 复刻音色 / 文生音色；用混合音色时置空并改用 `timber_weights` |
-| `vol` | `1` | `(0, 10]` |
-| `pitch` | `0` | `[-12, 12]` |
-| `speed` | `1` | `[0.5, 2]` |
-| `emotion` | — | `happy` / `sad` / `angry` / `fearful` / `disgusted` / `surprised` / `calm` / `fluent` / `whisper` |
-| `latex_read` | `false` | |
-| `text_normalization` | `false` | |
-
-> ⚠️ **`emotion` 仅对 `speech-2.6-hd/turbo` 与 `speech-01-hd/turbo` 生效，2.8 系列不支持情绪控制**；其中 `fluent` / `whisper` 仅 2.6 系列生效。项目当前只接了 2.8 路由，因此**情绪参数在当前配置下是无效的**，参数面板不应展示。
-
-### `audio_setting`
-
-| 字段 | 默认 | 约束 |
-|---|---|---|
-| `format` | `mp3` | `mp3` / `pcm` / `flac` / `wav`（wav 仅非流式） |
-| `bitrate` | `128000` | `32000` / `64000` / `128000` / `256000`（仅 mp3 生效） |
-| `channel` | `1` | `1` / `2` |
-| `sample_rate` | `32000` | `8000` / `16000` / `22050` / `24000` / `32000` / `44100` |
-| `force_cbr` | `false` | 仅流式 + mp3 生效 |
-
-### 语气词标签（仅 2.8 系列支持）
-
-```
-(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant)
-(inhale) (exhale) (gasps) (sniffs) (sighs) (snorts) (burps)
-(lip-smacking) (humming) (hissing) (emm) (whistles) (sneezes)
-(crying) (applause)
-```
-
-### 响应
-
-```json
-{
-  "data": { "audio": "...", "status": 2, "subtitle_file": "..." },
-  "trace_id": "...",
-  "base_resp": { "status_code": 0, "status_msg": "success" },
-  "extra_info": {
-    "usage_characters": 100,
-    "audio_length": 1000, "audio_size": 12345, "bitrate": 128000,
-    "word_count": 50, "audio_format": "mp3", "audio_channel": 1,
-    "audio_sample_rate": 32000, "invisible_character_ratio": 0
-  }
-}
-```
-
-`extra_info.usage_characters` 是**计费字符数**。
-
-## 4. 语音合成（异步）—— 与同步有多处差异
-
-本项目走的是异步路由，以下差异必须注意：
-
-| 差异点 | 同步 | 异步 |
-|---|---|---|
-| `stream` / `output_format` / `timber_weights` / `subtitle_enable` / `stream_options` | 有 | **没有** |
-| `text` 上限 | < 10000 字符 | **5 万字符** |
-| `text_file_id` | 无 | **有**，与 `text` 二选一必填；txt <100000 字符 或 zip；zip 内 json 支持 `title`/`content`/`extra` 三字段，三者齐全则产出 3 组共 9 个文件 |
-| `voice_setting` | 可选 | **整个 object 必填** |
-| `voice_setting` 内字段 | `latex_read` / `text_normalization` | **`english_normalization`**（默认 false） |
-| 采样率字段名 | `sample_rate` | **`audio_sample_rate`** |
-| `format` 枚举 | mp3/pcm/flac/wav | mp3/pcm/flac/wav/**pcmu_raw**/**pcmu_wav**/**opus** |
-
-- `pcmu_*` 为 G.711 μ-law 8kHz
-- `opus` 仅支持采样率 8000/12000/16000/24000/48000，其他值会报错
-- ⚠️ `audio_setting.channel` 文档正文写「可选范围 [1,2]，默认值为 1」但 default 标注为 `2`，**文档自相矛盾，建议显式传值**
-
-响应：`{ task_id, details: { usage_characters } }`，再走 `/v3/async/task-result` 取 `audios[].audio_url`。
-
-## 5. 适配要点
-
-- **`emotion` 在 2.8 上不生效**，当前项目只接 2.8 路由，该参数应隐藏或在切到 2.6 时才显示。
-- 同步与异步的字段名不同（`sample_rate` vs `audio_sample_rate`、`text_normalization` vs `english_normalization`），不能共用同一个 builder 分支。
-- 声音克隆的 168 小时失效规则需要在产品侧提示用户，否则会出现「克隆成功但过几天音色不见了」。
-- 声音克隆试听会额外产生 TTS 费用，计价展示应体现 ¥9.9 音色费 + 试听字符费两部分。
-- `audio_url` 字段以 `_url` 结尾 → 走 `public-url` 模式，**声音克隆依赖 KIE API Key**。
-
-## 6. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 声音克隆 | https://ppio.com/docs/models/reference-minimax-voice-cloning | 否 |
-| Speech 2.8 HD 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd | 否 |
-| Speech 2.8 HD 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async | 否 |
-| Speech 2.8 Turbo 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo | 否 |
-| Speech 2.8 Turbo 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo-async | 否 |
-| 定价页（音频 tab） | https://ppio.com/pricing | 否 |
-| 模型注册表（含计费表达式） | https://api-server.ppio.com/v1/product/multimodal-model/list?returnSchema=true | 否 |
+# MiniMax Speech · 派欧云 PPIO
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 模态 | 音频（语音合成 + 声音克隆） |
+| 供应商 | 派欧云 PPIO |
+| 平台路由 | `/v3/[async/]minimax-speech-2.8-{hd,turbo}`、`/v3/minimax-voice-cloning` |
+| 接口形态 | 同步与异步双版本；声音克隆为同步 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+供应商公共协议见 [供应商/派欧云.md](../供应商/派欧云.md)。
+
+## 1. 能力与价格
+
+| 接口 | 路由 | 价格 |
+|---|---|---|
+| Speech 2.8 HD 同步 | `POST /v3/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
+| Speech 2.8 HD 异步 | `POST /v3/async/minimax-speech-2.8-hd` | ¥3.5 / 万字符 |
+| Speech 2.8 Turbo 同步 | `POST /v3/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
+| Speech 2.8 Turbo 异步 | `POST /v3/async/minimax-speech-2.8-turbo` | ¥2.0 / 万字符 |
+| 声音克隆 | `POST /v3/minimax-voice-cloning` | **¥9.9 / 音色**（试听另计） |
+
+定价页还列着 `MiniMax speech-2.6-hd` ¥3.5/万字符 与 `speech-2.6-turbo` ¥2/万字符，说明 **2.6 仍在售**，但文档站已不再提供 2.6 的 API 参考页，**路由无法确认**（PPIO 对所有未知路径统一返回 400，无法靠探测区分）。
+
+计费字符数以响应里的 `extra_info.usage_characters` 为准。PPIO 公开商品注册表给出的结算表达式为 `(单价 × 字符数 + 999999) / 1000000`，即每次请求按实际字符费**向上取整到人民币分**；不能只做“最低 ¥0.01”而保留分以下的小数。
+
+## 2. 声音克隆 `/v3/minimax-voice-cloning`
+
+### `model` 字段枚举（已核实）
+
+```
+speech-2.6-hd | speech-2.6-turbo | speech-2.8-hd | speech-2.8-turbo
+```
+
+> ⚠️ **该文档页底部的 curl 示例里写的是 `"model": "speech-01-hd"`，那是 PPIO 没同步更新的过期示例，不要照抄。** 以正文参数表的枚举为准。曾有一次排查因为参照了含旧示例的过期资料，误判项目代码写错——项目当前的 4 个枚举值是正确的。
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `audio_url` | string | ✅ | — | mp3/m4a/wav；时长 10 秒 ~ 5 分钟；≤20MB |
+| `clone_prompt` | object | | — | `{ prompt_audio_url 必填（示例音频 <8s）, prompt_text 必填（对应文本，句末需有标点）}`，提升音色相似度与稳定性 |
+| `text` | string | | — | 复刻试听文本，≤2000 字符 |
+| `model` | string | 传 `text` 时必填 | — | 上述 4 个枚举值 |
+| `accuracy` | float | | `0.7` | 文本校验准确率阈值 `[0, 1]` |
+| `need_noise_reduction` | boolean | | `false` | 降噪 |
+| `need_volume_normalization` | boolean | | `false` | 音量归一化 |
+
+响应：`{ demo_audio_url, voice_id }`
+
+### 两个业务硬约束
+
+1. ⚠️ **仅个人认证 / 企业认证用户可调用**（需实名认证）
+2. ⚠️ **复刻出的是临时音色，必须在 168 小时（7 天）内在任意 T2A 合成接口中实际使用一次（试听不算），否则音色被删除**
+
+### 计费
+
+¥9.9 / 音色。**试听单独计费**——文档明确写「试听将根据字符数正常收取语音合成费用，定价与 T2A 各接口一致」，即传了 `text` 会额外按 HD ¥3.5/万字符或 Turbo ¥2/万字符扣费。试听字符费也按单次请求向上取整到分，再与 ¥9.9 音色费相加；例如 Turbo 60 字符原始金额 ¥0.012，实际计为 ¥0.02，总计 ¥9.92。
+
+## 3. 语音合成（同步）
+
+**模型版本在路由里，请求体没有 `model` 字段。**
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `text` | string | ✅ | — | < 10000 字符（>3000 建议流式）；支持换行分段、`<#x#>` 停顿标记、语气词标签 |
+| `stream` | boolean | | `false` | |
+| `output_format` | string | | **`hex`** | `url` / `hex`；仅非流式生效，流式只能 hex；返回的 url 有效期 24 小时 |
+| `voice_setting` | object | | — | 见下 |
+| `audio_setting` | object | | — | 见下 |
+| `voice_modify` | object | | — | `pitch` / `timbre` / `intensity` 各 `[-100, 100]`；`sound_effects` 枚举 `spacious_echo` / `auditorium_echo` / `lofi_telephone` / `robotic`（单次仅一种） |
+| `timber_weights` | object[] | | — | 混合音色 `{ weight 必填 integer, voice_id 必填 string }` |
+| `subtitle_enable` | boolean | | `false` | |
+| `aigc_watermark` | boolean | | `false` | |
+| `language_boost` | string | | `null` | 41 个枚举值（`Chinese`、`Chinese,Yue`、`English`、`Japanese`、…、`auto`） |
+| `pronunciation_dict` | object | | — | `tone` string[]，如 `["燕少飞/(yan4)(shao3)(fei1)", "omg/oh my god"]` |
+| `stream_options` | object | | — | `exclude_aggregated_audio` boolean 默认 false |
+
+### `voice_setting`
+
+| 字段 | 默认 | 约束 |
+|---|---|---|
+| `voice_id` | — | **必填**；系统音色 / 复刻音色 / 文生音色；用混合音色时置空并改用 `timber_weights` |
+| `vol` | `1` | `(0, 10]` |
+| `pitch` | `0` | `[-12, 12]` |
+| `speed` | `1` | `[0.5, 2]` |
+| `emotion` | — | `happy` / `sad` / `angry` / `fearful` / `disgusted` / `surprised` / `calm` / `fluent` / `whisper` |
+| `latex_read` | `false` | |
+| `text_normalization` | `false` | |
+
+> ⚠️ **`emotion` 仅对 `speech-2.6-hd/turbo` 与 `speech-01-hd/turbo` 生效，2.8 系列不支持情绪控制**；其中 `fluent` / `whisper` 仅 2.6 系列生效。项目当前只接了 2.8 路由，因此**情绪参数在当前配置下是无效的**，参数面板不应展示。
+
+### `audio_setting`
+
+| 字段 | 默认 | 约束 |
+|---|---|---|
+| `format` | `mp3` | `mp3` / `pcm` / `flac` / `wav`（wav 仅非流式） |
+| `bitrate` | `128000` | `32000` / `64000` / `128000` / `256000`（仅 mp3 生效） |
+| `channel` | `1` | `1` / `2` |
+| `sample_rate` | `32000` | `8000` / `16000` / `22050` / `24000` / `32000` / `44100` |
+| `force_cbr` | `false` | 仅流式 + mp3 生效 |
+
+### 语气词标签（仅 2.8 系列支持）
+
+```
+(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant)
+(inhale) (exhale) (gasps) (sniffs) (sighs) (snorts) (burps)
+(lip-smacking) (humming) (hissing) (emm) (whistles) (sneezes)
+(crying) (applause)
+```
+
+### 响应
+
+```json
+{
+  "data": { "audio": "...", "status": 2, "subtitle_file": "..." },
+  "trace_id": "...",
+  "base_resp": { "status_code": 0, "status_msg": "success" },
+  "extra_info": {
+    "usage_characters": 100,
+    "audio_length": 1000, "audio_size": 12345, "bitrate": 128000,
+    "word_count": 50, "audio_format": "mp3", "audio_channel": 1,
+    "audio_sample_rate": 32000, "invisible_character_ratio": 0
+  }
+}
+```
+
+`extra_info.usage_characters` 是**计费字符数**。
+
+## 4. 语音合成（异步）—— 与同步有多处差异
+
+本项目走的是异步路由，以下差异必须注意：
+
+| 差异点 | 同步 | 异步 |
+|---|---|---|
+| `stream` / `output_format` / `timber_weights` / `subtitle_enable` / `stream_options` | 有 | **没有** |
+| `text` 上限 | < 10000 字符 | **5 万字符** |
+| `text_file_id` | 无 | **有**，与 `text` 二选一必填；txt <100000 字符 或 zip；zip 内 json 支持 `title`/`content`/`extra` 三字段，三者齐全则产出 3 组共 9 个文件 |
+| `voice_setting` | 可选 | **整个 object 必填** |
+| `voice_setting` 内字段 | `latex_read` / `text_normalization` | **`english_normalization`**（默认 false） |
+| 采样率字段名 | `sample_rate` | **`audio_sample_rate`** |
+| `format` 枚举 | mp3/pcm/flac/wav | mp3/pcm/flac/wav/**pcmu_raw**/**pcmu_wav**/**opus** |
+
+- `pcmu_*` 为 G.711 μ-law 8kHz
+- `opus` 仅支持采样率 8000/12000/16000/24000/48000，其他值会报错
+- ⚠️ `audio_setting.channel` 文档正文写「可选范围 [1,2]，默认值为 1」但 default 标注为 `2`，**文档自相矛盾，建议显式传值**
+
+响应：`{ task_id, details: { usage_characters } }`，再走 `/v3/async/task-result` 取 `audios[].audio_url`。
+
+## 5. 适配要点
+
+- **`emotion` 在 2.8 上不生效**，当前项目只接 2.8 路由，该参数应隐藏或在切到 2.6 时才显示。
+- 同步与异步的字段名不同（`sample_rate` vs `audio_sample_rate`、`text_normalization` vs `english_normalization`），不能共用同一个 builder 分支。
+- 声音克隆的 168 小时失效规则需要在产品侧提示用户，否则会出现「克隆成功但过几天音色不见了」。
+- 声音克隆试听会额外产生 TTS 费用，计价展示应体现 ¥9.9 音色费 + 试听字符费两部分。
+- `audio_url` 字段以 `_url` 结尾 → 走 `public-url` 模式，**声音克隆依赖 KIE API Key**。
+
+## 6. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 声音克隆 | https://ppio.com/docs/models/reference-minimax-voice-cloning | 否 |
+| Speech 2.8 HD 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd | 否 |
+| Speech 2.8 HD 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-hd-async | 否 |
+| Speech 2.8 Turbo 同步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo | 否 |
+| Speech 2.8 Turbo 异步 | https://ppio.com/docs/models/reference-minimax-speech-2.8-turbo-async | 否 |
+| 定价页（音频 tab） | https://ppio.com/pricing | 否 |
+| 模型注册表（含计费表达式） | https://api-server.ppio.com/v1/product/multimodal-model/list?returnSchema=true | 否 |

package/docs/model-adaptation/Nano-Banana-2/Nano-Banana-2_APIMart.md

@@ -1,89 +1,89 @@
-# Nano Banana 2 · APIMart
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-28 |
-| 模态 | 图片 |
-| 供应商 | APIMart（聚合平台） |
-| 平台模型 ID | 标准版 `gemini-3.1-flash-image-preview`（别名 `nano-banana-2-ext`）<br>官方版 `gemini-3.1-flash-image-preview-official`（别名 `nano-banana-2`） |
-| 接口形态 | **异步任务** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-> **Nano Banana 2 Lite 已拆分为独立文档**：[Nano-Banana-2-Lite_APIMart.md](../Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md)。它在代码里对应独立的 `canonicalModelId: nano-banana-2-lite`（[catalog/apimart/nano-banana-2-lite.model.ts](../../../src/catalog/apimart/nano-banana-2-lite.model.ts)），是独立产品模型，不是本模型的渠道或分辨率选项——本文件只覆盖主模型的标准版 / 官方版两条渠道。
-
----
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.apimart.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
-- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
-- **回调**（仅 Lite 文档明确提供）：`webhook` 参数传 base 地址，平台回调 `webhook + /callback`（不转发上游），仍建议保留轮询兜底
-
----
-
-## 2. 主模型 `gemini-3.1-flash-image-preview` / `-official`
-
-### 2.1 能力
-
-文生图 / 图生图；最多 **14 张**参考图；最高 **4K**；支持**极端宽高比**（1:4、4:1、1:8、8:1）；集成 **Google Search 搜索增强**。
-
-### 2.2 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | `gemini-3.1-flash-image-preview` | 标准版 `gemini-3.1-flash-image-preview`（别名 `nano-banana-2-ext`）；官方版 `gemini-3.1-flash-image-preview-official`（别名 `nano-banana-2`） |
-| `prompt` | string | 必填 | — | 图像生成描述 |
-| `size` | string | 可选 | — | `auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`5:4`、`4:5`、`21:9`、`1:4`、`4:1`、`1:8`、`8:1`。**`auto` 时文生图默认 `1:1` 或 `16:9`；图生图按上游返回比例为准——建议始终显式指定** |
-| `resolution` | string | 可选 | `1K` | `0.5K`（约 512px）/ `1K`（约 1024px）/ `2K`（约 2048px）/ `4K`（约 4096px）。**不同分辨率计费不同** |
-| `n` | integer | 可选 | `1` | **取值只能是 1**。必须传纯数字 |
-| `image_urls` | array | 可选 | — | 参考图。**最多 14 张**（建议最多 10 张物体参考 + 4 张角色参考）；单张 ≤ 10 MB；格式 jpeg/png/webp；支持公网 URL 或完整 Data URI（前缀不能省） |
-| `google_search` | boolean | 可选 | `false` | Google **文字**搜索增强，适合需要真实信息的场景 |
-| `google_image_search` | boolean | 可选 | `false` | Google **图片**搜索增强。**必须配合 `google_search: true`** |
-| `official_fallback` | boolean | 可选 | `false` | 官方渠道兜底。**使用 `-official` 模型时不能带此参数** |
-| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
-
-### 2.3 价格
-
-来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与[Nano Banana 3 模型页](https://apimart.ai/zh/model/nano-banana-3-api)（2026-08-28，1 Credit ≈ $0.1）。
-
-**NANO-BANANA-2-EXT**（按张，5 档）
-
-| 规格 | 我们的价格 | 官方价 | 节省 |
-|---|---|---|---|
-| 默认 / 0.5K / 1K | 0.15 Credits/张 ≈ **$0.015/张** | $0.01875 | 20% |
-| 2K | 0.2 Credits/张 ≈ **$0.02/张** | $0.025 | 20% |
-| 4K | 0.25 Credits/张 ≈ **$0.025/张** | $0.03125 | 20% |
-
-**NANO-BANANA-2**（官方渠道，按 token）
-
-| 计费项 | 我们的价格 | 官方价 |
-|---|---|---|
-| 文本输入 | 4 Credits/M ≈ $0.4/M | $0.5/M |
-| 图片输入 | 4 Credits/M ≈ $0.4/M | $0.5/M |
-| 文本输出 | 24 Credits/M ≈ $2.4/M | $3/M |
-| 图片输出 | 480 Credits/M ≈ **$48/M** | $60/M |
-
-SDK 对官方渠道采用模型页给出的当前单张估算：0.5K/1K **$0.0536**、2K **$0.0808**、4K **$0.1208**；实际账单仍按 token 结算。
-
----
-
-## 3. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 这两个渠道都没有这两个字段。
-- 主模型 `n` 只能是 1；`n` 必须是数字类型。
-- `size: auto` 在文生图与图生图下行为不同，建议永远显式下发比例。
-- `google_image_search` 依赖 `google_search`，两者要做联动。
-- SDK 用首位 `apimartNanoBanana2Channel` 参数表达渠道，默认 `standard` 保持 0.1.5 的 EXT 请求；`official` 只切换为精确官方模型 ID，不发送 `official_fallback`。
-- Lite 版本不要并入本模型：分辨率档位、比例集合、`n` 上限、搜索增强、计费方式都不同，是独立产品，见 [Nano-Banana-2-Lite_APIMart.md](../Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md)。
-
-## 4. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Nano banana2 图像生成（主模型） | https://docs.apimart.ai/cn/api-reference/images/gemini-3.1-flash/generation | 否 |
-| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
-| 定价中心（搜 NANO-BANANA-2-EXT / NANO-BANANA-2） | https://apimart.ai/zh/pricing | 否 |
-| API Key 管理 | https://apimart.ai/keys | **是** |
+# Nano Banana 2 · APIMart
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 模态 | 图片 |
+| 供应商 | APIMart（聚合平台） |
+| 平台模型 ID | 标准版 `gemini-3.1-flash-image-preview`（别名 `nano-banana-2-ext`）<br>官方版 `gemini-3.1-flash-image-preview-official`（别名 `nano-banana-2`） |
+| 接口形态 | **异步任务** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> **Nano Banana 2 Lite 已拆分为独立文档**：[Nano-Banana-2-Lite_APIMart.md](../Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md)。它在代码里对应独立的 `canonicalModelId: nano-banana-2-lite`（[catalog/apimart/nano-banana-2-lite.model.ts](../../../src/catalog/apimart/nano-banana-2-lite.model.ts)），是独立产品模型，不是本模型的渠道或分辨率选项——本文件只覆盖主模型的标准版 / 官方版两条渠道。
+
+---
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.apimart.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /v1/images/generations` → `{ code, data: [{ status: "submitted", task_id }] }`
+- **查询**：`GET /v1/tasks/{task_id}`，读 `result.images`
+- **回调**（仅 Lite 文档明确提供）：`webhook` 参数传 base 地址，平台回调 `webhook + /callback`（不转发上游），仍建议保留轮询兜底
+
+---
+
+## 2. 主模型 `gemini-3.1-flash-image-preview` / `-official`
+
+### 2.1 能力
+
+文生图 / 图生图；最多 **14 张**参考图；最高 **4K**；支持**极端宽高比**（1:4、4:1、1:8、8:1）；集成 **Google Search 搜索增强**。
+
+### 2.2 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | `gemini-3.1-flash-image-preview` | 标准版 `gemini-3.1-flash-image-preview`（别名 `nano-banana-2-ext`）；官方版 `gemini-3.1-flash-image-preview-official`（别名 `nano-banana-2`） |
+| `prompt` | string | 必填 | — | 图像生成描述 |
+| `size` | string | 可选 | — | `auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`、`5:4`、`4:5`、`21:9`、`1:4`、`4:1`、`1:8`、`8:1`。**`auto` 时文生图默认 `1:1` 或 `16:9`；图生图按上游返回比例为准——建议始终显式指定** |
+| `resolution` | string | 可选 | `1K` | `0.5K`（约 512px）/ `1K`（约 1024px）/ `2K`（约 2048px）/ `4K`（约 4096px）。**不同分辨率计费不同** |
+| `n` | integer | 可选 | `1` | **取值只能是 1**。必须传纯数字 |
+| `image_urls` | array | 可选 | — | 参考图。**最多 14 张**（建议最多 10 张物体参考 + 4 张角色参考）；单张 ≤ 10 MB；格式 jpeg/png/webp；支持公网 URL 或完整 Data URI（前缀不能省） |
+| `google_search` | boolean | 可选 | `false` | Google **文字**搜索增强，适合需要真实信息的场景 |
+| `google_image_search` | boolean | 可选 | `false` | Google **图片**搜索增强。**必须配合 `google_search: true`** |
+| `official_fallback` | boolean | 可选 | `false` | 官方渠道兜底。**使用 `-official` 模型时不能带此参数** |
+| `nsfw_check` | boolean | 可选 | `false` | `true` 时用 `omni-moderation-latest` 预审 |
+
+### 2.3 价格
+
+来源：[APIMart 定价中心](https://apimart.ai/zh/pricing)与[Nano Banana 3 模型页](https://apimart.ai/zh/model/nano-banana-3-api)（2026-08-28，1 Credit ≈ $0.1）。
+
+**NANO-BANANA-2-EXT**（按张，5 档）
+
+| 规格 | 我们的价格 | 官方价 | 节省 |
+|---|---|---|---|
+| 默认 / 0.5K / 1K | 0.15 Credits/张 ≈ **$0.015/张** | $0.01875 | 20% |
+| 2K | 0.2 Credits/张 ≈ **$0.02/张** | $0.025 | 20% |
+| 4K | 0.25 Credits/张 ≈ **$0.025/张** | $0.03125 | 20% |
+
+**NANO-BANANA-2**（官方渠道，按 token）
+
+| 计费项 | 我们的价格 | 官方价 |
+|---|---|---|
+| 文本输入 | 4 Credits/M ≈ $0.4/M | $0.5/M |
+| 图片输入 | 4 Credits/M ≈ $0.4/M | $0.5/M |
+| 文本输出 | 24 Credits/M ≈ $2.4/M | $3/M |
+| 图片输出 | 480 Credits/M ≈ **$48/M** | $60/M |
+
+SDK 对官方渠道采用模型页给出的当前单张估算：0.5K/1K **$0.0536**、2K **$0.0808**、4K **$0.1208**；实际账单仍按 token 结算。
+
+---
+
+## 3. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。APIMart 这两个渠道都没有这两个字段。
+- 主模型 `n` 只能是 1；`n` 必须是数字类型。
+- `size: auto` 在文生图与图生图下行为不同，建议永远显式下发比例。
+- `google_image_search` 依赖 `google_search`，两者要做联动。
+- SDK 用首位 `apimartNanoBanana2Channel` 参数表达渠道，默认 `standard` 保持 0.1.5 的 EXT 请求；`official` 只切换为精确官方模型 ID，不发送 `official_fallback`。
+- Lite 版本不要并入本模型：分辨率档位、比例集合、`n` 上限、搜索增强、计费方式都不同，是独立产品，见 [Nano-Banana-2-Lite_APIMart.md](../Nano-Banana-2-Lite/Nano-Banana-2-Lite_APIMart.md)。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Nano banana2 图像生成（主模型） | https://docs.apimart.ai/cn/api-reference/images/gemini-3.1-flash/generation | 否 |
+| 获取任务状态 | https://docs.apimart.ai/cn/api-reference/tasks/status | 否 |
+| 定价中心（搜 NANO-BANANA-2-EXT / NANO-BANANA-2） | https://apimart.ai/zh/pricing | 否 |
+| API Key 管理 | https://apimart.ai/keys | **是** |