scenario-audio

场景音频生成

概述

Scenario 使用与图像相同的循环生成音频。当前目录涵盖三种生成类型（音乐、音效、语音/语音合成），以及视频转音频配乐模型和音频实用工具。有关连接和核心生成循环，请参阅 scenario 技能。如果此处提到的同级技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，请根据工具架构继续操作，并指出这一缺失。

快速参考

步骤	工具	说明
查找模型	使用 recommend，以用户自己的措辞描述需求；仅当已知成员名称时使用 search	capability="txt2audio" 涵盖音乐、音效和 TTS；此参数为可选项，省略时会根据提示词推断
检查输入	model_schema_get	音频架构差异很大：时长、歌词、音色、循环方式
生成	model_run	参数须符合架构；长任务请使用 wait=false
等待	jobs_wait	在服务端阻塞；超时后使用 pending_job_ids 再次调用
收听	asset_display	渲染内嵌音频播放器
保存	asset_download	按生成格式保存文件（WAV、MP3 等）：curl -L -o out.<ext> "<url>"，<ext> 根据其返回的 mimeType 确定，否则使用 ffprobe

使用 search，并设置 target="assets"、filters={kind: "audio"}，查找现有音频资源。有关团队和项目范围（team_id、project_id），请参阅 scenario 技能。

音频功能范围

• 音乐：文本生成音乐模型可生成短背景音乐或带人声的完整歌曲；歌曲功能有自己的契约，见下文。
• 音效：文本生成音效模型可根据描述生成短音频片段；部分模型支持无缝循环。
• 语音和言语：使用预设音色进行文本转语音，支持多语言输出以及情绪或语速控制；部分模型可根据短音频片段克隆音色，语音转语音则可为录音重新配音。
• 视频转音频：为静音视频配乐或添加同步音效的模型。
• 实用工具：model_scenario-audio-cut、model_scenario-audio-split、model_scenario-audio-extract 和 model_scenario-compose-video（固定 ID：每个工具都是 Scenario 针对其操作提供的单一确定性工具，因此发现操作只会重新推导出这些工具）；合成器会根据 scenario-video-assembly，将完成的音轨（配乐、旁白、重新配音的片段）作为音频层叠加到视频片段上；如需语音转文本转录，请使用 recommend，并用用户自己的话描述需求。
• 音轨分离：每次运行只分离一个指定音轨（通过 recommend 发现），包括人声，不提供纯伴奏选项。人声隔离会返回干净的人声，不会将移除的人声和音效作为第二个音轨返回，因此，将音轨分成两部分（人声与其他所有内容）是需要报告的功能缺口，不必继续寻找。

各类别的契约：scenario-elevenlabs（语音、配音、重新配音、音乐、音效）、scenario-ace-step 和 scenario-minimax-music（歌曲）、scenario-sonilo（音效和视频配乐）。

示例：游戏音效

1. 使用 capability="txt2audio" 调用 recommend，并将用户自己的描述作为 prompt（“游戏音效：沉重的木箱吱呀一声打开”）。排序结果会返回 txt2audio 模型，例如 model_elevenlabs-sound-effects-v2（仅为示例）。
2. 使用该 model_id 调用 model_schema_get。返回确切字段：提示词，以及时长或循环等控制项。
3. 使用相同的 model_id 和 parameters={"prompt": "heavy wooden treasure chest creaking open, single event, dry, no music"} 调用 model_run。
4. 对任何未返回资源的 job_id 调用 jobs_wait job_ids=["job_xxx"]（等待超时后状态为 in_progress，或在 wait=false 后后端返回 queued 或 in-progress）；超时后，使用返回的 pending_job_ids 再次调用。
5. 调用 asset_display asset_id="asset_xxx" 以行内播放。
6. 调用不带 format 的 asset_download，然后使用 curl -L 将返回的 URL 保存为其 mimeType 指定的扩展名。

提示词技巧：

• 音效：说明声源、材质、动作和声学空间，并指出要排除的内容（“无音乐”“无混响”）。每个片段只生成一个事件；如需不同变体，请分别运行。
• 音乐：说明流派、情绪、节奏和乐器。短背景音乐通常只需一个提示词，时长或循环设置见架构字段。
• 语音：文本字段只填写要说出的内容；音色、语言、情绪和语速应设置在单独的架构字段或行内标签中。

语音与对话

使用 recommend 发现语音成员（capability="txt2audio"；若是双人对话，则使用用户提供的原话 “two-person dialogue”），然后在 model_schema_get 中查看其文本字段的描述：成员通常会在这里说明自己的表达语法。

• 标签语法因成员而异，即使属于同一系列也不例外：方括号（[whispers]）、尖括号 （<sigh>、<short pause>）、圆括号（(sighs)）或成对包裹 （<whisper>text</whisper>），有些成员则不识别任何标签。使用了错误语法的标签可能会被朗读出来，因此请从文本字段的描述中照抄标签写法；如果其中没有说明，则查看成员的目录描述或 recommend 的备注；如果没有任何来源，就不要添加标签。拼写正确的标签只是请求，并非保证：两次相同的运行对同一个标签也出现了不同结果，因此在最终定稿前请让用户试听；如果某个标签被忽略，请重新生成该段。
• 两个声音，一次生成。 支持多说话人数组的成员（创作时最多可包含 2 行，每行是一个说话人标签和一个声音）会将文本作为轮次朗读，每轮一行 Name: line，其中每个 Name 都必须与某一行的标签完全匹配；没有前缀的行会延续上一轮，并且在此模式下会忽略单声音字段。预设声音名称无法说明性别、年龄或音色，因此请说明每个预设由谁使用，并在付费运行前让用户确认。说话人数更多的场景应拆分为每段最多两人的多次生成，再按顺序交付，或根据 scenario-video-assembly 与画面叠加。
• 文本有长度上限且会计费。 文本字段带有 max_length（创作时某个成员的上限为 5000 个字符），超出会返回 400 错误；cost_impact 标记此字段为计费因素：请在轮次边界拆分长脚本，并对第一段执行 dry_run。
• 如果架构中有语言字段，请通过该字段指定语言，不要在文本中注明。

带人声的歌曲

完整歌曲并不是更长的音乐伴奏，而且歌曲架构的差异比该系列中的其他内容都大，因此应以 model_schema_get 为准：架构可能是风格提示词加独立歌词表、同时包含两者的单段文本提示词，或包含各段文本和风格的有序分段数组。

• 歌词绝不能放在风格字段中。 架构将二者分开时，风格字段用于填写流派、情绪、速度、调性、人声风格和乐器配置；歌词字段用于填写歌词，并可通过 [Verse] 和 [Chorus] 等段落标签来组织。
• 纯器乐和自动生成歌词是标志字段（前提是架构包含这些字段）；仅在文本中提出这类要求并不可靠。如果架构没有相应标志字段，就只能通过文本字段来控制。重新运行时切换纯器乐标志会生成不同版本，而不是同一首歌：如果模型支持 seed，它只能在设置完全相同时复现结果。若要为已有曲目生成纯器乐版本，可尝试使用 audio2audio 翻唱模型（通过 recommend 发现），并查看架构，因为并非所有模型都支持该标志。
• 每个模型和字段的文本长度都有上限，超出会返回 400 错误，而不是截断文本。

如果架构提供时长字段（标记为 cost_impact），该字段会同时限制长度和价格；如果没有，歌词表或提示词则会同时决定两者。无论哪种情况，都应先通过 dry_run: true 估算歌曲价格，再使用 wait: false 启动；两者都是 model_run 参数，而不是 parameters 键。

是否可复现以及是否支持批量生成，都因成员而异，而非因系列而异：创作时，repaint 成员支持 numOutputs（1 到 4），但不支持 seed，因此若要让 repaint 保留相同歌手，就应批量运行后再挑选；而分段作曲器支持 seed，但不支持 numOutputs。在承诺支持其中任一功能前，请先从 model_schema_get 中确认。

延长歌曲

延长现有曲目属于独立的 audio2audio 工作流，而不是运行时长更长的文本生成音乐任务： 使用 recommend，设置 capability="audio2audio"，并用用户自己的话描述延长需求；只有已知成员名称时才使用 search。执行此操作的成员会接收歌曲作为 audio，并接收一个按顺序排列的 sections 数组（编写时最多 30 项）。其中每项要么保留原曲的一段（使用 sourceStartSeconds 和 sourceEndSeconds），要么生成新片段（使用带有 [Verse] 等标签的 text、durationSeconds 和数组形式的 positiveStyles）。contextAdherence 用于决定新片段在多大程度上贴合相邻片段。保留的片段按相同长度的生成音频计费，因此请先对整个计划运行 dry_run。重绘、编辑和添加图层的成员只会在原曲时长内重新生成，绝不会延长歌曲；在编写时，recommend 曾为“延长歌曲”推荐排名较高的一个旧版文本生成音乐成员：延长歌曲并非 txt2audio 需求，因此不要采用该推荐。

常见错误

• 将生成模型 ID 硬编码：不同团队的可用模型各不相同，也会随时间变化。每次会话都要重新发现模型，根据需求使用 recommend，或根据名称使用 search；只有上文列出的固定第一方工具 ID 不会变化。
• 跳过 model_schema_get：一种音频模型的参数不适用于另一种（语音、时长和歌词字段都可能不同）。
• 循环调用 job_get 轮询：音乐任务可能运行数分钟。请使用 jobs_wait；超时后，使用 pending_job_ids 再次调用。
• 在聊天中粘贴原始资源 URL：使用 asset_display 播放音频。
• 对音频调用 asset_download 时传入 format：它只会转换图像格式，因此请省略该参数。只有在成员的架构提供输出格式字段时，才能在生成时请求 WAV。
• 将语音指示写进 TTS 文本（“生气地说这句话”）：指示内容可能会被读出来。请使用架构中的情绪或语音字段。
• 用一个声音朗读对话双方：对于多说话者成员，请填写说话者行，并在每轮发言前加上对应标签；如果行内容为空，成员会用同一个声音朗读所有内容。
• 将歌词粘贴到风格字段：模型会改为描述歌曲，而不是演唱歌曲。
• 用重绘或新的文本生成音乐任务来回应“让它更长”：前者会保留原时长，后者会丢失原歌曲；上文的延长工作流会保留用户选定的片段。
• 将 dry_run 或 wait 放进 parameters：它们是 model_run 自带的参数，因此多余的 dry_run 仍会产生费用，多余的 wait 则会阻塞最多 180s。