dsh-audiogen 0.3.5 → 0.4.0

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

package/skills/music/SKILL.md

@@ -50,3 +50,27 @@
 | seed / generation_mode / finetune_* | — | 高级字段，暂未透出 |
 
 > 响应为音频字节流（audio/*，常为 mp3）。请求同时携带 `xi-api-key` 与 `Authorization: Bearer`，以兼容 New API 类网关（官方站任一头即可）。
+
+## Stability Stable Audio（官方 v2beta，multipart/form-data）
+
+官方端点（文本到音频，TTS 描述 / 音乐 / 音效统一走该接口，不同模型参数不同）：
+- `POST /v2beta/audio/stable-audio/text-to-audio` → 模型 `stable-audio-3`（202 异步，随后轮询 GET /v2beta/audio/results/{id}）
+- `POST /v2beta/audio/stable-audio-2/text-to-audio` → 模型 `stable-audio-2` / `stable-audio-2.5`（同步返回音频）
+
+| 字段 | 工具/面板参数 | 说明 |
+| --- | --- | --- |
+| prompt | prompt | 必填，描述性提示词（乐器/情绪/风格/体裁，≤10000 字符） |
+| model | model | stable-audio-3 / stable-audio-2.5 / stable-audio-2 |
+| duration | duration | 秒数：3 ≤380（默认 190）；2/2.5 ≤190（默认 190） |
+| seed | seed | 0-4294967294，默认 0=随机；同参数同 seed 可复现 |
+| steps | steps | 采样步数：2 → 30-100（默认 50）；2.5/3 → 4-8（默认 8） |
+| cfg_scale | cfg_scale | 1-25：2 默认 7，2.5/3 默认 1；越高越贴提示词 |
+| output_format | format | mp3 / wav |
+
+> 引擎按模型自动收敛步数/时长区间；渠道 preset/apiUrl 含 `stability` 或模型名以 `stable-audio-` 开头即走官方协议（自定义渠道同样适用）。
+
+### 双通道（自动选择）
+- **官方 v2beta**：apiUrl 为 `https://api.stability.ai`（含 `/v2beta`、`/v2beta/audio` 形态）→ multipart 原生端点（2/2.5 同步、3 异步轮询）。
+- **OpenAI 兼容网关**：apiUrl 以 `/v1` 结尾或含 `/audio/speech`（如 New API）→ `POST {apiUrl}/audio/speech`，JSON：
+  `{ "model": "stable-audio-2.5", "input": "<prompt>", "output_format": "mp3", "duration": 30, "seed": 0, "steps": 8, "cfg_scale": 1 }`（网关把该模型映射到 Stable 上游）。
+- 一方返回 `404 Invalid URL`（未路由）时自动换另一方重试；参数在两种通道均按模型收敛（duration/seed/steps/cfg_scale/output_format）。

package/src/agent-audio-tools.ts

@@ -9,14 +9,15 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { randomUUID } from 'node:crypto'
 import type { AudioChannel } from './audio-engine.ts'
 import { generateAudio, AudioGenError } from './audio-engine.ts'
-import { appendHistory, saveAudioFile } from './audio-store.ts'
-import type { AudioMode, GenerateAudioRequest } from './protocol.ts'
+import { appendHistory, saveAudioFile, saveToLibrary, listLibrary } from './audio-store.ts'
+import type { AudioMode, GenerateAudioRequest, LibraryType } from './protocol.ts'
 
 export interface AgentAudioToolConfig {
   enabled: boolean
   allowAgentAudioGeneration: boolean
   channels: AudioChannel[]
   defaultChannelId: string
+  autoSaveToLibrary: boolean
 }
 
 interface AgentAudioRef {
@@ -27,12 +28,19 @@ interface AgentAudioRef {
   voiceId?: string
 }
 
+/** Internal: the persisted file name, needed for library copies. */
+interface SavedAudioRef extends AgentAudioRef {
+  file: string
+}
+
 interface AgentAudioResult {
   status: string
   message: string
   mode: AudioMode
   model: string
   audio: AgentAudioRef[]
+  /** Resource-library entry ids when the audio was saved to the library. */
+  resources?: string[]
   error?: string
 }
 
@@ -57,6 +65,7 @@ const resultSchema = {
     mode: { type: 'string', required: true, enum: ['tts', 'music', 'sfx', 'voice_design'] },
     model: { type: 'string', required: true },
     audio: { type: 'array', required: true, items: audioRefSchema },
+    resources: { type: 'array', items: { type: 'string' } },
     error: { type: 'string' },
   },
 } as const
@@ -96,11 +105,17 @@ function ensureConfigured(config: AgentAudioToolConfig): void {
   if (!usable) throw new AudioGenError('Audio API credentials are not configured. Open Settings > Plugins > AI Audio, add a channel and fill its API URL and API key.', 'audio-api-not-configured')
 }
 
+/** Library type from the generation mode, with an explicit override. */
+function libraryTypeOf(mode: AudioMode, override: unknown): LibraryType {
+  if (override === 'voice' || override === 'music' || override === 'sfx' || override === 'tts') return override
+  if (mode === 'voice_design') return 'voice'
+  return mode
+}
+
 /** Register the Agent audio tool. */
 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, sound effects and voice design (MiniMax /v1/voice_design, ElevenLabs /v1/text-to-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.',
+    name: 'generate_audio',    description: 'Generate audio with the configured audio provider. Supports text-to-speech, music generation, sound effects and voice design (MiniMax /v1/voice_design, ElevenLabs /v1/text-to-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', 'voice_design'], description: 'Generation mode. Defaults to tts.' },
@@ -113,6 +128,9 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       is_instrumental: { type: 'boolean', description: 'Generate purely instrumental music without vocals/lyrics (MiniMax is_instrumental). When true, lyrics may be omitted.' },
       loop: { type: 'boolean', description: 'Create a seamlessly looping sound effect (ElevenLabs sound generation loop, only for eleven_text_to_sound_v2).' },
       prompt_influence: { type: 'number', description: 'Sound effect prompt influence 0-1 (ElevenLabs prompt_influence, default 0.3): higher follows the prompt more closely, lower is more variable.' },
+      seed: { type: 'integer', description: 'Stable Audio random seed 0-4294967294 (default 0 = random); same seed yields reproducible audio.' },
+      steps: { type: 'integer', description: 'Stable Audio sampling steps, model-dependent: stable-audio-2 30-100, stable-audio-2.5/3 4-8 (out-of-range auto-clamped).' },
+      cfg_scale: { type: 'number', description: 'Stable Audio prompt adherence 1-25 (stable-audio-2 default 7, 2.5/3 default 1); higher follows the prompt more strictly.' },
       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).' },
@@ -152,6 +170,11 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
         },
         description: 'MiniMax TTS dual-voice blend weights (timbre_weights).',
       },
+      // ---- resource library ----
+      save_to_library: { type: 'boolean', description: 'Save the generated audio into the local resource library after success. Also enabled globally by the "auto save to library" setting; pass false to skip a single run.' },
+      library_name: { type: 'string', description: 'Resource name in the library. Defaults to the prompt.' },
+      library_type: { type: 'string', enum: ['voice', 'music', 'sfx', 'tts'], description: 'Resource type in the library. Defaults to the generation mode (voice_design → voice).' },
+      library_tags: { type: 'array', items: { type: 'string' }, description: 'Tags for the library resource.' },
     },
     output: {
       schema: resultSchema,
@@ -203,6 +226,9 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
         ...(typeof args.is_instrumental === 'boolean' ? { isInstrumental: args.is_instrumental } : {}),
         ...(typeof args.loop === 'boolean' ? { loop: args.loop } : {}),
         ...(typeof args.prompt_influence === 'number' && Number.isFinite(args.prompt_influence) ? { promptInfluence: args.prompt_influence } : {}),
+        ...(typeof args.seed === 'number' && Number.isFinite(args.seed) ? { seed: args.seed } : {}),
+        ...(typeof args.steps === 'number' && Number.isFinite(args.steps) ? { steps: args.steps } : {}),
+        ...(typeof args.cfg_scale === 'number' && Number.isFinite(args.cfg_scale) ? { cfgScale: args.cfg_scale } : {}),
         ...(typeof args.format === 'string' && args.format.trim() !== '' ? { format: args.format.trim() } : {}),
         // ---- MiniMax TTS 专属字段 ----
         ...(typeof args.emotion === 'string' && args.emotion.trim() !== '' ? { emotion: args.emotion.trim() } : {}),
@@ -226,13 +252,22 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       try {
         const outputs = await generateAudio(picked.channel, request, exec.signal)
         const audio: AgentAudioRef[] = []
+        const saved: SavedAudioRef[] = []
         for (const [index, output] of outputs.entries()) {
-          const saved = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`)
+          const stored = await saveAudioFile(output.data, output.mime, `generated-${index + 1}`)
+          saved.push({
+            id: stored.id,
+            url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+            file: stored.file,
+            mime: stored.mime,
+            bytes: stored.bytes,
+            ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
+          })
           audio.push({
-            id: saved.id,
-            url: `/api/dsh-audiogen/audio/${encodeURIComponent(saved.file)}`,
-            mime: saved.mime,
-            bytes: saved.bytes,
+            id: stored.id,
+            url: `/api/dsh-audiogen/audio/${encodeURIComponent(stored.file)}`,
+            mime: stored.mime,
+            bytes: stored.bytes,
             ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
           })
         }
@@ -248,25 +283,60 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
             ...(request.duration === undefined ? {} : { duration: request.duration }),
             ...(request.format === undefined ? {} : { format: request.format }),
             audio: outputs.map((output, index) => ({
-              id: audio[index]!.id,
+              id: saved[index]!.id,
+              file: saved[index]!.file,
               b64: Buffer.from(output.data).toString('base64'),
-              mime: audio[index]!.mime,
-              bytes: audio[index]!.bytes,
-              url: audio[index]!.url,
+              mime: saved[index]!.mime,
+              bytes: saved[index]!.bytes,
+              url: saved[index]!.url,
               ...(output.voiceId === undefined ? {} : { voiceId: output.voiceId }),
             })),
             channelId: picked.channel.id,
             channel: picked.channel.name,
+            params: { ...request },
           })
         } catch {
           // History is best-effort and must not fail the agent tool.
         }
+        // ---- 资源库保存：显式参数优先；设置自动入库时可用 false 跳过 ----
+        const wantSave = args.save_to_library === true || (config.autoSaveToLibrary && args.save_to_library !== false)
+        let resources: string[] | undefined
+        if (wantSave) {
+          try {
+            const entry = await saveToLibrary({
+              audioFiles: saved.map(item => ({
+                id: item.id,
+                file: item.file,
+                mime: item.mime,
+                ...(item.voiceId === undefined ? {} : { voiceId: item.voiceId }),
+              })),
+              type: libraryTypeOf(request.mode, args.library_type),
+              ...(typeof args.library_name === 'string' && args.library_name.trim() !== '' ? { name: args.library_name.trim() } : {}),
+              ...(Array.isArray(args.library_tags) ? { tags: args.library_tags.filter((tag): tag is string => typeof tag === 'string' && tag.trim() !== '').map(tag => tag.trim()) } : {}),
+              provenance: {
+                mode: request.mode,
+                prompt: request.prompt,
+                channel: picked.channel.name,
+                channelId: picked.channel.id,
+                apiUrl: picked.channel.apiUrl,
+                model: picked.alias,
+                upstream: picked.upstream,
+                ...(request.voice === undefined ? {} : { voice: request.voice }),
+                params: { ...request },
+              },
+            })
+            resources = [entry.id]
+          } catch {
+            // library-save is best-effort; generation already succeeded.
+          }
+        }
         return {
           status: 'completed',
           message: 'Audio generation completed. The audio files can be played/downloaded from the returned URLs.',
           mode: request.mode,
           model: picked.alias,
           audio,
+          ...(resources === undefined ? {} : { resources }),
         }
       } catch (error) {
         if (exec.signal?.aborted === true) throw error
@@ -281,5 +351,76 @@ export function registerAgentAudioTools(ctx: Context, resolve: () => AgentAudioT
       }
     },
   }))
-  return disposer
+
+  const searchDisposer = ctx.tools.register(defineTool({
+    name: 'search_audio_library',
+    description: 'Search curated audio resources in the local resource library (voice / music / sfx / tts). Returns matching resources with type, category, name, tags, full provenance (channel, model, voiceId, prompt) and same-origin audio URLs the user can play. Use it before generating to reuse an existing voice, music bed or sound effect instead of generating a new one.',
+    parameters: {
+      type: { type: 'string', enum: ['voice', 'music', 'sfx', 'tts'], description: 'Filter by resource type.' },
+      category: { type: 'string', description: 'Filter by category (voice: male/female/custom; tts: the speaking voice key).' },
+      keyword: { type: 'string', description: 'Search name, tags, prompt and model.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          status: { type: 'string', required: true, enum: ['ok'] },
+          count: { type: 'integer', required: true },
+          entries: {
+            type: 'array', required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                name: { type: 'string', required: true },
+                type: { type: 'string', required: true, enum: ['voice', 'music', 'sfx', 'tts'] },
+                category: { type: 'string' },
+                tags: { type: 'array', items: { type: 'string' }, required: true },
+                prompt: { type: 'string', required: true },
+                model: { type: 'string' },
+                channel: { type: 'string' },
+                voiceId: { type: 'string' },
+                urls: { type: 'array', items: { type: 'string' }, required: true },
+              },
+            },
+          },
+        },
+      } as const,
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const keyword = typeof args.keyword === 'string' ? args.keyword.trim().toLowerCase() : ''
+      const wantedType = args.type === 'voice' || args.type === 'music' || args.type === 'sfx' || args.type === 'tts' ? args.type : undefined
+      const wantedCategory = typeof args.category === 'string' && args.category.trim() !== '' ? args.category.trim() : undefined
+      const all = await listLibrary()
+      const entries = all.filter(entry => {
+        if (wantedType !== undefined && entry.type !== wantedType) return false
+        if (wantedCategory !== undefined && (entry.category ?? '') !== wantedCategory) return false
+        if (keyword !== '') {
+          const haystack = [entry.name, ...entry.tags, entry.provenance.prompt, entry.provenance.model ?? '', entry.provenance.channel ?? ''].join(' ').toLowerCase()
+          if (!haystack.includes(keyword)) return false
+        }
+        return true
+      }).slice(0, 30).map(entry => ({
+        id: entry.id,
+        name: entry.name,
+        type: entry.type,
+        ...(entry.category === undefined ? {} : { category: entry.category }),
+        tags: entry.tags,
+        prompt: entry.provenance.prompt,
+        ...(entry.provenance.model === undefined ? {} : { model: entry.provenance.model }),
+        ...(entry.provenance.channel === undefined ? {} : { channel: entry.provenance.channel }),
+        ...(entry.provenance.voiceId === undefined ? {} : { voiceId: entry.provenance.voiceId }),
+        urls: entry.files.map(file => file.url),
+      }))
+      return { status: 'ok' as const, count: entries.length, entries }
+    },
+  }))
+  return () => {
+    disposer()
+    searchDisposer()
+  }
 }

package/src/audio-engine.ts

@@ -63,7 +63,13 @@ export function detectAudioMime(data: Uint8Array): string | undefined {
 
 function mimeFromContentType(value: string | null): string | undefined {
   if (value === null || value === '') return undefined
-  return value.split(';')[0]!.trim().toLowerCase()
+  const parts = value.split(';')
+  for (const part of parts.slice(1)) {
+    // `application/json; type=audio/mpeg` —— Stability 官方用该形式携带音频真实类型。
+    const match = /^\s*type=([^;\s]+)/i.exec(part)
+    if (match !== null) return match[1]!.trim().toLowerCase()
+  }
+  return parts[0]!.trim().toLowerCase()
 }
 
 function audioMime(data: Uint8Array, contentType: string | null): string {
@@ -630,30 +636,183 @@ async function minimax(channel: AudioChannel, request: GenerateAudioRequest, sig
   }
 }
 
-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'
+/** Stability 内部信号：路由缺失（网关 404 Invalid URL），可切换另一协议重试。 */
+class StabilityRouteMissError extends Error {}
+
+/** 网关风格：apiUrl 形如 .../v1、.../v1/audio/speech 时优先 OpenAI 兼容 speech。 */
+function stabilityGatewayStyle(channel: AudioChannel): boolean {
+  const url = channel.apiUrl.trim().toLowerCase()
+  return /\/v1(\/|$|\?)/.test(url) || /\/audio\/speech(\?|$)/.test(url)
+}
+
+function isStabilityRouteMiss(status: number, detail: string): boolean {
+  return status === 404 && /invalid url|invalid_request_error/i.test(detail)
+}
+
+/**
+ * Stable Audio 官方 v2beta（multipart/form-data）。
+ * - stable-audio-3        → POST {base}/stable-audio/text-to-audio    （202 异步 → GET /v2beta/audio/results/{id} 轮询）
+ * - stable-audio-2 / 2.5  → POST {base}/stable-audio-2/text-to-audio  （200 同步返回音频/JSON base64）
+ * - 不同模型参数不同：stable-audio-3 steps 4-8、duration ≤380；2 steps 30-100、cfg_scale 默认 7；
+ *   2.5 steps 4-8、cfg_scale 默认 1；均支持 seed、output_format(hp3|wav)。
+ */
+async function stabilityNativeAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const rawBase = endpointBase(channel.apiUrl)
+  const model = (request.upstream ?? request.model) || 'stable-audio-2.5'
+  const isV3 = /^stable-audio-3/i.test(model)
+  const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model)
+  const group = isV2 ? 'stable-audio-2' : 'stable-audio'
+
+  // 规范化 base：允许 apiUrl 为 `https://api.stability.ai` / `.../v2beta` / `.../v2beta/audio`
+  const base = /\/v2beta\/audio$/i.test(rawBase)
+    ? rawBase
+    : /\/v2beta$/i.test(rawBase)
+      ? `${rawBase}/audio`
+      : `${rawBase}/v2beta/audio`
+  const endpoint = `${base}/${group}/text-to-audio`
+
+  const form = new FormData()
+  form.set('prompt', request.prompt)
+  form.set('model', model)
+  if (request.duration !== undefined && Number.isFinite(request.duration)) {
+    const maxDuration = isV3 ? 380 : 190
+    form.set('duration', String(Math.min(maxDuration, Math.max(1, request.duration))))
+  }
+  if (request.seed !== undefined && Number.isFinite(request.seed)) {
+    form.set('seed', String(Math.floor(Math.min(4294967294, Math.max(0, request.seed)))))
+  }
+  const format = request.format === 'wav' ? 'wav' : 'mp3'
+  form.set('output_format', format)
+  if (request.steps !== undefined && Number.isInteger(request.steps)) {
+    const minSteps = isV2 && !/2\.5/i.test(model) ? 30 : 4
+    const maxSteps = isV2 && !/2\.5/i.test(model) ? 100 : 8
+    form.set('steps', String(Math.min(maxSteps, Math.max(minSteps, request.steps))))
+  }
+  if (request.cfgScale !== undefined && Number.isFinite(request.cfgScale)) {
+    form.set('cfg_scale', String(Math.min(25, Math.max(1, request.cfgScale))))
+  }
+
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      accept: 'application/json',
+    },
+    body: form,
+    signal,
+  }, isV3 ? 60_000 : UPSTREAM_TIMEOUT_MS)
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError()
+    throw new AudioGenError(`Stable Audio API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+  }
+
+  // stable-audio-3 异步：202 → 轮询结果
+  if (response.status === 202) {
+    const payload = await response.json().catch(() => ({})) as { id?: string }
+    if (payload.id === undefined || payload.id === '') {
+      throw new AudioGenError('Stable Audio accepted the job but returned no result id', 'audio-empty-result')
+    }
+    const apiOrigin = base.replace(/\/v2beta\/audio$/i, '')
+    const resultUrl = `${apiOrigin}/v2beta/audio/results/${encodeURIComponent(payload.id)}`
+    const deadline = Date.now() + UPSTREAM_TIMEOUT_MS
+    while (Date.now() < deadline) {
+      if (signal?.aborted === true) throw new AudioGenError('Stable Audio generation was aborted', 'audio-aborted')
+      const polled = await fetchWithTimeout(resultUrl, {
+        method: 'GET',
+        redirect: 'error',
+        headers: {
+          authorization: `Bearer ${channel.apiKey.trim()}`,
+          accept: 'application/json',
+        },
+        signal,
+      }, 60_000)
+      if (polled.ok) {
+        return normalizeAudioResponse(polled, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+      }
+      if (polled.status === 404 || polled.status === 202) {
+        await new Promise(resolve => setTimeout(resolve, 5000))
+        continue
+      }
+      const detail = await polled.text().catch(() => '')
+      throw new AudioGenError(`Stable Audio result API error (HTTP ${polled.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+    }
+    throw new AudioGenError('Stable Audio generation timed out waiting for the result', 'audio-timeout')
+  }
+
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+/**
+ * Stable Audio 经 OpenAI 兼容网关（如 New API 的 /v1/audio/speech）：
+ * 模型名映射到 Stable 上游，JSON 体为 {model, input, output_format, duration,
+ * seed, steps, cfg_scale} —— 与官方 v2beta 字段一一对应，网关负责转发。
+ */
+async function stabilityGatewayAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const rawBase = endpointBase(channel.apiUrl)
+  const model = (request.upstream ?? request.model) || 'stable-audio-2.5'
+  const isV3 = /^stable-audio-3/i.test(model)
+  const isV2 = /^stable-audio-2(\.[05])?$/i.test(model) || /^stable-audio-2-/i.test(model)
+  const endpoint = /\/audio\/speech(\?|$)/i.test(rawBase) ? rawBase : `${rawBase}/audio/speech`
+  const format = request.format === 'wav' ? 'wav' : 'mp3'
   const body: Record<string, unknown> = {
     model,
-    prompt: request.prompt,
-    ...(request.duration !== undefined ? { duration: request.duration } : {}),
-    ...(request.format !== undefined ? { output_format: request.format } : {}),
+    input: request.prompt,
+    output_format: format,
+    ...(request.duration !== undefined && Number.isFinite(request.duration)
+      ? { duration: Math.min(isV3 ? 380 : 190, Math.max(1, request.duration)) }
+      : {}),
+    ...(request.seed !== undefined && Number.isFinite(request.seed)
+      ? { seed: Math.floor(Math.min(4294967294, Math.max(0, request.seed))) }
+      : {}),
+    ...(request.steps !== undefined && Number.isInteger(request.steps)
+      ? { steps: Math.min(isV2 && !/2\.5/i.test(model) ? 100 : 8, Math.max(isV2 && !/2\.5/i.test(model) ? 30 : 4, request.steps)) }
+      : {}),
+    ...(request.cfgScale !== undefined && Number.isFinite(request.cfgScale)
+      ? { cfg_scale: Math.min(25, Math.max(1, request.cfgScale)) }
+      : {}),
   }
   const response = await fetchWithTimeout(endpoint, {
     method: 'POST',
-    redirect: 'error',
+    redirect: 'follow',
     headers: {
       authorization: `Bearer ${channel.apiKey.trim()}`,
+      accept: 'audio/*',
       'content-type': 'application/json',
-      accept: 'application/json, audio/mpeg, audio/wav',
     },
     body: JSON.stringify(body),
     signal,
   }, UPSTREAM_TIMEOUT_MS)
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    if (isStabilityRouteMiss(response.status, detail)) throw new StabilityRouteMissError()
+    throw new AudioGenError(`Stable Audio gateway API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`, 'audio-api-error')
+  }
   return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
 }
 
+/**
+ * 稳定性入口：优先官方 v2beta（api.stability.ai / v2beta 形态），
+ * 网关形态（apiUrl 以 /v1 结尾或已含 /audio/speech）优先 OpenAI 兼容；
+ * 一方返回 404 Invalid URL（未路由）时自动换另一方重试。
+ */
+async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string; voiceId?: string }>> {
+  const styles: Array<'native' | 'gateway'> = stabilityGatewayStyle(channel) ? ['gateway', 'native'] : ['native', 'gateway']
+  let lastError: Error | undefined
+  for (const style of styles) {
+    try {
+      if (style === 'gateway') return await stabilityGatewayAudio(channel, request, signal)
+      return await stabilityNativeAudio(channel, request, signal)
+    } catch (error) {
+      if (!(error instanceof StabilityRouteMissError)) throw error
+      lastError = error
+    }
+  }
+  throw lastError ?? new AudioGenError('Stable Audio 渠道未配置或不可达', 'audio-api-error')
+}
+
 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)) {
@@ -701,7 +860,10 @@ export async function generateAudio(
 
   if (isElevenLabs(channel)) return elevenLabs(channel, request, signal)
   if (isMiniMax(channel)) return minimax(channel, request, signal)
-  if (isStability(channel)) return stabilityAudio(channel, request, signal)
+  // 稳定性渠道或模型名明确为 stable-audio-*（含自定义渠道）→ 走官方 Stable Audio 协议
+  if (isStability(channel) || /^stable-audio-/i.test(((request.upstream ?? request.model) || '').trim())) {
+    return stabilityAudio(channel, request, signal)
+  }
   if (isOpenAICompatible(channel, request.mode)) return openAITTS(channel, request, signal)
   return genericAudio(channel, request, signal)
 }

package/src/audio-presets.ts

@@ -74,10 +74,11 @@ export const AUDIO_PRESETS: AudioPresetProvider[] = [
     name: 'Stability AI（stable-audio）',
     apiUrl: 'https://api.stability.ai/v2beta/audio',
     site: 'https://stability.ai/stable-audio',
-    hint: 'Stability AI 音乐 / 音效生成（stable-audio 系列）',
+    hint: 'Stability AI 文本到音频（TTS 描述 / 音乐 / 音效，stable-audio 系列；stable-audio-3 为异步任务）',
     models: [
-      { alias: 'stable-audio-2.0', id: 'stable-audio-2.0', category: 'music' },
-      { alias: 'stable-audio-1.0', id: 'stable-audio-1.0', category: 'music' },
+      { alias: 'stable-audio-3', id: 'stable-audio-3', category: 'music' },
+      { alias: 'stable-audio-2.5', id: 'stable-audio-2.5', category: 'music' },
+      { alias: 'stable-audio-2', id: 'stable-audio-2', category: 'music' },
     ],
   },
 ]