dsh-audiogen 0.2.0 → 0.3.2

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.2.0",
+  "version": "0.3.2",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

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

@@ -24,6 +24,7 @@ interface AgentAudioRef {
   url: string
   mime: string
   bytes: number
+  voiceId?: string
 }
 
 interface AgentAudioResult {
@@ -43,6 +44,7 @@ const audioRefSchema = {
     url: { type: 'string', required: true },
     mime: { type: 'string', required: true },
     bytes: { type: 'integer', required: true },
+    voiceId: { type: 'string' },
   },
 } as const
 
@@ -52,7 +54,7 @@ const resultSchema = {
   properties: {
     status: { type: 'string', required: true },
     message: { type: 'string', required: true },
-    mode: { type: 'string', required: true, enum: ['tts', 'music', 'sfx'] },
+    mode: { type: 'string', required: true, enum: ['tts', 'music', 'sfx', 'voice_design'] },
     model: { type: 'string', required: true },
     audio: { type: 'array', required: true, items: audioRefSchema },
     error: { type: 'string' },
@@ -98,15 +100,54 @@ function ensureConfigured(config: AgentAudioToolConfig): void {
 export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioToolConfig): () => void {
   const disposer = ctx.tools.register(defineTool({
     name: 'generate_audio',
-    description: 'Generate audio with the configured audio provider. Supports text-to-speech, music generation and sound effects. The tool call waits for the upstream result and returns same-origin audio URLs; pass those URLs to the user for playback or download. If multiple models are configured, first ask the user which one to use or pass model explicitly.',
+    description: 'Generate audio with the configured audio provider. Supports text-to-speech, music generation, sound effects and MiniMax voice design. The tool call waits for the upstream result and returns same-origin audio URLs; pass those URLs to the user for playback or download. If multiple models are configured, first ask the user which one to use or pass model explicitly.',
     parameters: {
       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'], description: 'Generation mode. Defaults to tts.' },
+      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.' },
-      speed: { type: 'number', description: 'Optional speaking rate / speed multiplier where supported.' },
+      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. 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.' },
+      // ---- 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,
@@ -117,18 +158,62 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
     async execute(args, exec) {
       const config = resolve()
       ensureConfigured(config)
-      const picked = resolveModel(config, args.model)
+      const mode = args.mode === 'music' ? 'music' : args.mode === 'sfx' ? 'sfx' : args.mode === 'voice_design' ? 'voice_design' : 'tts'
+      const picked = mode === 'voice_design'
+        ? (() => {
+          const usable = config.channels.filter(channel => channel.apiUrl.trim() !== '' && channel.apiKey.trim() !== '')
+          const target = usable.find(channel => channel.id === config.defaultChannelId) ?? usable[0]
+          if (target === undefined) throw new AudioGenError('No usable audio channel is configured for voice design.', 'no-channel-available')
+          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: args.mode === 'music' ? 'music' : args.mode === 'sfx' ? 'sfx' : 'tts',
+        mode,
         model: picked.alias,
         upstream: picked.upstream,
         channelId: picked.channel.id,
         channel: picked.channel.name,
         prompt: args.prompt.trim(),
         ...(typeof args.voice === 'string' && args.voice.trim() !== '' ? { voice: args.voice.trim() } : {}),
+        ...(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.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)
@@ -140,6 +225,7 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
             url: `/api/dsh-audiogen/audio/${encodeURIComponent(saved.file)}`,
             mime: saved.mime,
             bytes: saved.bytes,
+            ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
           })
         }
         try {
@@ -159,6 +245,7 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
               mime: audio[index]!.mime,
               bytes: audio[index]!.bytes,
               url: audio[index]!.url,
+              ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
             })),
             channelId: picked.channel.id,
             channel: picked.channel.name,

package/src/audio-engine.ts

@@ -164,7 +164,7 @@ async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: numbe
 async function normalizeAudioResponse(
   response: Response,
   options: { apiKey: string; fallbackMime?: string },
-): Promise<Array<{ data: Uint8Array; mime: string }>> {
+): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   if (!response.ok) {
     let detail = ''
     try {
@@ -213,7 +213,7 @@ async function normalizeAudioResponse(
   return [{ data: buffer, mime: audioMime(buffer, response.headers.get('content-type') ?? contentType ?? null) }]
 }
 
-async function openAITTS(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+async function openAITTS(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   const endpoint = /\/audio\/speech(\?|$)/i.test(base) ? base : `${base}/audio/speech`
   const model = (request.upstream ?? request.model) || 'tts-1'
@@ -239,7 +239,7 @@ async function openAITTS(channel: AudioChannel, request: GenerateAudioRequest, s
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
-async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   const model = (request.upstream ?? request.model) || 'eleven_multilingual_v2'
   const voiceId = (request.voice ?? request.model ?? model).trim()
@@ -274,16 +274,171 @@ function minimaxApiBase(base: string): string {
   return /\/v1$/i.test(trimmed) ? trimmed : `${trimmed}/v1`
 }
 
-async function minimax(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+/**
+ * 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 ?? ''
 
-  let endpoint: string
-  let body: Record<string, unknown>
+  if (request.mode === 'voice_design') {
+    const endpoint = `${base}/voice_design`
+    const body: Record<string, unknown> = {
+      prompt: request.prompt,
+      preview_text: request.previewText ?? request.voice ?? '你好，这是新设计的音色试听。',
+    }
+    const response = await fetchWithTimeout(endpoint, {
+      method: 'POST',
+      redirect: 'error',
+      headers: {
+        authorization: `Bearer ${channel.apiKey.trim()}`,
+        'content-type': 'application/json',
+        accept: 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal,
+    }, UPSTREAM_TIMEOUT_MS)
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new AudioGenError(`MiniMax voice design API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+    }
+    const payload = await response.json() as {
+      voice_id?: string
+      trial_audio?: string
+      base_resp?: { status_code?: number; status_msg?: string }
+    }
+    if (payload.base_resp?.status_code !== undefined && payload.base_resp.status_code !== 0) {
+      throw new AudioGenError(payload.base_resp.status_msg ?? `MiniMax returned status ${payload.base_resp.status_code}`, 'audio-api-error')
+    }
+    const encoded = payload.trial_audio ?? ''
+    if (encoded === '') throw new AudioGenError('MiniMax voice design returned no trial audio', 'audio-empty-result')
+    const isHex = /^[0-9a-fA-F]+$/.test(encoded) && encoded.length % 2 === 0
+    const data = new Uint8Array(Buffer.from(encoded, isHex ? 'hex' : 'base64'))
+    return [{
+      data,
+      mime: 'audio/mpeg',
+      ...(payload.voice_id === undefined ? {} : { voiceId: payload.voice_id }),
+    }]
+  }
+
   if (request.mode === 'music') {
-    endpoint = `${base}/music_generation`
-    body = {
+    const endpoint = `${base}/music_generation`
+    const body: Record<string, unknown> = {
       model,
       prompt: request.prompt,
       ...(request.duration !== undefined ? { duration: request.duration } : {}),
@@ -293,26 +448,34 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
         bitrate: 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',
@@ -324,10 +487,30 @@ 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 }>> {
+async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   const endpoint = /\/generation(\?|$)/i.test(base) ? base : `${base}/generation`
   const model = (request.upstream ?? request.model) || 'stable-audio-2.0'
@@ -351,7 +534,7 @@ async function stabilityAudio(channel: AudioChannel, request: GenerateAudioReque
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
-async function genericAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+async function genericAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   const base = endpointBase(channel.apiUrl)
   if (request.mode === 'tts' && !/\/generate(\?|$)/i.test(base)) {
     return openAITTS(channel, request, signal)
@@ -388,10 +571,13 @@ export async function generateAudio(
   channel: AudioChannel,
   request: GenerateAudioRequest,
   signal?: AbortSignal,
-): Promise<Array<{ data: Uint8Array; mime: string }>> {
+): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
   if (channel.apiUrl.trim() === '') throw new AudioGenError('channel API URL is not configured', 'audio-no-endpoint')
   if (channel.apiKey.trim() === '') throw new AudioGenError('channel API key is not configured', 'audio-no-key')
   if (request.prompt.trim() === '') throw new AudioGenError('audio prompt/text is required', 'audio-empty-prompt')
+  if (request.mode === 'voice_design' && !isMiniMax(channel)) {
+    throw new AudioGenError('音色设计当前仅支持 MiniMax 渠道', 'voice-design-unsupported')
+  }
 
   if (isElevenLabs(channel)) return elevenLabs(channel, request, signal)
   if (isMiniMax(channel)) return minimax(channel, request, signal)