dsh-audiogen 0.3.0 → 0.3.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-audiogen",
   "description": "AI audio generation plugin for the dsh web GUI: multi-vendor TTS/music/sound-effect channels (OpenAI-compatible, ElevenLabs, MiniMax, Stability AI and custom), per-channel model/voice catalogs, Agent tool and a sidebar AI 音频 panel.",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/skills/music/SKILL.md

@@ -2,15 +2,38 @@
 
 ## 触发
 - `/audio:music <描述>`
-- 用户说“生成一段音乐 / 配乐 / BGM”
+- 用户说“生成一段音乐 / 配乐 / BGM / 纯音乐”
 
 ## 参数
 - prompt: 必填，风格/情绪/乐器/时长描述
-- model: 可选，已配置的音频模型
-- duration: 可选，秒数
-- format: 可选，mp3 / wav
+- model: 可选，已配置的音频模型（MiniMax：music-3.0 / music-2.6 / music-cover）
+- lyrics: 可选，歌词；**MiniMax music-3.0 / music-cover 必填**（除非 is_instrumental=true）；多段用空行分隔
+- is_instrumental: 可选，是否纯音乐（无歌词/人声），true 时 lyrics 可留空
+- duration: 可选，秒数（MiniMax 一般 5-120s）
+- format: 可选，MiniMax 音乐仅 mp3 / wav / pcm
 
 ## 流程
-1. 确认已配置支持音乐生成的渠道（如 Stability Audio / 自定义）。
-2. 调用 `generate_audio`，mode=music。
-3. 将生成的音频 URL 返回给用户。
+1. 确认已配置支持音乐生成的渠道（如 MiniMax / Stability Audio / 自定义）。
+2. 若用户未给歌词且未要求纯音乐：对 MiniMax 渠道先创作/补全一段歌词再调用。
+3. 调用 `generate_audio`，mode=music。
+4. 将生成的音频 URL 返回给用户。
+
+## MiniMax 官方 music_generation 字段参考（POST /v1/music_generation）
+
+| 字段 | 工具参数 | 说明 |
+| --- | --- | --- |
+| model | model | music-3.0 / music-2.6 / music-cover |
+| prompt | prompt | 音乐风格/情绪/乐器描述（≤3000 字） |
+| lyrics | lyrics | 歌词；多段用空行分隔；纯音乐模式可留空 |
+| is_instrumental | is_instrumental | 默认 false；true = 纯音乐（无歌词/人声），此时 lyrics 可省 |
+| duration | duration | 生成时长（秒） |
+| audio_setting.format | format | **mp3 / wav / pcm**（仅此三种） |
+| audio_setting.sample_rate | sample_rate | **16000 / 24000 / 32000 / 44100**（无 48000） |
+| audio_setting.bitrate | bitrate | **32000 / 64000 / 128000 / 256000** |
+
+> 引擎对音乐 audio_setting 按上述枚举校验，超出枚举的取值自动回退默认（format=mp3、sample_rate=44100、bitrate=256000）。
+> 若不加 lyrics 也未开启纯音乐，引擎会直接提示 `lyrics-required`（MiniMax 上游返回 2013 lyrics is required）。
+
+## 常见错误
+- `lyrics-required`：MiniMax 音乐生成需要歌词，或开启纯音乐。
+- `HTTP 400` 且含 `2013`：上游参数不合法，检查 lyrics / audio_setting 枚举。

package/skills/tts/SKILL.md

@@ -6,13 +6,51 @@
 
 ## 参数
 - text: 必填，要朗读的文本
-- model: 可选，已配置的模型/音色
-- voice: 可选，音色
-- speed: 可选，语速倍率
-- format: 可选，mp3 / wav 等
+- model: 可选，已配置的模型/音色（MiniMax 为 speech-2.6/2.8 系列）
+- voice: 可选，音色；**MiniMax 必填**（voice_id，如 male-qn-qingse、female-shaonv）
+- speed: 可选，语速倍率（MiniMax 0.5-2.0，默认 1）
+- format: 可选，mp3 / wav / flac / aac / pcm
 
 ## 流程
 1. 确认已配置音频渠道（设置 → 插件 → AI 音频）。
 2. 若用户未指定模型且有多个，先询问。
 3. 调用 `generate_audio` 工具，mode=tts。
 4. 把返回的音频 URL 提供给用户，可播放/下载。
+
+## MiniMax 官方 t2a_v2 字段参考（POST /v1/t2a_v2）
+
+引擎按官方协议逐字段透传（无值时不发送）；以下字段均可在 `generate_audio` 中按需传入（仅 MiniMax 渠道生效）：
+
+| 字段 | 工具参数 | 说明 |
+| --- | --- | --- |
+| model | model | 模型：speech-2.8-hd / speech-2.8-turbo / speech-2.6-hd / speech-2.6-turbo / speech-02-hd / speech-02-turbo |
+| text | prompt | 文本，支持 (laughs) 等标签 |
+| stream | — | 固定 false（引擎非流式消费） |
+| voice_setting.voice_id | voice | **必填**音色；账号音色可在设置中「获取可用模型」拉取 |
+| voice_setting.speed | speed | 0.5-2.0，默认 1 |
+| voice_setting.vol | vol | 音量 0-10，默认 1 |
+| voice_setting.pitch | pitch | 音调偏移 -12~12，默认 0 |
+| voice_setting.emotion | emotion | 情绪：happy / sad / angry / nervous / fearful / bored 等 |
+| voice_setting.text_normalization | text_normalization | 文本归一化开关 |
+| voice_setting.latex_read | latex_read | 数学公式朗读开关 |
+| pronunciation_dict.tone | pronunciation_tone | 发音词典条目数组，如 ["处理/(chu3)(li3)", "危险/dangerous"]（每项 "文字/读音"） |
+| audio_setting.format | format | mp3 / wav / pcm，默认 mp3 |
+| audio_setting.sample_rate | sample_rate | 16000/24000/32000/44100/48000，默认 32000 |
+| audio_setting.bitrate | bitrate | 64000-320000，默认 128000 |
+| audio_setting.channel | channel | 1 或 2，默认 1 |
+| audio_setting.force_cbr | force_cbr | 强制 CBR 编码 |
+| subtitle_enable | subtitle_enable | 生成字幕（响应携带字幕内容） |
+| aigc_watermark | aigc_watermark | AIGC 水印 |
+| language_boost | language_boost | 语言增强（模型相关，如中英混读） |
+| voice_modify | voice_modify | 变声 {pitch, intensity, timbre, sound_effects}（speech-2.8 等支持） |
+| timbre_weights | timbre_weights | 双音色混合 [{voice_id, weight}] |
+
+### 网关/代理渠道
+- 官方默认地址 `https://api.minimaxi.com`（原生 `/v1/t2a_v2`，字段全量支持）。
+- 若渠道配置为 New API 一类网关（只暴露 OpenAI 兼容 `/v1/audio/speech`，对 `/v1/t2a_v2` 返回 404 Invalid URL），引擎会自动回退到 `/v1/audio/speech`，并把上述官方字段放进 `metadata` 供网关合并转发；此类网关的字段支持取决于其实现。
+- 回退也失败时，错误信息会同时给出两种端点与排查建议。
+
+### 常见错误
+- `voice-required`：未选择音色，需传 voice（voice_id）。
+- HTTP 404 Invalid URL：网关未路由 `/v1/t2a_v2`（已自动回退）。
+- `HTTP 400` 且 base_resp.status_code 非 0：上游参数不合法（如 emotion 不受该音色支持）。

package/src/agent-audio-tools.ts

@@ -105,11 +105,51 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       prompt: { type: 'string', required: true, description: 'For tts, the text to speak. For music/sfx, a descriptive prompt.' },
       mode: { type: 'string', enum: ['tts', 'music', 'sfx', 'voice_design'], description: 'Generation mode. Defaults to tts.' },
       model: { type: 'string', description: 'One of the configured audio models/voices. Defaults to the first configured model.' },
-      voice: { type: 'string', description: 'Optional voice id/name for TTS providers.' },
+      voice: { type: 'string', description: 'Optional voice id/name for TTS providers. Required for MiniMax TTS (e.g. male-qn-qingse, female-shaonv); fetch the account voices in Settings > Plugins > AI Audio.' },
       preview_text: { type: 'string', description: 'Optional preview text for voice_design.' },
-      speed: { type: 'number', description: 'Optional speaking rate / speed multiplier where supported.' },
+      speed: { type: 'number', description: 'Optional speaking rate / speed multiplier where supported. MiniMax range 0.5-2.0 (default 1).' },
       duration: { type: 'number', description: 'Requested duration in seconds for music/sfx.' },
-      format: { type: 'string', description: 'Output format such as mp3 or wav.' },
+      lyrics: { type: 'string', description: 'Lyrics for music generation (MiniMax music-3.0/music-cover). Required unless is_instrumental is true. Split verses with an empty line.' },
+      is_instrumental: { type: 'boolean', description: 'Generate purely instrumental music without vocals/lyrics (MiniMax is_instrumental). When true, lyrics may be omitted.' },
+      format: { type: 'string', description: 'Output format such as mp3 or wav. MiniMax music supports mp3/wav/pcm.' },
+      // ---- MiniMax TTS only (ignored by other providers) ----
+      emotion: { type: 'string', description: 'MiniMax TTS emotion, e.g. happy/sad/angry/nervous/fearful/bored (voice_setting.emotion).' },
+      vol: { type: 'number', description: 'MiniMax TTS volume 0-10, default 1 (voice_setting.vol).' },
+      pitch: { type: 'integer', description: 'MiniMax TTS pitch shift -12..12 semitones, default 0 (voice_setting.pitch).' },
+      text_normalization: { type: 'boolean', description: 'MiniMax TTS text normalization switch (voice_setting.text_normalization).' },
+      latex_read: { type: 'boolean', description: 'MiniMax TTS math formula reading switch (voice_setting.latex_read).' },
+      pronunciation_tone: { type: 'array', items: { type: 'string' }, description: 'MiniMax TTS pronunciation dictionary tone entries, each "word/pronunciation", e.g. ["处理/(chu3)(li3)", "危险/dangerous"] (pronunciation_dict.tone).' },
+      sample_rate: { type: 'integer', description: 'MiniMax TTS sample rate: 16000/24000/32000/44100/48000, default 32000 (audio_setting.sample_rate).' },
+      bitrate: { type: 'integer', description: 'MiniMax TTS bitrate in bps: 64000-320000, default 128000 (audio_setting.bitrate).' },
+      channel: { type: 'integer', description: 'MiniMax TTS audio channels: 1 or 2, default 1 (audio_setting.channel).' },
+      force_cbr: { type: 'boolean', description: 'MiniMax TTS force CBR encoding (audio_setting.force_cbr).' },
+      subtitle_enable: { type: 'boolean', description: 'MiniMax TTS subtitle output switch (subtitle_enable).' },
+      aigc_watermark: { type: 'boolean', description: 'MiniMax TTS AIGC watermark switch (aigc_watermark).' },
+      language_boost: { type: 'string', description: 'MiniMax TTS language boost, e.g. 中英混读 (language_boost, model-dependent).' },
+      voice_modify: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          pitch: { type: 'integer', description: 'Pitch shift for voice modification.' },
+          intensity: { type: 'integer', description: 'Intensity for voice modification.' },
+          timbre: { type: 'integer', description: 'Timbre shift for voice modification.' },
+          sound_effects: { type: 'string', description: 'Sound effect for voice modification, e.g. 耳语.' },
+        },
+        description: 'MiniMax TTS voice modification (voice_modify, supported by speech-2.8+).',
+      },
+      timbre_weights: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            voice_id: { type: 'string' },
+            weight: { type: 'integer' },
+          },
+          required: ['voice_id', 'weight'],
+        },
+        description: 'MiniMax TTS dual-voice blend weights (timbre_weights).',
+      },
     },
     output: {
       schema: resultSchema,
@@ -129,6 +169,23 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
           return { channel: target, alias: '', upstream: '' }
         })()
         : resolveModel(config, args.model)
+      const voiceModify = typeof args.voice_modify === 'object' && args.voice_modify !== null
+        ? (() => {
+          const raw = args.voice_modify as Record<string, unknown>
+          const out: { pitch?: number; intensity?: number; timbre?: number; soundEffects?: string } = {}
+          if (typeof raw.pitch === 'number') out.pitch = raw.pitch
+          if (typeof raw.intensity === 'number') out.intensity = raw.intensity
+          if (typeof raw.timbre === 'number') out.timbre = raw.timbre
+          if (typeof raw.sound_effects === 'string' && raw.sound_effects.trim() !== '') out.soundEffects = raw.sound_effects.trim()
+          return Object.keys(out).length > 0 ? out : undefined
+        })()
+        : undefined
+      const timbreWeights = Array.isArray(args.timbre_weights)
+        ? args.timbre_weights
+          .filter((item): item is { voice_id: string; weight: number } => typeof item === 'object' && item !== null && typeof (item as { voice_id?: unknown }).voice_id === 'string' && typeof (item as { weight?: unknown }).weight === 'number')
+          .map(item => ({ voiceId: (item.voice_id as string).trim(), weight: item.weight as number }))
+          .filter(item => item.voiceId !== '')
+        : undefined
       const request: GenerateAudioRequest = {
         mode,
         model: picked.alias,
@@ -140,7 +197,27 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
         ...(typeof args.preview_text === 'string' && args.preview_text.trim() !== '' ? { previewText: args.preview_text.trim() } : {}),
         ...(typeof args.speed === 'number' ? { speed: args.speed } : {}),
         ...(typeof args.duration === 'number' ? { duration: args.duration } : {}),
+        ...(typeof args.lyrics === 'string' && args.lyrics.trim() !== '' ? { lyrics: args.lyrics.trim() } : {}),
+        ...(typeof args.is_instrumental === 'boolean' ? { isInstrumental: args.is_instrumental } : {}),
         ...(typeof args.format === 'string' && args.format.trim() !== '' ? { format: args.format.trim() } : {}),
+        // ---- MiniMax TTS 专属字段 ----
+        ...(typeof args.emotion === 'string' && args.emotion.trim() !== '' ? { emotion: args.emotion.trim() } : {}),
+        ...(typeof args.vol === 'number' && Number.isFinite(args.vol) ? { vol: args.vol } : {}),
+        ...(typeof args.pitch === 'number' && Number.isFinite(args.pitch) ? { pitch: args.pitch } : {}),
+        ...(typeof args.text_normalization === 'boolean' ? { textNormalization: args.text_normalization } : {}),
+        ...(typeof args.latex_read === 'boolean' ? { latexRead: args.latex_read } : {}),
+        ...(Array.isArray(args.pronunciation_tone) && args.pronunciation_tone.length > 0
+          ? { pronunciationTone: args.pronunciation_tone.filter((item): item is string => typeof item === 'string' && item.trim() !== '').map((item: string) => item.trim()) }
+          : {}),
+        ...(typeof args.sample_rate === 'number' && Number.isFinite(args.sample_rate) ? { sampleRate: args.sample_rate } : {}),
+        ...(typeof args.bitrate === 'number' && Number.isFinite(args.bitrate) ? { bitrate: args.bitrate } : {}),
+        ...(typeof args.channel === 'number' && Number.isFinite(args.channel) ? { audioChannel: args.channel } : {}),
+        ...(typeof args.force_cbr === 'boolean' ? { forceCbr: args.force_cbr } : {}),
+        ...(typeof args.subtitle_enable === 'boolean' ? { subtitleEnable: args.subtitle_enable } : {}),
+        ...(typeof args.aigc_watermark === 'boolean' ? { aigcWatermark: args.aigc_watermark } : {}),
+        ...(typeof args.language_boost === 'string' && args.language_boost.trim() !== '' ? { languageBoost: args.language_boost.trim() } : {}),
+        ...(voiceModify !== undefined ? { voiceModify } : {}),
+        ...(timbreWeights !== undefined && timbreWeights.length > 0 ? { timbreWeights } : {}),
       }
       try {
         const outputs = await generateAudio(picked.channel, request, exec.signal)

package/src/audio-engine.ts

@@ -124,7 +124,7 @@ function findBase64Audio(value: unknown): string | undefined {
   }
   if (value === null || typeof value !== 'object') return undefined
   const record = value as Record<string, unknown>
-  for (const key of ['audio', 'b64_json', 'base64', 'data', 'output', 'result', 'value']) {
+  for (const key of ['audio', 'music', 'b64_json', 'base64', 'data', 'output', 'result', 'value']) {
     const candidate = record[key]
     const found = findBase64Audio(candidate)
     if (found !== undefined) return found
@@ -274,10 +274,127 @@ function minimaxApiBase(base: string): string {
   return /\/v1$/i.test(trimmed) ? trimmed : `${trimmed}/v1`
 }
 
+/**
+ * Resolve the MiniMax voice_id for a TTS request.
+ * Priority: explicit voice param → upstream id (if it is not a model name) →
+ * model alias (if it is not a model name). MiniMax speech/music model ids
+ * (speech-2.8-hd, music-3.0, …) are never treated as voice ids.
+ */
+function resolveMiniMaxVoice(request: GenerateAudioRequest): string | undefined {
+  const explicit = request.voice?.trim()
+  if (explicit !== undefined && explicit !== '') return explicit
+  for (const candidate of [request.upstream, request.model]) {
+    const value = typeof candidate === 'string' ? candidate.trim() : ''
+    if (value === '') continue
+    if (/^(speech|music|t2a|tts)[-_]/i.test(value)) continue
+    return value
+  }
+  return undefined
+}
+
+/**
+ * Build the full MiniMax t2a_v2 body. Every official field is carried
+ * through — voice_setting (voice_id/speed/vol/pitch/emotion/text_normalization/
+ * latex_read), pronunciation_dict.tone, audio_setting (format/sample_rate/
+ * bitrate/channel/force_cbr), subtitle_enable, aigc_watermark, language_boost,
+ * voice_modify and timbre_weights — so callers and skills can reference them.
+ */
+function buildMiniMaxTTSBody(request: GenerateAudioRequest, model: string, voiceId: string): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    model,
+    text: request.prompt,
+    stream: false,
+    voice_setting: {
+      voice_id: voiceId,
+      speed: request.speed ?? 1,
+      vol: request.vol ?? 1,
+      pitch: request.pitch ?? 0,
+      ...(request.emotion !== undefined && request.emotion.trim() !== '' ? { emotion: request.emotion.trim() } : {}),
+      ...(request.textNormalization !== undefined ? { text_normalization: request.textNormalization } : {}),
+      ...(request.latexRead !== undefined ? { latex_read: request.latexRead } : {}),
+    },
+    audio_setting: {
+      format: request.format ?? 'mp3',
+      sample_rate: request.sampleRate ?? 32000,
+      bitrate: request.bitrate ?? 128000,
+      channel: request.audioChannel ?? 1,
+      ...(request.forceCbr !== undefined ? { force_cbr: request.forceCbr } : {}),
+    },
+  }
+  if (request.pronunciationTone !== undefined && request.pronunciationTone.length > 0) {
+    body.pronunciation_dict = { tone: request.pronunciationTone }
+  }
+  if (request.subtitleEnable !== undefined) body.subtitle_enable = request.subtitleEnable
+  if (request.aigcWatermark !== undefined) body.aigc_watermark = request.aigcWatermark
+  if (request.languageBoost !== undefined && request.languageBoost.trim() !== '') {
+    body.language_boost = request.languageBoost.trim()
+  }
+  if (request.voiceModify !== undefined) {
+    const modify: Record<string, unknown> = {}
+    if (request.voiceModify.pitch !== undefined) modify.pitch = request.voiceModify.pitch
+    if (request.voiceModify.intensity !== undefined) modify.intensity = request.voiceModify.intensity
+    if (request.voiceModify.timbre !== undefined) modify.timbre = request.voiceModify.timbre
+    if (request.voiceModify.soundEffects !== undefined && request.voiceModify.soundEffects.trim() !== '') {
+      modify.sound_effects = request.voiceModify.soundEffects.trim()
+    }
+    if (Object.keys(modify).length > 0) body.voice_modify = modify
+  }
+  if (request.timbreWeights !== undefined && request.timbreWeights.length > 0) {
+    body.timbre_weights = request.timbreWeights
+      .filter(item => typeof item?.voiceId === 'string' && item.voiceId.trim() !== '' && typeof item.weight === 'number')
+      .map(item => ({ voice_id: item.voiceId.trim(), weight: item.weight }))
+  }
+  return body
+}
+
+/** The MiniMax-specific fields only (model/text/stream excluded) — used as the
+ *  new-api `metadata` payload when a gateway serves MiniMax TTS at /v1/audio/speech.
+ *  The merge keeps the gateway-sent model/input, and voice_setting.voice_id is
+ *  carried explicitly so relays that overwrite it still get the right voice. */
+function buildMiniMaxTTSUpload(request: GenerateAudioRequest, voiceId: string): Record<string, unknown> {
+  const upload = buildMiniMaxTTSBody(request, '', voiceId)
+  delete upload.model
+  delete upload.text
+  delete upload.stream
+  return upload
+}
+
+/**
+ * OpenAI-compatible MiniMax TTS path for New API style gateways that do not
+ * route the native /v1/t2a_v2. The full native field set is carried inside
+ * `metadata`, which new-api's MiniMax TTS relay merges into t2a_v2 upstream.
+ */
+async function minimaxTTSGateway(channel: AudioChannel, request: GenerateAudioRequest, signal: AbortSignal | undefined, voiceId: string): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const base = minimaxApiBase(channel.apiUrl)
+  const endpoint = `${base}/audio/speech`
+  const model = (request.upstream ?? request.model) || 'speech-2.8-hd'
+  const metadata = buildMiniMaxTTSUpload(request, voiceId)
+  const body: Record<string, unknown> = {
+    model,
+    input: request.prompt,
+    voice: voiceId,
+    response_format: request.format ?? 'mp3',
+    ...(request.speed !== undefined ? { speed: request.speed } : {}),
+    ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    // Gateways may answer with a redirect to the real audio URL — follow it.
+    redirect: 'follow',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      'content-type': 'application/json',
+      accept: 'application/json, audio/mpeg',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
 async function minimax(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = minimaxApiBase(channel.apiUrl)
   const model = (request.upstream ?? request.model) || (request.mode === 'music' ? 'music-3.0' : 'speech-2.8-hd')
-  const voice = request.voice ?? request.model ?? ''
 
   if (request.mode === 'voice_design') {
     const endpoint = `${base}/voice_design`
@@ -319,40 +436,62 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
     }]
   }
 
-  let endpoint: string
-  let body: Record<string, unknown>
   if (request.mode === 'music') {
-    endpoint = `${base}/music_generation`
-    body = {
+    // MiniMax 音乐生成官方字段：model/lyrics/prompt/is_instrumental/duration/
+    // audio_setting{format, sample_rate, bitrate}。音频输出配置为固定枚举：
+    // format mp3|wav|pcm；sample_rate 16000|24000|32000|44100；
+    // bitrate 32000|64000|128000|256000，超出枚举的值回退默认。
+    const MUSIC_FORMATS = new Set(['mp3', 'wav', 'pcm'])
+    const MUSIC_SAMPLE_RATES = new Set([16000, 24000, 32000, 44100])
+    const MUSIC_BITRATES = new Set([32000, 64000, 128000, 256000])
+    const lyrics = request.lyrics?.trim() ?? ''
+    if (lyrics === '' && request.isInstrumental !== true) {
+      throw new AudioGenError(
+        'MiniMax 音乐生成需要歌词（lyrics 参数），或在「纯音乐」模式（is_instrumental=true）下生成；也可让面板/Agent 先为提示词创作一段歌词。',
+        'lyrics-required',
+      )
+    }
+    const endpoint = `${base}/music_generation`
+    const body: Record<string, unknown> = {
       model,
       prompt: request.prompt,
+      ...(lyrics === '' ? {} : { lyrics }),
+      ...(request.isInstrumental !== undefined ? { is_instrumental: request.isInstrumental } : {}),
       ...(request.duration !== undefined ? { duration: request.duration } : {}),
       audio_setting: {
-        format: request.format ?? 'mp3',
-        sample_rate: 44100,
-        bitrate: 256000,
+        format: MUSIC_FORMATS.has(request.format ?? 'mp3') ? (request.format ?? 'mp3') : 'mp3',
+        sample_rate: MUSIC_SAMPLE_RATES.has(request.sampleRate ?? 44100) ? (request.sampleRate ?? 44100) : 44100,
+        bitrate: MUSIC_BITRATES.has(request.bitrate ?? 256000) ? (request.bitrate ?? 256000) : 256000,
       },
     }
-  } else {
-    endpoint = `${base}/t2a_v2`
-    body = {
-      model,
-      text: request.prompt,
-      stream: false,
-      ...(voice === '' ? {} : { voice_setting: {
-        voice_id: voice,
-        ...(request.speed !== undefined ? { speed: request.speed } : {}),
-        vol: 1,
-        pitch: 0,
-      } }),
-      audio_setting: {
-        format: request.format ?? 'mp3',
-        sample_rate: 32000,
-        bitrate: 128000,
+    const response = await fetchWithTimeout(endpoint, {
+      method: 'POST',
+      redirect: 'error',
+      headers: {
+        authorization: `Bearer ${channel.apiKey.trim()}`,
+        'content-type': 'application/json',
+        accept: 'application/json, audio/mpeg',
       },
+      body: JSON.stringify(body),
+      signal,
+    }, UPSTREAM_TIMEOUT_MS)
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new AudioGenError(`MiniMax music API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
     }
+    return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
   }
 
+  // ------------------------------------------------------------- TTS
+  const voiceId = resolveMiniMaxVoice(request)
+  if (voiceId === undefined) {
+    throw new AudioGenError(
+      'MiniMax TTS 需要指定音色 voice_id（如 male-qn-qingse、female-shaonv）：请在「音色」字段填写，或把音色加入渠道模型目录（alias 可任意、upstream 填 voice_id），也可点「获取可用模型」拉取账号音色列表。',
+      'voice-required',
+    )
+  }
+  const endpoint = `${base}/t2a_v2`
+  const body = buildMiniMaxTTSBody(request, model, voiceId)
   const response = await fetchWithTimeout(endpoint, {
     method: 'POST',
     redirect: 'error',
@@ -364,7 +503,27 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
     body: JSON.stringify(body),
     signal,
   }, UPSTREAM_TIMEOUT_MS)
-  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+  if (response.ok) {
+    return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+  }
+  const detail = await response.text().catch(() => '')
+  const routeMiss = response.status === 404 && /invalid url|invalid_request_error/i.test(detail)
+  if (!routeMiss) {
+    throw new AudioGenError(`MiniMax TTS API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+  }
+  // Gateway does not route the native MiniMax path — retry over its
+  // OpenAI-compatible /v1/audio/speech (new-api MiniMax relays merge
+  // `metadata` back into a full t2a_v2 request).
+  try {
+    return await minimaxTTSGateway(channel, request, signal, voiceId)
+  } catch (gatewayError) {
+    const detailText = gatewayError instanceof AudioGenError ? gatewayError.message : String(gatewayError)
+    throw new AudioGenError(
+      `MiniMax 渠道「${channel.name}」网关未提供原生 TTS 接口：POST ${endpoint} 返回 HTTP 404（Invalid URL，网关未路由 /v1/t2a_v2）；已回退 OpenAI 兼容 ${minimaxApiBase(channel.apiUrl)}/audio/speech 仍失败：${detailText.slice(0, 300)}。`
+      + '请把渠道 API 地址配置为官方 https://api.minimaxi.com（配合 MiniMax 官方密钥），或确认网关已将 /v1/audio/speech 映射到 MiniMax 音色渠道。',
+      'audio-api-error',
+    )
+  }
 }
 
 async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {