OpenMontage × Google Lyria 3基于 Gemini Interactions API 的音乐生成、Prompt 编排与质量验证指南【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本指南围绕 OpenMontage 仓库中的lyriaAgent 技能文档.agents/skills/lyria/SKILL.md 及其参考文档 api-and-prompting.md展开面向三类读者需要通过 OpenMontagegoogle_music工具为视频成片配乐的创作者、希望用 Agent 自动化生成 → 校验 → 归档完整链路的技术用户以及需要深入理解该工具底层实现的开发者。读完本文你将掌握 Lyria 3 Clip / Pro / RealTime 的选型逻辑、可复制的结构化 Prompt 模板、人声与自定义歌词的编排契约、时长不可信前提下的 ffprobe 探测纪律以及 Google 凭证与失败分类的排障清单。OpenMontage 定位为开源的 Agentic 视频生产系统其音乐能力由google_music工具对接 Google Lyria 3 提供。为了让 AI 助手Agent在与工具交互前就具备足够的领域知识仓库把整套使用规范沉淀为lyria技能技能文件定义了强制性工作流与质量红线参考文档补全了 API 形状与 Prompt 模板二者共同约束 Agent 不得盲调接口、盲信返回、不试听即验收。lyria技能在 OpenMontage 中的角色lyria技能位于仓库 .agents/skills/lyria/SKILL.md其 frontmatter 声明了适用范围生成并校验 Google Lyria 3 音乐、设计 Lyria 3 Clip / Pro Prompt、使用图生音乐或自定义歌词、在 Lyria 3 与 Lyria RealTime 之间选型、诊断 Google 音乐生成失败以及为视频准备精确时长的音乐。该技能还附带一个 Agent 接口声明 .agents/skills/lyria/agents/openai.yaml其中把$lyria定义为设计一份生产级 Lyria 3 音乐生成 Prompt 与验证计划的默认工具语义。也就是说技能并非仅供人类阅读的说明而是可直接被 Agent 装载执行的角色卡——当视频流水线需要 BGM 时Agent 会先走 lyria 的决策流程再调用google_music。技能同时与 OpenMontage 的 音乐生成工具 一一对应该工具类把agent_skills [lyria]写入自身元数据并从 工具注册中心 暴露给上层 Agent。理解技能 理解工具的安全使用边界。三条模型路线先选型再动手Lyria 3 并非单一模型技能文档将其划分为三个家族Agent 必须先明确任务类型再选择模型需求场景模型契约Prompt 迭代、预览、循环乐段、精确 30 秒源lyria-3-clip-preview固定生成 30 秒 MP3当前约 $0.04/次请求完整歌曲、人声、较长曲式、图像条件化配乐lyria-3-pro-preview时长受 Prompt 影响最长约三分钟当前约 $0.08/次请求实时、可连续操控的器乐演奏lyria-realtime-exp独立 WebSocket 工作流不要路由到google_music各家族的能力边界Lyria 3 Clip适合快速试听与循环素材输入为文本或图片输出为 MP3 音频与包含歌词/曲式说明的文本时长固定 30 秒。Gemini Developer API 定价当前为 $0.04/次请求无免费额度。Lyria 3 Pro适合完整歌曲、人声、主歌/副歌/桥段与更长配乐。输入支持文本或至多 10 张图片经由底层 API输出默认 MP3底层 Pro API 可请求 audio/WAV 响应格式时长受 Prompt 影响、最多约三分钟不是精确媒体契约。定价当前为 $0.08/次请求无免费额度。Lyria RealTimelyria-realtime-exp实验性、器乐型、常驻 WebSocket 会话可连续操控 BPM、音阶、密度、亮度与引导强度。它既不属于 Interactions API也不是 OpenMontagegoogle_music使用的模型。当前适配器的硬性约束必须如实上报一个容易被忽略的事实是OpenMontage 的google_music适配器目前锁定在lyria-3-pro-preview并未暴露 Clip、WAV 响应选择、多图输入或 RealTime 控制能力。技能明确要求 Agent 在用户面前表面化这一局限而不是暗示这些选项可通过该适配器使用。例如一个 30 秒视频配乐需求可选路径只有两条要么为Pro 精确时长后期母带征得用户同意要么通过显式支持的路径改用 Clip。技能规定不得静默更换模型。源码佐证见 tools/audio/google_music.pymodel_name lyria-3-pro-preview硬编码在生成逻辑中输入 schema 也只接受一个image_url或image_path对应底层至多 10 张图能力的裁剪。生成前必须遵守的工作流技能定义了 8 步强制流程核心思想是先规划、后调用、再实测确认音乐的角色衬底铺乐underscore、循环、器乐提示短句还是完整歌曲。确认人声、语言、目标时长、曲式结构与交付格式。向用户明示提供方、确切模型、预估单次成本、本次调用是探索性还是最终交付。按下一节的契约编写一条结构化 Prompt。执行一次经批准的生成调用把任何重试都当作又一次可能计费的随机生成。原样保留返回的提供方源文件provider source不修改。先探测实际文件并试听再记录时长、格式或批准元数据。当剪辑要求精确时长时派生一份独立的生产母带production master。其中第 5、7 步直接对应 OpenAI Montage 的成本治理与质量红线Lyria 是随机性生成重试 ≠ 免费重跑duration_seconds元数据 ≠ 实际媒体时长。构建结构化 Prompt九要素与两个可直接复制的模板九要素顺序缺一不可技能要求按如下顺序穷举需求用途与时长——这段音乐支撑什么画面、需要多长。风格与时代——使用音乐术语而非模仿在世艺术家。速度与和声——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.经验是单写 no vocals 往往不够——Lyria 默认会生成人声与歌词除非 Prompt 明确且完整地请求纯器乐。模板一视频衬底配乐Video Underscore参考文档给出可直接套用的完整模板见 api-and-prompting.mdCreate an original instrumental background score for [purpose], target [N] seconds. Style: [genre/blend/era], [mood], [foreground or background role]. Tempo and harmony: [BPM], [meter], [key/scale or tonal behavior]. Instrumentation: [lead], [rhythm], [bass], [texture]. [0:00-0:06] [one musical state and entrance rule]. [0:06-0:12] [one development]. [0:12-0:15] [build or reduction that prepares the sync point]. [0:15-0:18] [exact synchronization event and required hold]. [0:18-0:30] [release and ending behavior]. Mix: [density, space, transient character, dynamic range]. Ending: [tail, final resonance, no abrupt cutoff]. Instrumental only. No vocals, speech, choir, humming, vocal chops, spoken samples, lyrical fragments, or recognizable quotations. Avoid: [unwanted instruments, clichés, oversized hits, abrupt fade].注意模板的语义定位时间戳是结构性指令不是 Pro 一定能返回精确长度文件的保证——这是下文时长不可信纪律的由来。模板二带自定义歌词的歌曲Create a [duration] [genre] song in [key] at [BPM]. Vocal profile: [range, tone, delivery, language]. Instrumentation and production: [details]. Structure: [Intro], [Verse], [Chorus], [Bridge], [Outro]. Lyrics: [Verse 1] ... [Chorus] ...歌词与制作方向必须分离制作说明写在Lyrics:块之外只有当你确实想要和声伴唱回声时才在歌词中使用圆括号。主动设计人声避免歌词跑偏的系统性方案Lyria 在 Prompt 未明确要求器乐时会默认生成人声与歌词歌词语言默认为 Prompt 语言。参考文档要求只要涉及人声写 Prompt 前就要定义五件事人声角色——主唱独唱、二重唱、对答式call-and-response、伴唱群、还是无词织体。语言与书写系统——点名歌唱语言自定义歌词保持单一有意的书写系统不静默转写、不混用代码切换。歌手画像——声部/音域、音色、力度、咬字、装饰音、情感距离不得模仿具名艺人。分轨行为——主唱何时进入、和声/回声出现在哪里、哪些段落保持纯器乐。歌词契约——方向与Lyrics:块分离使用[Verse]、[Chorus]、[Bridge]、[Outro]标签圆括号仅保留给有意的伴唱回声。技能给出一个更完整的带人声 Prompt 骨架Create a [duration] [genre] song in [key] at [BPM]. Vocal role: [solo, duet, call-and-response, or ensemble]. Singer profile: [range], [timbre], [delivery], and [diction]. Sing in [language and intended register]. Use backing vocals only for words shown in parentheses. No [unwanted vocal gestures or effects], and do not imitate a named singer. Lyrics: [Verse 1] [custom lyrics in the selected language and script] [Chorus] [lead line] ([intentional backing-vocal echo])多语言工作纪律当涉及非默认语言或双语需求时参考文档要求即使自定义歌词已经表明语言仍要显式点名歌唱语言。刻意选择书写系统或转写方案未经用户批准不得擅自转换文字系统。歌词版本内保持同一书写系统避免模型推断出意外的语言切换。描述预期语域、方言、正式度与任何有意的代码切换。把获批的歌词原文单独保存与生成 Prompt 分离。Lyria 可能改动、省略或重复歌词因此必须拿返回文本与实际演唱与源文本逐一比对。把发音与语言覆盖率当作输出级 QA。API 文档称 Lyria 会跟随 Prompt 语言但并不承诺每种语言或地域语域都发音完美。人声验收Vocal QA试听并记录以下 7 项缺一不可请求的主唱/二重唱/群唱角色是否真的出现。每行获批歌词是被唱出、省略、改动还是重复。语言、由书写系统推导的发音与预期语域是否保持一致。请求的音域、音色、力度、装饰音与分段进入是否被遵循。伴唱是否只出现在你要求的位置。主唱在混音中是否清晰可辨无削波、无被遮蔽。结尾是否包含完整的收束乐句与有音乐意义的衰减。技能特别提醒咬字或歌词遵从失败不是文件格式问题而是随机的 Prompt/遵从失败任何重试都是新的付费生成必须走已批准的 retry 策略。时长不可信探测纪律与精确时长母带Lyria 3 Pro 的时长由 Prompt 指令与时间戳控制并非 API 的精确参数。更隐蔽的是OpenMontage 适配器会在文本末尾追加目标时长指令但其返回结果中的duration_seconds字段记录的是请求值而非媒体探测值。源码佐证见 tools/audio/google_music.py 第 221-221 行附近timed_prompt f{prompt}\n\n[Target Duration: {int(duration)} seconds]而最终返回的duration_seconds: duration仍是请求值。因此技能要求生成后必须探测真实文件标准命令为ffprobe -v error -show_entries \ formatduration,format_name,bit_rate:streamcodec_name,sample_rate,channels \ -of json output.mp3若业务要求精确时长例如剪辑到帧处理纪律是保留提供方源文件不动分别记录请求时长与实测时长在音乐上有意义的边界处修剪并加短淡入淡出派生新的生产母带不得未经批准的 production plan 就拉伸、循环或重新生成记录派生过程并对母带再次执行 ffprobe 探测。参考文档还指出一个真实存在的陷阱Google 官方资料对采样率存在 44.1 kHz 与 48 kHz 的描述分歧因此每个返回文件都必须探测并记录实测值不能照抄规格。认证与诊断凭证解析优先级与失败分类凭证路径Gemini API 通常使用GEMINI_API_KEYOpenMontage 同时支持GOOGLE_API_KEY与 Vertex 服务账号凭证。凭证解析逻辑集中在 tools/google_credentials.py关键事实可核对第 58 行api_key os.environ.get(GOOGLE_API_KEY) or os.environ.get(GEMINI_API_KEY)——当两者都非空时GOOGLE_API_KEY优先于GEMINI_API_KEY。服务账号经GOOGLE_APPLICATION_CREDENTIALS指向存在的 JSON 文件生效service_account_configured()。当设置了GOOGLE_GENAI_USE_VERTEXAI/GOOGLE_GENAI_USE_ENTERPRISE为 true或未配置 API Key 但存在服务账号时走 VertexAI 分支需要 project来自GOOGLE_CLOUD_PROJECT等与 location。技能给出的安全操作规范包括每次运行只使用一条已知的凭证路径调试时绝不打印 Key 或编辑凭证文件不要假设被拒的第一个 Key 会自动回退到第二个 Key。一个容易踩坑的实现细节Lyria 3 只从 Vertex 的global 位置提供服务。因此 google_music.py 在创建客户端时显式传入locationglobal——这与 TTS/Imagen 常用的us-central1见 google_credentials.py 的resolve_google_location默认值不同迁移到其他模型时容易忽略。失败分类与处置Failure Triage技能要求把403、API_KEY_SERVICE_BLOCKED、项目/服务限制判定为认证或 Google 项目配置失败而非 Prompt 质量问题不要在权限类错误上浪费重试次数。可复用的排查表如下症状类别动作401或无效 Key认证不打印地验证所选凭证403、API_KEY_SERVICE_BLOCKED认证/项目策略停止重试修复 Google Key、项目、API 启用或服务限制429限流仅在批准的 retry/budget 策略内重试超时瞬时/提供方走工具超时策略不并行发起重复的付费调用无output_audio响应解析遍历model_output步骤内容查找audio块输出长于/短于请求模型行为保留源、探测、派生独立精确时长母带意外人声Prompt/遵从加强完整器乐排除清单试听下一次付费结果安全拒绝策略/Prompt移除艺人模仿或版权内容不伪装请求只有瞬时限流或超时失败才允许在批准的 retry 与预算策略内重试——这与工具自身声明的RetryPolicy(max_retries2, retryable_errors[rate_limit, timeout])一致见 google_music.py。适配器源码级解析一次调用背后发生了什么把技能描述与 tools/audio/google_music.py 对齐可以得到google_music的完整行为画像工具声明name google_music、provider google、capability music_generation、stability EXPERIMENTAL、determinism STOCHASTIC随机生成、runtime API、tier GENERATE。它声明支持器乐、人声、自定义歌词、风格控制与长段落最佳场景是高质量器乐 BGM 富文本 Prompt 引导 Google 生态集成不适合离线生成与 5 秒以下的音效。输入 Schema字段级参数说明参数类型/默认说明promptstring必填音乐描述情绪、风格、乐器、速度duration_secondsnumber默认 30范围 5–184目标时长模型硬上限 184 秒image_urlstring图生音乐参考图 URLimage_pathstring图生音乐本地参考图路径auto_fixboolean默认 true时长越界时自动收敛到 5/184 秒output_pathstring默认music_output.mp3输出文件路径时长钳制逻辑低于 5 秒时若auto_fix开启则强制到 5.0 秒并告警Pro 最小 5 秒高于 184 秒则钳到 184.0 秒。若关闭auto_fix则直接报错。图生音乐实现本地路径先read_bytes()并用 mimetypes 推断 MIME兜底image/png后 base64 编码URL 则先下载 30 秒超时内取回并校验Content-Type含image。最终 payload 是一个文本块 至多一个图像块的列表——这正对应技能里当前适配器只接受一个image_path或一个image_url的表述。调用与解析链client.interactions.create(modellyria-3-pro-preview, inputinput_list)发起一次 Interactions 调用音频提取顺序为interaction.output_audio→ 回退到outputs列表的inline_data→ 再回退到遍历steps中model_output类型的audio内容块。写盘前会区分 base64 字符串与原始字节通过ID3头或0xFF/0xE0的 MPEG 帧头特征判断。这一步与技能解析并记录结果一节中优先output_audio交错响应遍历model_output步骤并分离 audio 与 text 块的建议一一对应。成本与重试estimate_cost固定返回 0.08 美元Pro 每请求一口价idempotency_key_fields [prompt, duration_seconds, image_url, image_path]side_effects声明了写文件 调用 Google API两件事user_visible_verification要求用户最终试听成品的风格与质量。该行为画像可通过测试佐证tests/contracts/test_phase3_contracts.py从 google_music.py 导入GoogleMusic用 mock 客户端断言interactions.create收到的 input 内容、凭证环境变量组合GEMINI_API_KEY/GOOGLE_API_KEY、可用性判定与工具元数据name google_music是理解凭证 → 调用 → 解析契约的现成参照。解析与记录结果留下可审计的生成档案技能规定无论走哪条解析路径最终都要记录提供方与确切模型原始 Prompt 与任何图像来源provenance请求时长与探测时长实际 codec、采样率、声道数与文件路径单次调用成本与总尝试次数是否请求了人声、试听时是否实际检测到人声提供方源文件与任何单独派生的生产母带。这套记录规范与 OpenMontage 成本追踪 的设计哲学一致每一次随机生成都是可计费事件元数据必须足以支持事后审计与复现。局限性、安全与版权成稿前必须知道技能与参考文档均强调以下边界涉及归因与合规时尤其重要随机性相同的 Prompt 可能产生不同结果重试即新一次付费生成。单轮生成Lyria 3 是 single-turn当前无法通过多轮编辑链精修已生成曲目。安全过滤安全过滤器可能拒绝艺人嗓音模仿、受版权歌词或其他受限内容拒绝时应移除违规请求而非伪装它。SynthID 水印所有生成音频都包含不可感知的 SynthID 水印——在需要 provenance 的场景中应如实声明。Preview 不稳定preview 模型与限流策略在稳定版发布前可能变化定价与额度请以官方页面为准本仓库只记录撰写时的数值。采样率分歧官方资料在 44.1 kHz / 48 kHz 间存在不一致描述——探测每个文件并记录实测值。质量验收红线技能 Quality Checklist 浓缩版Prompt 覆盖了用途、速度、配器、结构、力度、人声策略与收尾。时间戳窗口覆盖完整目标时长且无自相矛盾。未请求艺人模仿或版权歌词。输出文件存在、非空、可解码且含音频流。实际时长与技术属性来自探测而非请求元数据。器乐输出检查过意外人声开场、同步点、转场与结尾都经试听。未经修改的源被保留任何生产母带都有明确 provenance。涉及 provenance 时承认 SynthID 水印与 preview 模型的不稳定性。按此纪律交付的每一次配乐都能同时通过技术质量、成本审计与版权合规三重检查——这正是lyria技能文档希望所有 Agent 与开发者养成的肌肉记忆。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMontage × Google Lyria 3：基于 Gemini Interactions API 的音乐生成、Prompt 编排与质量验证指南
OpenMontage × Google Lyria 3基于 Gemini Interactions API 的音乐生成、Prompt 编排与质量验证指南【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本指南围绕 OpenMontage 仓库中的lyriaAgent 技能文档.agents/skills/lyria/SKILL.md 及其参考文档 api-and-prompting.md展开面向三类读者需要通过 OpenMontagegoogle_music工具为视频成片配乐的创作者、希望用 Agent 自动化生成 → 校验 → 归档完整链路的技术用户以及需要深入理解该工具底层实现的开发者。读完本文你将掌握 Lyria 3 Clip / Pro / RealTime 的选型逻辑、可复制的结构化 Prompt 模板、人声与自定义歌词的编排契约、时长不可信前提下的 ffprobe 探测纪律以及 Google 凭证与失败分类的排障清单。OpenMontage 定位为开源的 Agentic 视频生产系统其音乐能力由google_music工具对接 Google Lyria 3 提供。为了让 AI 助手Agent在与工具交互前就具备足够的领域知识仓库把整套使用规范沉淀为lyria技能技能文件定义了强制性工作流与质量红线参考文档补全了 API 形状与 Prompt 模板二者共同约束 Agent 不得盲调接口、盲信返回、不试听即验收。lyria技能在 OpenMontage 中的角色lyria技能位于仓库 .agents/skills/lyria/SKILL.md其 frontmatter 声明了适用范围生成并校验 Google Lyria 3 音乐、设计 Lyria 3 Clip / Pro Prompt、使用图生音乐或自定义歌词、在 Lyria 3 与 Lyria RealTime 之间选型、诊断 Google 音乐生成失败以及为视频准备精确时长的音乐。该技能还附带一个 Agent 接口声明 .agents/skills/lyria/agents/openai.yaml其中把$lyria定义为设计一份生产级 Lyria 3 音乐生成 Prompt 与验证计划的默认工具语义。也就是说技能并非仅供人类阅读的说明而是可直接被 Agent 装载执行的角色卡——当视频流水线需要 BGM 时Agent 会先走 lyria 的决策流程再调用google_music。技能同时与 OpenMontage 的 音乐生成工具 一一对应该工具类把agent_skills [lyria]写入自身元数据并从 工具注册中心 暴露给上层 Agent。理解技能 理解工具的安全使用边界。三条模型路线先选型再动手Lyria 3 并非单一模型技能文档将其划分为三个家族Agent 必须先明确任务类型再选择模型需求场景模型契约Prompt 迭代、预览、循环乐段、精确 30 秒源lyria-3-clip-preview固定生成 30 秒 MP3当前约 $0.04/次请求完整歌曲、人声、较长曲式、图像条件化配乐lyria-3-pro-preview时长受 Prompt 影响最长约三分钟当前约 $0.08/次请求实时、可连续操控的器乐演奏lyria-realtime-exp独立 WebSocket 工作流不要路由到google_music各家族的能力边界Lyria 3 Clip适合快速试听与循环素材输入为文本或图片输出为 MP3 音频与包含歌词/曲式说明的文本时长固定 30 秒。Gemini Developer API 定价当前为 $0.04/次请求无免费额度。Lyria 3 Pro适合完整歌曲、人声、主歌/副歌/桥段与更长配乐。输入支持文本或至多 10 张图片经由底层 API输出默认 MP3底层 Pro API 可请求 audio/WAV 响应格式时长受 Prompt 影响、最多约三分钟不是精确媒体契约。定价当前为 $0.08/次请求无免费额度。Lyria RealTimelyria-realtime-exp实验性、器乐型、常驻 WebSocket 会话可连续操控 BPM、音阶、密度、亮度与引导强度。它既不属于 Interactions API也不是 OpenMontagegoogle_music使用的模型。当前适配器的硬性约束必须如实上报一个容易被忽略的事实是OpenMontage 的google_music适配器目前锁定在lyria-3-pro-preview并未暴露 Clip、WAV 响应选择、多图输入或 RealTime 控制能力。技能明确要求 Agent 在用户面前表面化这一局限而不是暗示这些选项可通过该适配器使用。例如一个 30 秒视频配乐需求可选路径只有两条要么为Pro 精确时长后期母带征得用户同意要么通过显式支持的路径改用 Clip。技能规定不得静默更换模型。源码佐证见 tools/audio/google_music.pymodel_name lyria-3-pro-preview硬编码在生成逻辑中输入 schema 也只接受一个image_url或image_path对应底层至多 10 张图能力的裁剪。生成前必须遵守的工作流技能定义了 8 步强制流程核心思想是先规划、后调用、再实测确认音乐的角色衬底铺乐underscore、循环、器乐提示短句还是完整歌曲。确认人声、语言、目标时长、曲式结构与交付格式。向用户明示提供方、确切模型、预估单次成本、本次调用是探索性还是最终交付。按下一节的契约编写一条结构化 Prompt。执行一次经批准的生成调用把任何重试都当作又一次可能计费的随机生成。原样保留返回的提供方源文件provider source不修改。先探测实际文件并试听再记录时长、格式或批准元数据。当剪辑要求精确时长时派生一份独立的生产母带production master。其中第 5、7 步直接对应 OpenAI Montage 的成本治理与质量红线Lyria 是随机性生成重试 ≠ 免费重跑duration_seconds元数据 ≠ 实际媒体时长。构建结构化 Prompt九要素与两个可直接复制的模板九要素顺序缺一不可技能要求按如下顺序穷举需求用途与时长——这段音乐支撑什么画面、需要多长。风格与时代——使用音乐术语而非模仿在世艺术家。速度与和声——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.经验是单写 no vocals 往往不够——Lyria 默认会生成人声与歌词除非 Prompt 明确且完整地请求纯器乐。模板一视频衬底配乐Video Underscore参考文档给出可直接套用的完整模板见 api-and-prompting.mdCreate an original instrumental background score for [purpose], target [N] seconds. Style: [genre/blend/era], [mood], [foreground or background role]. Tempo and harmony: [BPM], [meter], [key/scale or tonal behavior]. Instrumentation: [lead], [rhythm], [bass], [texture]. [0:00-0:06] [one musical state and entrance rule]. [0:06-0:12] [one development]. [0:12-0:15] [build or reduction that prepares the sync point]. [0:15-0:18] [exact synchronization event and required hold]. [0:18-0:30] [release and ending behavior]. Mix: [density, space, transient character, dynamic range]. Ending: [tail, final resonance, no abrupt cutoff]. Instrumental only. No vocals, speech, choir, humming, vocal chops, spoken samples, lyrical fragments, or recognizable quotations. Avoid: [unwanted instruments, clichés, oversized hits, abrupt fade].注意模板的语义定位时间戳是结构性指令不是 Pro 一定能返回精确长度文件的保证——这是下文时长不可信纪律的由来。模板二带自定义歌词的歌曲Create a [duration] [genre] song in [key] at [BPM]. Vocal profile: [range, tone, delivery, language]. Instrumentation and production: [details]. Structure: [Intro], [Verse], [Chorus], [Bridge], [Outro]. Lyrics: [Verse 1] ... [Chorus] ...歌词与制作方向必须分离制作说明写在Lyrics:块之外只有当你确实想要和声伴唱回声时才在歌词中使用圆括号。主动设计人声避免歌词跑偏的系统性方案Lyria 在 Prompt 未明确要求器乐时会默认生成人声与歌词歌词语言默认为 Prompt 语言。参考文档要求只要涉及人声写 Prompt 前就要定义五件事人声角色——主唱独唱、二重唱、对答式call-and-response、伴唱群、还是无词织体。语言与书写系统——点名歌唱语言自定义歌词保持单一有意的书写系统不静默转写、不混用代码切换。歌手画像——声部/音域、音色、力度、咬字、装饰音、情感距离不得模仿具名艺人。分轨行为——主唱何时进入、和声/回声出现在哪里、哪些段落保持纯器乐。歌词契约——方向与Lyrics:块分离使用[Verse]、[Chorus]、[Bridge]、[Outro]标签圆括号仅保留给有意的伴唱回声。技能给出一个更完整的带人声 Prompt 骨架Create a [duration] [genre] song in [key] at [BPM]. Vocal role: [solo, duet, call-and-response, or ensemble]. Singer profile: [range], [timbre], [delivery], and [diction]. Sing in [language and intended register]. Use backing vocals only for words shown in parentheses. No [unwanted vocal gestures or effects], and do not imitate a named singer. Lyrics: [Verse 1] [custom lyrics in the selected language and script] [Chorus] [lead line] ([intentional backing-vocal echo])多语言工作纪律当涉及非默认语言或双语需求时参考文档要求即使自定义歌词已经表明语言仍要显式点名歌唱语言。刻意选择书写系统或转写方案未经用户批准不得擅自转换文字系统。歌词版本内保持同一书写系统避免模型推断出意外的语言切换。描述预期语域、方言、正式度与任何有意的代码切换。把获批的歌词原文单独保存与生成 Prompt 分离。Lyria 可能改动、省略或重复歌词因此必须拿返回文本与实际演唱与源文本逐一比对。把发音与语言覆盖率当作输出级 QA。API 文档称 Lyria 会跟随 Prompt 语言但并不承诺每种语言或地域语域都发音完美。人声验收Vocal QA试听并记录以下 7 项缺一不可请求的主唱/二重唱/群唱角色是否真的出现。每行获批歌词是被唱出、省略、改动还是重复。语言、由书写系统推导的发音与预期语域是否保持一致。请求的音域、音色、力度、装饰音与分段进入是否被遵循。伴唱是否只出现在你要求的位置。主唱在混音中是否清晰可辨无削波、无被遮蔽。结尾是否包含完整的收束乐句与有音乐意义的衰减。技能特别提醒咬字或歌词遵从失败不是文件格式问题而是随机的 Prompt/遵从失败任何重试都是新的付费生成必须走已批准的 retry 策略。时长不可信探测纪律与精确时长母带Lyria 3 Pro 的时长由 Prompt 指令与时间戳控制并非 API 的精确参数。更隐蔽的是OpenMontage 适配器会在文本末尾追加目标时长指令但其返回结果中的duration_seconds字段记录的是请求值而非媒体探测值。源码佐证见 tools/audio/google_music.py 第 221-221 行附近timed_prompt f{prompt}\n\n[Target Duration: {int(duration)} seconds]而最终返回的duration_seconds: duration仍是请求值。因此技能要求生成后必须探测真实文件标准命令为ffprobe -v error -show_entries \ formatduration,format_name,bit_rate:streamcodec_name,sample_rate,channels \ -of json output.mp3若业务要求精确时长例如剪辑到帧处理纪律是保留提供方源文件不动分别记录请求时长与实测时长在音乐上有意义的边界处修剪并加短淡入淡出派生新的生产母带不得未经批准的 production plan 就拉伸、循环或重新生成记录派生过程并对母带再次执行 ffprobe 探测。参考文档还指出一个真实存在的陷阱Google 官方资料对采样率存在 44.1 kHz 与 48 kHz 的描述分歧因此每个返回文件都必须探测并记录实测值不能照抄规格。认证与诊断凭证解析优先级与失败分类凭证路径Gemini API 通常使用GEMINI_API_KEYOpenMontage 同时支持GOOGLE_API_KEY与 Vertex 服务账号凭证。凭证解析逻辑集中在 tools/google_credentials.py关键事实可核对第 58 行api_key os.environ.get(GOOGLE_API_KEY) or os.environ.get(GEMINI_API_KEY)——当两者都非空时GOOGLE_API_KEY优先于GEMINI_API_KEY。服务账号经GOOGLE_APPLICATION_CREDENTIALS指向存在的 JSON 文件生效service_account_configured()。当设置了GOOGLE_GENAI_USE_VERTEXAI/GOOGLE_GENAI_USE_ENTERPRISE为 true或未配置 API Key 但存在服务账号时走 VertexAI 分支需要 project来自GOOGLE_CLOUD_PROJECT等与 location。技能给出的安全操作规范包括每次运行只使用一条已知的凭证路径调试时绝不打印 Key 或编辑凭证文件不要假设被拒的第一个 Key 会自动回退到第二个 Key。一个容易踩坑的实现细节Lyria 3 只从 Vertex 的global 位置提供服务。因此 google_music.py 在创建客户端时显式传入locationglobal——这与 TTS/Imagen 常用的us-central1见 google_credentials.py 的resolve_google_location默认值不同迁移到其他模型时容易忽略。失败分类与处置Failure Triage技能要求把403、API_KEY_SERVICE_BLOCKED、项目/服务限制判定为认证或 Google 项目配置失败而非 Prompt 质量问题不要在权限类错误上浪费重试次数。可复用的排查表如下症状类别动作401或无效 Key认证不打印地验证所选凭证403、API_KEY_SERVICE_BLOCKED认证/项目策略停止重试修复 Google Key、项目、API 启用或服务限制429限流仅在批准的 retry/budget 策略内重试超时瞬时/提供方走工具超时策略不并行发起重复的付费调用无output_audio响应解析遍历model_output步骤内容查找audio块输出长于/短于请求模型行为保留源、探测、派生独立精确时长母带意外人声Prompt/遵从加强完整器乐排除清单试听下一次付费结果安全拒绝策略/Prompt移除艺人模仿或版权内容不伪装请求只有瞬时限流或超时失败才允许在批准的 retry 与预算策略内重试——这与工具自身声明的RetryPolicy(max_retries2, retryable_errors[rate_limit, timeout])一致见 google_music.py。适配器源码级解析一次调用背后发生了什么把技能描述与 tools/audio/google_music.py 对齐可以得到google_music的完整行为画像工具声明name google_music、provider google、capability music_generation、stability EXPERIMENTAL、determinism STOCHASTIC随机生成、runtime API、tier GENERATE。它声明支持器乐、人声、自定义歌词、风格控制与长段落最佳场景是高质量器乐 BGM 富文本 Prompt 引导 Google 生态集成不适合离线生成与 5 秒以下的音效。输入 Schema字段级参数说明参数类型/默认说明promptstring必填音乐描述情绪、风格、乐器、速度duration_secondsnumber默认 30范围 5–184目标时长模型硬上限 184 秒image_urlstring图生音乐参考图 URLimage_pathstring图生音乐本地参考图路径auto_fixboolean默认 true时长越界时自动收敛到 5/184 秒output_pathstring默认music_output.mp3输出文件路径时长钳制逻辑低于 5 秒时若auto_fix开启则强制到 5.0 秒并告警Pro 最小 5 秒高于 184 秒则钳到 184.0 秒。若关闭auto_fix则直接报错。图生音乐实现本地路径先read_bytes()并用 mimetypes 推断 MIME兜底image/png后 base64 编码URL 则先下载 30 秒超时内取回并校验Content-Type含image。最终 payload 是一个文本块 至多一个图像块的列表——这正对应技能里当前适配器只接受一个image_path或一个image_url的表述。调用与解析链client.interactions.create(modellyria-3-pro-preview, inputinput_list)发起一次 Interactions 调用音频提取顺序为interaction.output_audio→ 回退到outputs列表的inline_data→ 再回退到遍历steps中model_output类型的audio内容块。写盘前会区分 base64 字符串与原始字节通过ID3头或0xFF/0xE0的 MPEG 帧头特征判断。这一步与技能解析并记录结果一节中优先output_audio交错响应遍历model_output步骤并分离 audio 与 text 块的建议一一对应。成本与重试estimate_cost固定返回 0.08 美元Pro 每请求一口价idempotency_key_fields [prompt, duration_seconds, image_url, image_path]side_effects声明了写文件 调用 Google API两件事user_visible_verification要求用户最终试听成品的风格与质量。该行为画像可通过测试佐证tests/contracts/test_phase3_contracts.py从 google_music.py 导入GoogleMusic用 mock 客户端断言interactions.create收到的 input 内容、凭证环境变量组合GEMINI_API_KEY/GOOGLE_API_KEY、可用性判定与工具元数据name google_music是理解凭证 → 调用 → 解析契约的现成参照。解析与记录结果留下可审计的生成档案技能规定无论走哪条解析路径最终都要记录提供方与确切模型原始 Prompt 与任何图像来源provenance请求时长与探测时长实际 codec、采样率、声道数与文件路径单次调用成本与总尝试次数是否请求了人声、试听时是否实际检测到人声提供方源文件与任何单独派生的生产母带。这套记录规范与 OpenMontage 成本追踪 的设计哲学一致每一次随机生成都是可计费事件元数据必须足以支持事后审计与复现。局限性、安全与版权成稿前必须知道技能与参考文档均强调以下边界涉及归因与合规时尤其重要随机性相同的 Prompt 可能产生不同结果重试即新一次付费生成。单轮生成Lyria 3 是 single-turn当前无法通过多轮编辑链精修已生成曲目。安全过滤安全过滤器可能拒绝艺人嗓音模仿、受版权歌词或其他受限内容拒绝时应移除违规请求而非伪装它。SynthID 水印所有生成音频都包含不可感知的 SynthID 水印——在需要 provenance 的场景中应如实声明。Preview 不稳定preview 模型与限流策略在稳定版发布前可能变化定价与额度请以官方页面为准本仓库只记录撰写时的数值。采样率分歧官方资料在 44.1 kHz / 48 kHz 间存在不一致描述——探测每个文件并记录实测值。质量验收红线技能 Quality Checklist 浓缩版Prompt 覆盖了用途、速度、配器、结构、力度、人声策略与收尾。时间戳窗口覆盖完整目标时长且无自相矛盾。未请求艺人模仿或版权歌词。输出文件存在、非空、可解码且含音频流。实际时长与技术属性来自探测而非请求元数据。器乐输出检查过意外人声开场、同步点、转场与结尾都经试听。未经修改的源被保留任何生产母带都有明确 provenance。涉及 provenance 时承认 SynthID 水印与 preview 模型的不稳定性。按此纪律交付的每一次配乐都能同时通过技术质量、成本审计与版权合规三重检查——这正是lyria技能文档希望所有 Agent 与开发者养成的肌肉记忆。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考