Gemini 2.5 Flash Image（又称 Nano Banana）现已在 Gemini API 中提供！了解详情

此页面由 Cloud Translation API 翻译。

使用 Lyria RealTime 生成音乐

Gemini API 使用 Lyria RealTime，可访问先进的实时流式音乐生成模型。它允许开发者构建应用，让用户能够以交互方式创作乐曲、持续引导乐曲的演奏，以及演奏乐器音乐。

如需体验使用 Lyria RealTime 可以构建哪些内容，请在 AI Studio 中使用 Prompt DJ 或 MIDI DJ 应用进行尝试！

音乐生成功能的运作方式

Lyria RealTime 音乐生成功能使用基于 WebSocket 的持久性双向低延迟流式传输连接。

生成和控制音乐

从某种意义上说，Lyria RealTime 的工作方式与 Live API 有点类似，因为它使用 WebSocket 与模型保持实时通信。不过，它仍然与人类对话不太一样，因为您无法与模型对话，并且必须使用特定格式来提示模型。

以下代码演示了如何生成音乐：

Python

此示例使用 client.aio.live.music.connect() 初始化 Lyria RealTime 会话，然后使用 session.set_weighted_prompts() 发送初始提示，同时使用 session.set_music_generation_config 发送初始配置，使用 session.play() 开始生成音乐，并设置 receive_audio() 来处理收到的音频块。

  import asyncio
  from google import genai
  from google.genai import types

  client = genai.Client(http_options={'api_version': 'v1alpha'})

  async def main():
      async def receive_audio(session):
        """Example background task to process incoming audio."""
        while True:
          async for message in session.receive():
            audio_data = message.server_content.audio_chunks[0].data
            # Process audio...
            await asyncio.sleep(10**-12)

      async with (
        client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
        asyncio.TaskGroup() as tg,
      ):
        # Set up task to receive server messages.
        tg.create_task(receive_audio(session))

        # Send initial prompts and config
        await session.set_weighted_prompts(
          prompts=[
            types.WeightedPrompt(text='minimal techno', weight=1.0),
          ]
        )
        await session.set_music_generation_config(
          config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
        )

        # Start streaming music
        await session.play()
  if __name__ == "__main__":
      asyncio.run(main())

JavaScript

此示例使用 client.live.music.connect() 初始化 Lyria RealTime 会话，然后使用 session.setWeightedPrompts() 发送初始提示，同时使用 session.setMusicGenerationConfig 发送初始配置，使用 session.play() 开始生成音乐，并设置 onMessage 回调来处理收到的音频块。

import { GoogleGenAI } from "@google/genai";
import Speaker from "speaker";
import { Buffer } from "buffer";

const client = new GoogleGenAI({
  apiKey: GEMINI_API_KEY,
    apiVersion: "v1alpha" ,
});

async function main() {
  const speaker = new Speaker({
    channels: 2,       // stereo
    bitDepth: 16,      // 16-bit PCM
    sampleRate: 44100, // 44.1 kHz
  });

  const session = await client.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
      onmessage: (message) => {
        if (message.serverContent?.audioChunks) {
          for (const chunk of message.serverContent.audioChunks) {
            const audioBuffer = Buffer.from(chunk.data, "base64");
            speaker.write(audioBuffer);
          }
        }
      },
      onerror: (error) => console.error("music session error:", error),
      onclose: () => console.log("Lyria RealTime stream closed."),
    },
  });

  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: "Minimal techno with deep bass, sparse percussion, and atmospheric synths", weight: 1.0 },
    ],
  });

  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 90,
      temperature: 1.0,
      audioFormat: "pcm16",  // important so we know format
      sampleRateHz: 44100,
    },
  });

  await session.play();
}

main().catch(console.error);

然后，您可以使用 session.play()、session.pause()、session.stop() 和 session.reset_context() 来开始、暂停、停止或重置会话。

实时控制音乐

提示 Lyria RealTime

在直播期间，您可以随时发送新的 WeightedPrompt 消息来改变生成的音乐。模型将根据新输入内容平稳过渡。

提示需要采用正确的格式，包含 text（实际提示）和 weight。weight 可以采用除 0 之外的任何值。1.0 通常是一个不错的起点。

Python

  await session.set_weighted_prompts(
    prompts=[
      {"text": "Piano", "weight": 2.0},
      types.WeightedPrompt(text="Meditation", weight=0.5),
      types.WeightedPrompt(text="Live Performance", weight=1.0),
    ]
  )

JavaScript

  await session.setMusicGenerationConfig({
    weightedPrompts: [
      { text: 'Harmonica', weight: 0.3 },
      { text: 'Afrobeat', weight: 0.7 }
    ],
  });

请注意，大幅更改提示时，模型过渡可能会有些突兀，因此建议通过向模型发送中间权重值来实现某种淡入淡出效果。

更新配置

您还可以实时更新音乐生成参数。您不能只更新一个参数，而需要设置整个配置，否则其他字段将重置回其默认值。

由于更新每分钟节拍数或音阶对模型来说是一项重大更改，因此您还需要使用 reset_context() 指示模型重置其上下文，以便将新配置纳入考虑范围。这不会停止视频流，但会造成硬过渡。您无需对其他参数执行此操作。

Python

  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(
      bpm=128,
      scale=types.Scale.D_MAJOR_B_MINOR,
      music_generation_mode=types.MusicGenerationMode.QUALITY
    )
  )
  await session.reset_context();

JavaScript

  await session.setMusicGenerationConfig({
    musicGenerationConfig: { 
      bpm: 120,
      density: 0.75,
      musicGenerationMode: MusicGenerationMode.QUALITY
    },
  });
  await session.reset_context();

Lyria RealTime 提示指南

以下列出了一些可用于提示 Lyria RealTime 的提示，但并非详尽无遗：

乐器：303 Acid Bass, 808 Hip Hop Beat, Accordion, Alto Saxophone, Bagpipes, Balalaika Ensemble, Banjo, Bass Clarinet, Bongos, Boomy Bass, Bouzouki, Buchla Synths, Cello, Charango, Clavichord, Conga Drums, Didgeridoo, Dirty Synths, Djembe, Drumline, Dulcimer, Fiddle, Flamenco Guitar, Funk Drums, Glockenspiel, Guitar, Hang Drum, Harmonica, Harp, Harpsichord, Hurdy-gurdy, Kalimba, Koto, Lyre, Mandolin, Maracas, Marimba, Mbira, Mellotron, Metallic Twang, Moog Oscillations, Ocarina, Persian Tar, Pipa, Precision Bass, Ragtime Piano, Rhodes Piano, Shamisen, Shredding Guitar, Sitar, Slide Guitar, Smooth Pianos, Spacey Synths, Steel Drum, Synth Pads, Tabla, TR-909 Drum Machine, Trumpet, Tuba, Vibraphone, Viola Ensemble, Warm Acoustic Guitar, Woodwinds, ...
音乐流派：Acid Jazz, Afrobeat, Alternative Country, Baroque, Bengal Baul, Bhangra, Bluegrass, Blues Rock, Bossa Nova, Breakbeat, Celtic Folk, Chillout, Chiptune, Classic Rock, Contemporary R&B, Cumbia, Deep House, Disco Funk, Drum & Bass, Dubstep, EDM, Electro Swing, Funk Metal, G-funk, Garage Rock, Glitch Hop, Grime, Hyperpop, Indian Classical, Indie Electronic, Indie Folk, Indie Pop, Irish Folk, Jam Band, Jamaican Dub, Jazz Fusion, Latin Jazz, Lo-Fi Hip Hop, Marching Band, Merengue, New Jack Swing, Minimal Techno, Moombahton, Neo-Soul, Orchestral Score, Piano Ballad, Polka, Post-Punk, 60s Psychedelic Rock, Psytrance, R&B, Reggae, Reggaeton, Renaissance Music, Salsa, Shoegaze, Ska, Surf Rock, Synthpop, Techno, Trance, Trap Beat, Trip Hop, Vaporwave, Witch house, ...
情绪/说明：Acoustic Instruments, Ambient, Bright Tones, Chill, Crunchy Distortion, Danceable, Dreamy, Echo, Emotional, Ethereal Ambience, Experimental, Fat Beats, Funky, Glitchy Effects, Huge Drop, Live Performance, Lo-fi, Ominous Drone, Psychedelic, Rich Orchestration, Saturated Tones, Subdued Melody, Sustained Chords, Swirling Phasers, Tight Groove, Unsettling, Upbeat, Virtuoso, Weird Noises, ...

以上只是一些示例，Lyria RealTime 的功能远不止于此。尝试使用自己的提示！

最佳做法

客户端应用必须实现强大的音频缓冲，以确保流畅播放。这有助于应对网络抖动和生成延迟的细微变化。
有效的提示：
- 客观描述。使用描述情绪、流派和乐器的形容词。
- 逐步迭代和调整。与其完全更改提示，不如尝试添加或修改元素，以便更顺畅地转换音乐。
- 尝试调整 WeightedPrompt 的权重，以影响新提示对正在进行的生成过程的影响程度。

技术详情

本部分详细介绍了如何使用 Lyria RealTime 音乐生成功能。

规格

输出格式：原始 16 位 PCM 音频
采样率：48kHz
声道：2（立体声）

控件

您可以通过发送包含以下内容的讯息来实时影响音乐生成：

WeightedPrompt：描述音乐创意、流派、乐器、情绪或特征的文本字符串。您可以提供多个提示，以融合不同的影响。如需详细了解如何以最佳方式提示 Lyria RealTime，请参阅上文。
MusicGenerationConfig：音乐生成过程的配置，会影响输出音频的特征。参数包括：
- guidance：（浮点数）范围：[0.0, 6.0]。默认值：4.0。控制模型遵循提示的严格程度。指导值越高，模型对提示的遵循程度就越高，但转场效果会更突兀。
- bpm：（整数）范围：[60, 200]。设置您希望生成的音乐达到的每分钟节拍数。您需要停止/播放或重置模型的上下文，以便模型将新的每分钟节拍数纳入考虑范围。
- density：（浮点数）范围：[0.0, 1.0]。控制音符/声音的密度。值越低，生成的音乐越稀疏；值越高，生成的音乐越“繁忙”。
- brightness：（浮点数）范围：[0.0, 1.0]。调整音调。值越高，音频听起来就越“明亮”，通常会强调高频。
- scale：(Enum) 设置生成音乐的音阶（调和模式）。使用 SDK 提供的 Scale 枚举值。您需要停止/播放或重置模型的上下文，以便模型将新比例纳入考虑范围。
- mute_bass：（布尔值）默认值：False。控制模型是否降低输出的低音。
- mute_drums：（布尔值）默认值：False。控制模型输出是否会减少输出的鼓声。
- only_bass_and_drums：（布尔值）默认值：False。引导模型尝试仅输出贝斯和鼓。
- music_generation_mode：（枚举）向模型表明它应侧重于音乐的 QUALITY（默认值）还是 DIVERSITY。也可以将其设置为 VOCALIZATION，让模型生成发声作为另一种乐器（将其添加为新的提示）。
PlaybackControl：用于控制播放方面的命令，例如播放、暂停、停止或重置上下文。

对于 bpm、density、brightness 和 scale，如果未提供值，模型将根据您的初始提示决定最佳值。

MusicGenerationConfig 中还可自定义更多经典形参，例如 temperature（0.0 到 3.0，默认值为 1.1）、top_k（1 到 1000，默认值为 40）和 seed（0 到 2147483647，默认情况下随机选择）。

缩放枚举值

以下是模型可以接受的所有比例值：

枚举值	规模 / 关键
`C_MAJOR_A_MINOR`	C 大调 / A 小调
`D_FLAT_MAJOR_B_FLAT_MINOR`	D♭ 大调 / B♭ 小调
`D_MAJOR_B_MINOR`	D 大调 / B 小调
`E_FLAT_MAJOR_C_MINOR`	E♭ 大调 / C 小调
`E_MAJOR_D_FLAT_MINOR`	E 大调 / C♯/D♭ 小调
`F_MAJOR_D_MINOR`	F 大调 / D 小调
`G_FLAT_MAJOR_E_FLAT_MINOR`	G♭ 大调 / E♭ 小调
`G_MAJOR_E_MINOR`	G 大调 / E 小调
`A_FLAT_MAJOR_F_MINOR`	A♭ 大调 / F 小调
`A_MAJOR_G_FLAT_MINOR`	A 大调 / F♯/G♭ 小调
`B_FLAT_MAJOR_G_MINOR`	降 B 大调 / G 小调
`B_MAJOR_A_FLAT_MINOR`	B 大调 / G♯/A♭ 小调
`SCALE_UNSPECIFIED`	默认值 / 由模型决定

该模型能够指导演奏的音符，但无法区分相对调。因此，每个枚举都同时对应于相对主版本和次版本。例如，C_MAJOR_A_MINOR 对应于钢琴的所有白键，而 F_MAJOR_D_MINOR 对应于除降 B 之外的所有白键。

限制

仅乐器：模型仅生成乐器音乐。
安全性：提示会经过安全过滤器的检查。系统会忽略触发过滤条件的提示，在这种情况下，输出的 filtered_prompt 字段中会写入说明。
添加水印：输出音频始终会添加水印，以便根据我们的 Responsible AI 原则进行识别。

后续步骤

了解如何使用 TTS 模型生成多说话人对话，而不是生成音乐，
了解如何生成图片或视频，
了解 Gemini 如何理解音频文件，而不是生成音乐或音频，
使用 Live API 与 Gemini 进行实时对话。

如需查看更多代码示例和教程，请探索食谱。