Lyria 3 Pro API Complete Implementation Guide — Generate Professional Full-Length Tracks from Text and Images

Setup and context: How Lyria 3 Pro Transforms AI Music Production

In March 2026, Google DeepMind released Lyria 3 Pro (lyria-3-pro-preview) as a public preview through the Gemini API. While the existing Lyria 3 Clip model specializes in generating clips up to 30 seconds, Lyria 3 Pro is the first model capable of producing full-length tracks of approximately three minutes.

The model autonomously structures complete songs with intros, verses, choruses, and bridges, outputting high-quality 48kHz stereo audio. Beyond text prompts, it also supports multimodal input from images, inferring mood and atmosphere to shape the generated music.

This guide walks you through the entire Lyria 3 family, from basic API calls and image-to-music generation to advanced patterns with the Interactions API, prompt engineering techniques, error handling strategies, and real-world monetization approaches.

The Lyria 3 Family: Understanding the Three Models

The Lyria 3 family consists of three distinct models, each designed for different use cases.

Lyria 3 Clip (lyria-3-clip-preview)

Generates short clips up to approximately 30 seconds
Ideal for social media BGM, sound effects, and rapid prototyping
Fast response times, suitable for high-volume requests
Inputs: text, images

Lyria 3 Pro (lyria-3-pro-preview)

Generates full-length tracks up to approximately 3 minutes
Autonomously structures songs with verses, choruses, bridges, and transitions
Best suited for professional track production and commercial use
Inputs: text, images

Lyria RealTime (lyria-realtime-exp)

Continuous streaming music generation for up to 10 minutes
Real-time control over BPM, density, and style
Purpose-built for game soundtracks and interactive music experiences
WebSocket-based bidirectional communication

As a general guideline, choose Clip for short jingles and social media content, Pro for polished full-length compositions, and RealTime for interactive applications requiring live responsiveness.

For a deep dive into Lyria RealTime implementation, see our guide on [Real-Time Music Generation with the Lyria RealTime API]((/articles/gemini-api/lyria-realtime-music-api).

Environment Setup and Prerequisites

Requirements

A Google AI Studio or Google Cloud account
A Gemini API key (available from Google AI Studio)
Python 3.10 or later
google-genai SDK v1.x or later

Installing the SDK

pip install google-genai

Client Initialization

from google import genai
from google.genai import types
 
# Create the client
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")

Security note: Store your API key in the GEMINI_API_KEY environment variable rather than hardcoding it. For production deployments, consider using Google Cloud Secret Manager.

Basic Implementation: Generating Music from Text

Simple Track Generation

The most straightforward way to use Lyria 3 Pro is through the generateContent method with response_modalities=["AUDIO", "TEXT"].

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
# Generate a full-length track from a text prompt
response = client.models.generate_content(
    model="lyria-3-pro-preview",
    contents="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. "
             "Tempo: BPM 80, Key: C major.",
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO", "TEXT"],
    ),
)
 
# Parse the response
for part in response.parts:
    if part.text is not None:
        # Generated lyrics or track structure description
        print("Track info:", part.text)
    elif part.inline_data is not None:
        # Save the audio data (MP3 format)
        with open("generated_track.mp3", "wb") as f:
            f.write(part.inline_data.data)
        print(f"Track saved: generated_track.mp3")
        print(f"MIME type: {part.inline_data.mime_type}")

Expected output:

Track info: A gentle piano melody in C major at 80 BPM,
building through lush string arrangements to a cinematic crescendo...
Track saved: generated_track.mp3
MIME type: audio/mp3

Understanding the Response Structure

When you include "TEXT" in response_modalities, the API returns descriptive text alongside the audio data. This text typically contains information about the track's structure, instrumentation, and mood.

If you specify only "AUDIO", you'll receive just the audio data. However, including ["AUDIO", "TEXT"] is recommended for debugging and logging purposes.

Image-to-Music Generation: Multimodal Input

One of Lyria 3 Pro's standout features is its ability to infer musical mood from images and generate matching soundtracks.

Generating from a Local Image

import pathlib
from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
# Read the image file
image_path = pathlib.Path("sunset_beach.jpg")
image_data = image_path.read_bytes()
 
# Generate music from image + text
response = client.models.generate_content(
    model="lyria-3-pro-preview",
    contents=[
        types.Part.from_bytes(
            data=image_data,
            mime_type="image/jpeg",
        ),
        "Create a relaxing chillout track that matches "
        "the atmosphere of this photo. Focus on ambient "
        "synths and acoustic guitar.",
    ],
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO", "TEXT"],
    ),
)
 
# Save the audio
for part in response.parts:
    if part.inline_data is not None:
        with open("image_inspired_track.mp3", "wb") as f:
            f.write(part.inline_data.data)
        print("Image-inspired track saved")

Generating from a URL Image

You can also point directly to a remote image URL.

response = client.models.generate_content(
    model="lyria-3-pro-preview",
    contents=[
        types.Part.from_uri(
            file_uri="https://example.com/mountain_sunrise.jpg",
            mime_type="image/jpeg",
        ),
        "Generate an orchestral piece that captures this landscape",
    ],
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO", "TEXT"],
    ),
)

Image input opens up creative possibilities like automated photo slideshow BGM generation, e-commerce product mood music, and visual-to-audio art installations.

For foundational multimodal techniques, see [Gemini API Multimodal Techniques Collection]((/articles/gemini-api/gemini-api-multimodal-techniques).

Interactions API: Long-Form Tracks and Advanced Control

What is the Interactions API?

The Interactions API provides a unified interface for managing conversations with Gemini models and agents. When combined with Lyria 3 Pro, it enables stateful session management and handling of long-running tasks.

While standard generateContent completes in a single request-response cycle, the Interactions API lets you iteratively refine tracks across multiple turns of dialogue.

Session-Based Track Generation

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
# Create a session with the Interactions API
interaction = client.interactions.create(
    model="lyria-3-pro-preview",
    config=types.InteractionConfig(
        response_modalities=["AUDIO", "TEXT"],
    ),
)
 
# Turn 1: Set the musical direction
response1 = interaction.send_message(
    "I want to create a chillhop track that blends "
    "electronica with jazz elements. BPM 90, "
    "lo-fi texture with warm vinyl crackle."
)
 
# Check the initial generation
for part in response1.parts:
    if part.text:
        print("Initial generation info:", part.text)
    elif part.inline_data:
        with open("draft_v1.mp3", "wb") as f:
            f.write(part.inline_data.data)
 
# Turn 2: Refine based on feedback
response2 = interaction.send_message(
    "That sounds great, but could you add a saxophone "
    "solo section in the middle and close with a "
    "quiet piano outro?"
)
 
for part in response2.parts:
    if part.inline_data:
        with open("draft_v2.mp3", "wb") as f:
            f.write(part.inline_data.data)
        print("Refined version saved")

Async Processing for Long-Form Generation

Full-length track generation can take significant processing time. Async patterns help maintain a smooth user experience.

import asyncio
from google import genai
from google.genai import types
 
async def generate_track_async(prompt: str, output_path: str):
    """Generate a track asynchronously and save to file"""
    client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
    response = await client.aio.models.generate_content(
        model="lyria-3-pro-preview",
        contents=prompt,
        config=types.GenerateContentConfig(
            response_modalities=["AUDIO", "TEXT"],
        ),
    )
 
    for part in response.parts:
        if part.inline_data is not None:
            with open(output_path, "wb") as f:
                f.write(part.inline_data.data)
            return output_path
 
    return None
 
async def batch_generate():
    """Generate multiple tracks in parallel"""
    tasks = [
        generate_track_async(
            "Bright and upbeat pop song, BPM 120",
            "track_pop.mp3"
        ),
        generate_track_async(
            "Dark ambient synthwave, BPM 85",
            "track_ambient.mp3"
        ),
        generate_track_async(
            "Jazzy piano trio, BPM 110, swing feel",
            "track_jazz.mp3"
        ),
    ]
 
    results = await asyncio.gather(*tasks)
    for path in results:
        if path:
            print(f"Generated: {path}")
 
# Run the batch
asyncio.run(batch_generate())

Expected output:

Generated: track_pop.mp3
Generated: track_ambient.mp3
Generated: track_jazz.mp3

Prompt Engineering: Crafting High-Quality Music Prompts

The quality of Lyria 3 Pro's output is heavily influenced by how you write your prompts. Here are proven patterns for generating professional-grade tracks.

Structured Prompt Design

To maximize track quality, explicitly specify the following elements.

structured_prompt = """
Genre: Cinematic Orchestral
Tempo: BPM 72
Key: D minor
Mood: Epic, emotional, hopeful
 
Song structure:
- Intro (0:00-0:20): Solo cello melody, resonating in silence
- Verse 1 (0:20-0:50): String quartet joins, presenting the main theme
- Build-up (0:50-1:20): Horns and timpani enter, gradually increasing dynamics
- Climax (1:20-2:00): Full orchestra at peak intensity, main theme variation
- Outro (2:00-2:40): Piano and strings fade gently, leaving a lingering resonance
 
Reference artists: Hans Zimmer, Joe Hisaishi
"""
 
response = client.models.generate_content(
    model="lyria-3-pro-preview",
    contents=structured_prompt,
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO", "TEXT"],
    ),
)

Genre-Specific Prompt Templates

Lo-Fi Hip Hop / Chillhop:

Lo-fi hip hop track, BPM 85, vinyl crackle texture,
mellow Rhodes piano chords with jazzy extensions,
laid-back boom-bap drums, ambient rain sounds in background,
warm bass line, study/focus mood

EDM / Electronic:

Progressive house track, BPM 128, key of A minor,
atmospheric pads building over 16 bars,
punchy kick drums with sidechain compression feel,
melodic synth lead in the drop, euphoric breakdown

Film & Game Scores:

Fantasy RPG battle theme, BPM 150,
epic orchestral with choir chants,
aggressive string ostinato, brass fanfares,
taiko drums accenting the rhythm,
heroic and intense mood

Prompt Anti-Patterns to Avoid

The following prompt patterns tend to produce suboptimal results.

Vague instructions: "Make a nice song" — specify genre, tempo, and mood
Contradictory directions: "Quiet and epic heavy metal" — maintain consistent mood
Overly technical mixing instructions: "EQ boost 2dB at 3kHz" — the model doesn't process mixing parameters
Reproduction requests: Asking to recreate existing songs raises copyright concerns; reference styles instead

Production-Grade Error Handling

Here are essential error handling patterns for running Lyria 3 Pro in production environments.

Retry and Fallback Strategy

import time
from google import genai
from google.genai import types
 
class MusicGenerationService:
    """Production music generation service"""
 
    def __init__(self, api_key: str):
        self.client = genai.Client(api_key=api_key)
        self.max_retries = 3
        self.retry_delay = 2  # seconds
 
    def generate_with_retry(
        self,
        prompt: str,
        output_path: str,
        model: str = "lyria-3-pro-preview",
    ) -> dict:
        """Generate a track with automatic retry"""
        last_error = None
 
        for attempt in range(self.max_retries):
            try:
                response = self.client.models.generate_content(
                    model=model,
                    contents=prompt,
                    config=types.GenerateContentConfig(
                        response_modalities=["AUDIO", "TEXT"],
                    ),
                )
 
                result = {"text": None, "audio_path": None}
 
                for part in response.parts:
                    if part.text is not None:
                        result["text"] = part.text
                    elif part.inline_data is not None:
                        with open(output_path, "wb") as f:
                            f.write(part.inline_data.data)
                        result["audio_path"] = output_path
 
                if result["audio_path"]:
                    return result
 
                raise ValueError(
                    "No audio data in response"
                )
 
            except Exception as e:
                last_error = e
                print(
                    f"Attempt {attempt + 1}/{self.max_retries} "
                    f"failed: {e}"
                )
                if attempt < self.max_retries - 1:
                    wait = self.retry_delay * (2 ** attempt)
                    print(f"Retrying in {wait} seconds...")
                    time.sleep(wait)
 
        # Fall back to Clip model if Pro fails
        if model == "lyria-3-pro-preview":
            print("Pro model failed — falling back to Clip")
            return self.generate_with_retry(
                prompt, output_path,
                model="lyria-3-clip-preview"
            )
 
        raise RuntimeError(
            f"Music generation failed after "
            f"{self.max_retries} retries: {last_error}"
        )
 
    def generate_with_validation(
        self,
        prompt: str,
        output_path: str,
        min_size_bytes: int = 50000,
    ) -> dict:
        """Generate a track with output validation"""
        result = self.generate_with_retry(prompt, output_path)
 
        if result["audio_path"]:
            import os
            file_size = os.path.getsize(result["audio_path"])
            if file_size < min_size_bytes:
                raise ValueError(
                    f"Generated file too small "
                    f"({file_size} bytes < {min_size_bytes} bytes)"
                )
            result["file_size"] = file_size
 
        return result
 
# Usage
service = MusicGenerationService(api_key="YOUR_GEMINI_API_KEY")
result = service.generate_with_validation(
    prompt="Jazz piano trio, BPM 120, swing feel",
    output_path="output/jazz_trio.mp3",
    min_size_bytes=100000,
)
print(f"Generation complete: {result}")

About SynthID Watermarking

All audio generated by Lyria 3 models is automatically embedded with Google DeepMind's SynthID digital watermark. This watermark is imperceptible to human listeners but detectable by specialized tools.

SynthID serves several purposes:

Identifying and tracking AI-generated content
Supporting copyright management and transparency
Contributing to deepfake prevention

SynthID cannot be disabled and applies to all Lyria 3 output. When using generated tracks commercially, it's recommended to acknowledge this in your terms of service.

Lyria 3 Clip vs Pro: Cost and Performance Comparison

To make informed decisions in production, here's a practical comparison of both models.

Generation Time Estimates

Lyria 3 Clip: 5–15 seconds (for a 30-second clip)
Lyria 3 Pro: 30–90 seconds (for a track up to 3 minutes)

Output Quality

Lyria 3 Clip: High quality but simple structure (loop-oriented)
Lyria 3 Pro: Full song arc (intro → development → climax → outro) generated autonomously

Choosing the Right Model Programmatically:

def select_model(use_case: dict) -> str:
    """Select the appropriate model based on use case"""
    if use_case.get("duration_needed", 0) <= 30:
        return "lyria-3-clip-preview"
 
    if use_case.get("needs_structure", False):
        return "lyria-3-pro-preview"
 
    if use_case.get("realtime", False):
        return "lyria-realtime-exp"
 
    if use_case.get("high_volume", False):
        # Clip is more cost-effective for bulk generation
        return "lyria-3-clip-preview"
 
    return "lyria-3-pro-preview"
 
# Example
model = select_model({
    "duration_needed": 180,  # 3 minutes
    "needs_structure": True,
    "high_volume": False,
})
print(f"Recommended model: {model}")
# Output: Recommended model: lyria-3-pro-preview

Monetization Patterns: Building a Business with Lyria 3 Pro

Here are concrete approaches to monetizing AI music generation technology.

1. Building a Stock Music Library

Generate a diverse catalog of tracks across genres and moods using Lyria 3 Pro, then offer them as a stock music service.

# Batch stock music generation example
genres = [
    {"genre": "Corporate", "prompt": "Bright, upbeat corporate BGM, BPM 110"},
    {"genre": "Cinematic", "prompt": "Epic orchestral trailer music, BPM 90"},
    {"genre": "Lo-Fi", "prompt": "Relaxing lo-fi beats, BPM 80, rain ambience"},
    {"genre": "Electronic", "prompt": "Tech-forward electronica for videos, BPM 128"},
]
 
for item in genres:
    result = service.generate_with_validation(
        prompt=item["prompt"],
        output_path=f"stock/{item['genre'].lower()}_001.mp3",
    )
    print(f"{item['genre']}: {result['audio_path']}")

2. Integration with Video Production Pipelines

Pair Lyria 3 Pro with Veo 3 to automatically generate matching BGM for AI-produced videos. For more on the video side, check out our [Veo 3 Video Generation API Complete Guide]((/articles/gemini-api/veo3-video-generation-api).

3. Embedding in SaaS Products

Integrating Lyria 3 Pro into a SaaS application backend is a compelling business model. For strategies on building and monetizing AI-powered SaaS with the Gemini API, see [Monetizing AI Services with Gemini API and Stripe]((/articles/gemini-api/gemini-api-saas-monetization).

Summary

Lyria 3 Pro represents a significant leap in practical AI music generation. The jump from 30-second clips to full three-minute tracks with autonomous song structure makes it genuinely viable for commercial content production.

Use the implementation patterns covered in this guide to start integrating Lyria 3 Pro into your own projects. Whether it's text-to-music, image-to-music, or iterative refinement through the Interactions API, these capabilities have the potential to fundamentally reshape music production workflows.