lyria

用途

该技能用于通过 Gemini Interactions API 使用 Google Lyria 3 生成并校验音乐。资料指出，它应在调用 OpenMontage 的 google_music 之前，或在设计 Lyria 3 Clip、Pro 生成方案时使用。

需要将 Lyria 3 与 Lyria RealTime 区分开：Lyria 3 是单轮音乐生成器；Lyria RealTime 是实验性的 WebSocket 模型，用于持续受控的器乐演奏。

当需要选择模型、设计人声或自定义歌词、使用图像输入、调试响应，或查看当前限制与定价时，应阅读 references/api-and-prompting.md。

必做工作流

资料要求按以下顺序执行：

1. 确认目标角色：衬底音乐、循环、器乐提示，或完整歌曲。
2. 确认人声、语言、目标时长、音乐结构和交付格式。
3. 声明提供商、确切模型、单次请求预估成本，以及该次调用是探索性还是最终调用。
4. 使用下文契约编写一条结构化提示词。
5. 进行一次经批准的生成调用。重试应视为又一次可能计费的随机生成。
6. 原样保留返回的提供商源文件。
7. 在记录时长、格式或审批元数据之前，先探测实际文件并试听。
8. 当编辑需要精确时长时，另行派生一个制作母版。

模型选择

需求	模型	契约
提示词迭代、预览、循环、精确 30 秒源	lyria-3-clip-preview	始终生成 30 秒 MP3；资料标注当前为 $0.04/请求
完整歌曲、人声、较长结构、图像条件配乐	lyria-3-pro-preview	时长受提示词影响，最多约三分钟；资料标注当前为 $0.08/请求
实时、持续受控的器乐演奏	lyria-realtime-exp	独立 WebSocket 工作流；不要经由 google_music 路由

资料明确说明：当前 OpenMontage google_music 适配器锁定为 lyria-3-pro-preview，不暴露 Clip、WAV 响应选择、多图像或 RealTime 控制。应说明这一限制，而不是暗示这些选项可通过该适配器使用。

不要静默更换模型。对于 30 秒视频，要么获得对 Pro 加精确时长母版制作的批准，要么通过明确受支持的路径使用 Clip。

构建提示词

提示词应按以下顺序指定：

• 用途与时长：音乐支持什么，以及请求长度。
• 曲风与年代：使用音乐词汇，不要模仿在世艺术家。
• 速度与和声：BPM 或速度范围、拍号、调性或调性中心。
• 配器与质感：命名主奏、节奏、低音和环境层。
• 结构：带时间戳的段落，或 [Intro]、[Verse]、[Chorus]、[Bridge]、[Outro]。
• 动态与同步：与剪辑时间绑定的进入、休止、推进、重击与持续。
• 人声策略：仅器乐约束、人声轮廓，或清晰分离的自定义歌词。
• 混音与结尾：密度、前景/背景角色、动态余量特征，以及最终衰减。
• 排除项：不想要的人声、乐器、手势、陈词滥调、突兀结尾或受版权保护的材料。

对于视频衬底，使用时间戳窗口覆盖完整的请求时长。每个窗口只请求一个主要变化，并指出精确的同步时刻。

对于仅器乐输出，在重要时应说明以下全部内容：

Instrumental only. No lead or backing vocals, speech, choir, humming,
vocal chops, spoken samples, lyrical fragments, or recognizable quotations.

对于自定义歌词，将表演指示放在单独的 Lyrics: 块之前，并使用段落标签。提示词应使用歌手演唱的语言。

有意指导人声

当请求人声时，在编写提示词之前先定义：

• 人声角色：独唱主音、二重唱、呼应、伴唱群，或人声质感。
• 语言与文字：命名演唱语言，并让自定义歌词保持在一种有意选择的文字中；不要静默转写或语码转换。
• 歌手轮廓：声部类型或音域、音色、强度、咬字、装饰音和情感距离。不要模仿具名艺术家。
• 段落行为：说明主音在哪里进入、和声或回声出现在哪里，以及哪些段落保持器乐。
• 歌词契约：将指示与 Lyrics: 块分开，使用 [Verse]、[Chorus]、[Bridge] 和 [Outro]，括号仅保留给有意设计的伴唱回声。

在试听之前，将返回的人声视为不可信。检查歌词遵循度、语言漂移、发音、可懂度、不想要的伴唱、人声/器乐平衡，以及表演是否遵循所要求的情感弧线。一个技术有效但咬字差或歌词被改动的文件，不算经批准的人声结果。

将时长视为不可信，直到探测

Lyria 3 Pro 的时长通过提示词指令和时间戳控制，而不是精确的 API 参数。OpenMontage 适配器会追加一条目标时长指令，但其返回的 duration_seconds 字段是请求值，不是媒体探测值。

始终检查生成的文件：

ffprobe -v error -show_entries \
  format=duration,format_name,bit_rate:stream=codec_name,sample_rate,channels \
  -of json output.mp3

如果需要精确时长：

• 保持提供商源文件不变；
• 分别记录请求时长与实测时长；
• 在音乐上合理的边界处裁剪并应用短淡出，从而派生新母版；
• 未经批准的制作计划，不要拉伸、循环或重新生成；
• 记录派生过程，并再次探测母版。

安全认证与诊断

Gemini API 通常使用 GEMINI_API_KEY。OpenMontage 还支持 GOOGLE_API_KEY 以及 Vertex 服务账号凭证。

• 每次运行只使用一条已知的凭证路径。
• 调试时绝不打印密钥或编辑凭证文件。
• 不要假设第一个密钥被拒后会回退到第二个已配置密钥。
• 在当前 OpenMontage 解析器中，当 GOOGLE_API_KEY 与 GEMINI_API_KEY 都非空时，前者优先。
• 将 403、API_KEY_SERVICE_BLOCKED 以及项目/服务限制视为认证或 Google 项目配置失败，而不是提示词质量问题。
• 不要将重试浪费在权限失败上。先解决凭证/项目路径。
• 仅在批准的的重试与预算策略内，对临时的速率限制或超时失败进行重试。

解析并记录结果

优先使用 interaction.output_audio。对于交错响应，遍历 model_output 步骤并选择音频块；如果歌词或结构描述相关，则单独捕获输出文本。

记录以下内容：

• 提供商与确切模型；
• 原始提示词及任何图像来源；
• 请求时长与探测时长；
• 实际编解码器、采样率、声道和文件路径；
• 每次调用成本与总尝试次数；
• 是否请求人声，以及通过试听是否检测到人声；
• 提供商源文件与任何单独派生的制作母版。

质量检查清单

• 提示词说明用途、速度、乐器、结构、动态、人声策略和结尾。
• 时间戳窗口覆盖预期运行时，且无矛盾。
• 未请求艺术家模仿或受版权保护的歌词。
• 输出文件存在、非空、可解码，并包含音频流。
• 实际时长与技术属性来自探测，而非请求元数据。
• 检查器乐输出是否存在意外的人声材料。
• 试听开场、同步时刻、过渡和结尾。
• 保留未触碰的源文件，且任何制作母版都有明确来源。
• 在来源重要之处，确认 SynthID 水印与预览模型的不稳定性。