Repository Public
1# Generate music with Lyria 323> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67Lyria 3 is Google's family of music generation models, available8through the Gemini API. With Lyria 3, you can generate9high-quality, 44.1 kHz stereo audio from text prompts or from images. These10models deliver structural coherence, including vocals, timed lyrics, and full11instrumental arrangements.1213The Lyria 3 family includes two models:1415| Model | Model ID | Best for | Duration | Output |16|---|---|---|---|---|17| **Lyria 3 Clip** | `lyria-3-clip-preview` | Short clips, loops, previews | 30 seconds | MP3 |18| **Lyria 3 Pro** | `lyria-3-pro-preview` | Full-length songs with verses, choruses, bridges | A couple of minutes (controllable using prompt) | MP3 |1920Both models can be used using the new21[Interactions API](https://ai.google.dev/gemini-api/docs/interactions), supporting multimodal22inputs (text and images), and produce **44.1 kHz high-fidelity stereo**23audio.2425> [!NOTE]26> **Note:** Looking for real-time, streaming music generation? See [Real-time music generation with Lyria RealTime](https://ai.google.dev/gemini-api/docs/interactions/realtime-music-generation).2728## Generate a music clip2930The Lyria 3 Clip model always generates a **30-second** clip. To generate a31clip, call the `interactions.create` method with a text prompt. The response32always includes the generated lyrics and song structure alongside the audio in33the `steps` schema.3435### Python3637 import base6438 from google import genai3940 client = genai.Client()4142 interaction = client.interactions.create(43 model="lyria-3-clip-preview",44 input="A short instrumental acoustic guitar piece.",45 )4647 generated_audio = interaction.output_audio48 if generated_audio:49 with open("music.mp3", "wb") as f:50 f.write(base64.b64decode(generated_audio.data))5152 lyrics = interaction.output_text53 if lyrics:54 print(f"Lyrics:\n{lyrics}")5556### JavaScript5758 import { GoogleGenAI } from '@google/genai';59 import * as fs from 'fs';6061 const client = new GoogleGenAI({});6263 const interaction = await client.interactions.create({64 model: 'lyria-3-clip-preview',65 input: 'A short instrumental acoustic guitar piece.',66 });6768 const generatedAudio = interaction.output_audio;69 if (generatedAudio) {70 fs.writeFileSync('music.mp3', Buffer.from(generatedAudio.data, 'base64'));71 }7273 const lyrics = interaction.output_text;74 if (lyrics) {75 console.log(`Lyrics:\n${lyrics}`);76 }7778### REST7980 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \81 -H "Content-Type: application/json" \82 -H "Api-Revision: 2026-05-20" \83 -H "x-goog-api-key: $GEMINI_API_KEY" \84 -d '{85 "model": "lyria-3-clip-preview",86 "input": "A short instrumental acoustic guitar piece."87 }'8889You can retrieve generated music data by using the `interaction.output_audio`90property, which returns the last generated audio block. You can also retrieve91the song's lyrics and structure by using the `interaction.output_text`92property. For details on convenience properties, see the93[Interactions overview](https://ai.google.dev/gemini-api/docs/interactions#convenience-properties).9495> [!NOTE]96> **Note:** For complex, interleaved multimodal responses (such as music containing both raw structural breakdowns and audio blocks), convenience properties may not capture all parts. You must manually iterate over the steps instead---see [Interleaved lyrics and music](https://ai.google.dev/gemini-api/docs/interactions/music-generation#interleaved-output) for an example.9798## Generate a full-length song99100Use the `lyria-3-pro-preview` model to generate full-length songs that last a101couple of minutes. The Pro model understands musical structure and can create102compositions with distinct verses, choruses, and bridges. You can influence the103duration by specifying it in your prompt (e.g., "create a 2-minute song") or by104using [timestamps](https://ai.google.dev/gemini-api/docs/interactions/music-generation#timing) to define the structure.105106### Python107108 interaction = client.interactions.create(109 model="lyria-3-pro-preview",110 input="An epic cinematic orchestral piece about a journey home. Starts with a solo piano intro, builds through sweeping strings, and climaxes with a massive wall of sound.",111 )112113### JavaScript114115 const interaction = await client.interactions.create({116 model: 'lyria-3-pro-preview',117 input: 'A beautiful piano melody.',118 });119120### REST121122 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \123 -H "Content-Type: application/json" \124 -H "Api-Revision: 2026-05-20" \125 -H "x-goog-api-key: $GEMINI_API_KEY" \126 -d '{127 "model": "lyria-3-pro-preview",128 "input": "A beautiful piano melody."129 }'130131## Select output format132133By default, the Lyria 3 models generate audio in **MP3** format. For134Lyria 3 Pro, you can also request the output in **WAV** format by setting135the `response_format`.136137### Python138139 interaction = client.interactions.create(140 model="lyria-3-pro-preview",141 input="A beautiful piano melody.",142 response_format={"type": "audio"},143 )144145### JavaScript146147 const interaction = await client.interactions.create({148 model: 'lyria-3-pro-preview',149 input: 'A beautiful piano melody.',150 response_format: {151 type: 'audio',152 },153 });154155### REST156157 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \158 -H "x-goog-api-key: $GEMINI_API_KEY" \159 -H "Api-Revision: 2026-05-20" \160 -H "Content-Type: application/json" \161 -d '{162 "model": "lyria-3-pro-preview",163 "input": "A beautiful piano melody.",164 "response_format": {165 "type": "audio"166 }167 }'168169## Parse the response170171The response from Lyria 3 contains multiple content blocks within the `steps` schema.172Interactions return a sequence of steps, where `model_output` steps contain the173generated content.174Text content blocks contain the generated lyrics or a JSON description of the song175structure.176Content blocks with `audio` type contain the base64 encoded audio data.177178### Python179180 lyrics = []181 audio_data = None182183 generated_audio = interaction.output_audio184 if generated_audio:185 with open("output.mp3", "wb") as f:186 f.write(base64.b64decode(generated_audio.data))187188 lyrics = interaction.output_text189 if lyrics:190 print(f"Lyrics:\n{lyrics}")191192### JavaScript193194 const lyrics = [];195 let audioData = null;196197 const generatedAudio = interaction.output_audio;198 if (generatedAudio) {199 fs.writeFileSync("output.mp3", Buffer.from(generatedAudio.data, 'base64'));200 }201202 const lyrics = interaction.output_text;203 if (lyrics) {204 console.log("Lyrics:\n" + lyrics);205 }206207### REST208209 # The output from the REST API is a JSON object containing base64 encoded data.210 # You can extract the text or the audio data using a tool like jq.211 # To extract the audio and save it to a file:212 curl ... | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio") | .data' | base64 -d > output.mp3213214#### Interleaved lyrics and music215216Because the output from Lyria 3 is complex---containing separate steps and217blocks for generated lyrics (text) and the song itself (audio)---convenience218properties offer a fast and recommended shortcut.219220However, if you want full, programmatic control over the raw timeline of steps221returned by the server (such as logging individual content blocks as they are222received), you can manually iterate over `steps` instead:223224### Python225226 lyrics = []227 audio_data = None228229 for step in interaction.steps:230 if step.type == "model_output":231 for content_block in step.content:232 if content_block.type == "audio":233 audio_data = base64.b64decode(content_block.data)234 elif content_block.type == "text":235 lyrics.append(content_block.text)236237 if lyrics:238 print("Lyrics:\n" + "\n".join(lyrics))239240 if audio_data:241 with open("output.mp3", "wb") as f:242 f.write(audio_data)243244### JavaScript245246 const lyrics = [];247 let audioData = null;248249 for (const step of interaction.steps) {250 if (step.type === 'model_output') {251 for (const contentBlock of step.content) {252 if (contentBlock.type === 'audio') {253 audioData = Buffer.from(contentBlock.data, 'base64');254 } else if (contentBlock.type === 'text') {255 lyrics.push(contentBlock.text);256 }257 }258 }259 }260261 if (lyrics.length) {262 console.log("Lyrics:\n" + lyrics.join("\n"));263 }264265 if (audioData) {266 fs.writeFileSync("output.mp3", audioData);267 }268269## Generate music from images270271Lyria 3 supports multimodal inputs --- you can provide up to **10 images**272alongside your text prompt in the `input` list and the model will compose music273inspired by the visual content.274275### Python276277 import base64278279 with open("desert_sunset.jpg", "rb") as f:280 image_bytes = f.read()281 image_b64 = base64.b64encode(image_bytes).decode("utf-8")282283 response = client.interactions.create(284 model="lyria-3-pro-preview",285 input=[286 {287 "type": "text",288 "text": "An atmospheric ambient track inspired by the mood and colors in this image.",289 },290 {291 "type": "image",292 "mime_type": "image/jpeg",293 "data": image_b64,294 },295 ],296 )297298### JavaScript299300 import * as fs from "fs";301302 const imageBytes = fs.readFileSync("desert_sunset.jpg").toString("base64");303304 const interaction = await client.interactions.create({305 model: "lyria-3-pro-preview",306 input: [307 {308 type: "text",309 text: "An atmospheric ambient track inspired by the mood and colors in this image.",310 },311 {312 type: "image",313 mime_type: "image/jpeg",314 data: imageBytes,315 },316 ],317 });318319### REST320321 # Pass base64 encoded image data directly:322 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \323 -H "x-goog-api-key: $GEMINI_API_KEY" \324 -H "Api-Revision: 2026-05-20" \325 -H 'Content-Type: application/json' \326 -d '{327 "model": "lyria-3-pro-preview",328 "input": [329 {"type": "text", "text": "An atmospheric ambient track inspired by the mood and colors in this image."},330 {"type": "image", "mime_type": "image/jpeg", "data": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA="}331 ]332 }'333334## Provide custom lyrics335336You can write your own lyrics and include them in the prompt. Use section tags337like `[Verse]`, `[Chorus]`, and `[Bridge]` to help the model understand the338song structure:339340### Python341342 prompt = """343 Create a dreamy indie pop song with the following lyrics:344345 [Verse 1]346 Walking through the neon glow,347 city lights reflect below,348 every shadow tells a story,349 every corner, fading glory.350351 [Chorus]352 We are the echoes in the night,353 burning brighter than the light,354 hold on tight, don't let me go,355 we are the echoes down below.356357 [Verse 2]358 Footsteps lost on empty streets,359 rhythms sync to heartbeats,360 whispers carried by the breeze,361 dancing through the autumn leaves.362 """363364 interaction = client.interactions.create(365 model="lyria-3-pro-preview",366 input=prompt,367 )368369### JavaScript370371 const prompt = `372 Create a dreamy indie pop song with the following lyrics:373374 [Verse 1]375 Walking through the neon glow,376 city lights reflect below,377 every shadow tells a story,378 every corner, fading glory.379380 [Chorus]381 We are the echoes in the night,382 burning brighter than the light,383 hold on tight, don't let me go,384 we are the echoes down below.385386 [Verse 2]387 Footsteps lost on empty streets,388 rhythms sync to heartbeats,389 whispers carried by the breeze,390 dancing through the autumn leaves.391 `;392393 const interaction = await client.interactions.create({394 model: 'lyria-3-pro-preview',395 input: prompt,396 });397398### REST399400 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \401 -H "x-goog-api-key: $GEMINI_API_KEY" \402 -H "Api-Revision: 2026-05-20" \403 -H "Content-Type: application/json" \404 -d '{405 "model": "lyria-3-pro-preview",406 "input": "Create a dreamy indie pop song with the following lyrics: ..."407 }'408409## Control timing and structure410411You can specify exactly what happens at specific moments in the song using412timestamps. This is useful for controlling when instruments enter, when lyrics413are delivered, and how the song progresses:414415### Python416417 prompt = """418 [0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled419 vinyl crackle.420 [0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody421 and gentle vocals singing about a rainy morning.422 [0:30 - 0:50] Chorus: Full band with upbeat drums and soaring423 synth leads. The lyrics are hopeful and uplifting.424 [0:50 - 1:00] Outro: Fade out with the piano melody alone.425 """426427 interaction = client.interactions.create(428 model="lyria-3-pro-preview",429 input=prompt,430 )431432### JavaScript433434 const prompt = `435 [0:00 - 0:10] Intro: Begin with a soft lo-fi beat and muffled436 vinyl crackle.437 [0:10 - 0:30] Verse 1: Add a warm Fender Rhodes piano melody438 and gentle vocals singing about a rainy morning.439 [0:30 - 0:50] Chorus: Full band with upbeat drums and soaring440 synth leads. The lyrics are hopeful and uplifting.441 [0:50 - 1:00] Outro: Fade out with the piano melody alone.442 `;443444 const interaction = await client.interactions.create({445 model: 'lyria-3-pro-preview',446 input: prompt,447 });448449### REST450451 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \452 -H "x-goog-api-key: $GEMINI_API_KEY" \453 -H "Api-Revision: 2026-05-20" \454 -H "Content-Type: application/json" \455 -d '{456 "model": "lyria-3-pro-preview",457 "input": "[0:00 - 0:10] Intro: ..."458 }'459460## Generate instrumental tracks461462For background music, game soundtracks, or any use case where vocals are not463required, you can prompt the model to produce instrumental-only tracks:464465### Python466467 interaction = client.interactions.create(468 model="lyria-3-clip-preview",469 input="A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals.",470 )471472### JavaScript473474 const interaction = await client.interactions.create({475 model: 'lyria-3-clip-preview',476 input: 'A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals.',477 });478479### REST480481 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \482 -H "x-goog-api-key: $GEMINI_API_KEY" \483 -H "Api-Revision: 2026-05-20" \484 -H "Content-Type: application/json" \485 -d '{486 "model": "lyria-3-clip-preview",487 "input": "A bright chiptune melody in C Major, retro 8-bit video game style. Instrumental only, no vocals."488 }'489490## Generate music in different languages491492Lyria 3 generates lyrics in the language of your prompt. To generate a song493with French lyrics, write your prompt in French. The model adapts its vocal494style and pronunciation to match the language.495496### Python497498 interaction = client.interactions.create(499 model="lyria-3-pro-preview",500 input="Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique.",501 )502503### JavaScript504505 const interaction = await client.interactions.create({506 model: 'lyria-3-pro-preview',507 input: 'Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique.',508 });509510### REST511512 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \513 -H "x-goog-api-key: $GEMINI_API_KEY" \514 -H "Api-Revision: 2026-05-20" \515 -H "Content-Type: application/json" \516 -d '{517 "model": "lyria-3-pro-preview",518 "input": "Crée une chanson pop romantique en français sur un coucher de soleil à Paris. Utilise du piano et de la guitare acoustique."519 }'520521## Model intelligence522523Lyria 3 analyzes your prompt process where the524model reasons through musical structure (intro, verse, chorus, bridge, etc.)525based on your prompt.526This happens before the audio is generated and ensures structural coherence and527musicality.528529> [!IMPORTANT]530> **Important:** While Lyria 3 uses a prompt rewriter internally to interpret natural language instructions, it does **not** expose intermediate "thought" blocks or thought signatures to the user.531532## Prompting guide533534The more specific your prompt, the better the results. Here's what you can535include to guide the generation:536537- **Genre**: Specify a genre or blend of genres (e.g., "lo-fi hip hop", "jazz fusion", "cinematic orchestral").538- **Instruments**: Name specific instruments (e.g., "Fender Rhodes piano", "slide guitar", "TR-808 drum machine").539- **BPM**: Set the tempo (e.g., "120 BPM", "slow tempo around 70 BPM").540- **Key/Scale**: Specify a musical key (e.g., "in G major", "D minor").541- **Mood and atmosphere**: Use descriptive adjectives (e.g., "nostalgic", "aggressive", "ethereal", "dreamy").542- **Structure** : Use tags like `[Verse]`, `[Chorus]`, `[Bridge]`, `[Intro]`, `[Outro]` or timestamps to control the song's progression.543- **Duration**: The Clip model always produces 30-second clips. For the Pro model, specify the intended length in your prompt (e.g., "create a 2-minute song") or use timestamps to control duration.544545### Example prompts546547Here are some examples of effective prompts:548549- `"A 30-second lofi hip hop beat with dusty vinyl crackle, mellow Rhodes550 piano chords, a slow boom-bap drum pattern at 85 BPM, and a jazzy upright551 bass line. Instrumental only."`552- `"An upbeat, feel-good pop song in G major at 120 BPM with bright acoustic553 guitar strumming, claps, and warm vocal harmonies about a summer road554 trip."`555- `"A dark, atmospheric trap beat at 140 BPM with heavy 808 bass, eerie synth556 pads, sharp hi-hats, and a haunting vocal sample. In D minor."`557558## Best practices559560- **Iterate with Clip first.** Use the faster `lyria-3-clip-preview` model to experiment with prompts before committing to a full-length generation with `lyria-3-pro-preview`.561- **Be specific.** Vague prompts produce generic results. Mention instruments, BPM, key, mood, and structure for the best output.562- **Match your language.** Prompt in the language you want the lyrics in.563- **Use section tags.** `[Verse]`, `[Chorus]`, `[Bridge]` tags give the model clear structure to follow.564- **Separate lyrics from instructions.** When providing custom lyrics, clearly separate them from your musical direction instructions.565566## Limitations567568- **Safety**: All prompts are checked by safety filters. Prompts that trigger the filters will be blocked. This includes prompts that request specific artist voices or the generation of copyrighted lyrics.569- **Watermarking** : All generated audio includes a [SynthID audio watermark](https://ai.google.dev/responsible/docs/safeguards/synthid) for identification. This watermark is imperceptible to the human ear and does not affect the listening experience.570- **Multi-turn editing**: Music generation is a single-turn process. Iterative editing or refining a generated clip through multiple prompts is not supported in the current version of Lyria 3.571- **Length**: The Clip model always generates 30-second clips. The Pro model generates songs that last a couple of minutes; exact duration can be influenced through your prompt.572- **Determinism**: Results may vary between calls, even with the same prompt.573574## What's next575576- Check [pricing](https://ai.google.dev/gemini-api/docs/interactions/pricing) for Lyria 3 models,577- Try [real-time, streaming music generation](https://ai.google.dev/gemini-api/docs/interactions/realtime-music-generation) with Lyria RealTime,578- Generate multi-speaker conversations with the [TTS models](https://ai.google.dev/gemini-api/docs/interactions/speech-generation),579- Discover how to generate [images](https://ai.google.dev/gemini-api/docs/interactions/image-generation) or [videos](https://ai.google.dev/gemini-api/docs/interactions/video),580- Find out how Gemini can [understand audio files](https://ai.google.dev/gemini-api/docs/interactions/audio),581- Have a real-time conversation with Gemini using the [Live API](https://ai.google.dev/gemini-api/docs/interactions/live).