Music models

Models and methods

Model	API ID	Interface	Billing unit
Lyria 2	lyria-002	Vertex-compatible predict	Completed track
Lyria 3 Clip	lyria-3-clip-preview	interactions (JSON or SSE)	Completed track
Lyria 3 Pro	lyria-3-pro-preview	interactions (JSON or SSE)	Completed track
Lyria 3.5	lyria-3.5	interactions (JSON or SSE)	Completed track
Lyria RealTime	lyria-realtime-exp	WebSocket BidiGenerateMusic	Second of delivered audio

Moonez.ai preserves the native request and response formats. Music is not an image job: do not submit these models to /api/v1/generations. generateContent, streamGenerateContent, and countTokens are not exposed for music models. These requests fail before any reservation or provider call. RealTime is a genuine bidirectional WebSocket, not a completed track split into SSE messages. Preview-model availability depends on the provider.

Google documents the Interactions music interface and the separate Live Music protocol. Use the Moonez.ai endpoints below with your Moonez.ai key, not Google credentials.

Before you start

1. Enable Lyria music models (MUSIC) on your key in API Keys. Existing image/text permissions do not grant music access automatically.
2. Add your server’s public egress IP in IP Whitelist.
3. Check Pricing → Music models. Not configured — unavailable means generation is blocked; it does not mean free. An explicitly configured zero price is allowed.
4. Keep enough available balance for the reservation. Use server-side code; never embed your key in a public browser application.

GET /api/gemini/v1beta/models lists the models permitted by your key and their supported methods. A catalog entry does not override pricing or provider access.

Generate a track

Lyria 3 Clip, Lyria 3 Pro, and Lyria 3.5 use native Interactions:

curl --fail-with-body 'https://api.moonez.ai/api/gemini/v1beta/interactions' \
  -H "x-goog-api-key: $MOONEZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"lyria-3-clip-preview","input":"An original instrumental loop with soft bells and a slow bass line.","store":false}'

The request body and upstream response are forwarded without converting them to generateContent. In JSON responses, read audio content from outputs or steps[].content, according to the model’s native response. An audio part has type: "audio", mime_type, and base64 data or a uri. Preserve its MIME type: do not assume every model returns WAV. Text or lyrics alone are not tracks.

For native SSE, use the same endpoint with "stream": true and curl -N. Google’s event names, payloads, and ordering are preserved; no synthetic Gemini candidate chunks or terminal events are generated. Wait for the native interaction.completed (or Vertex interaction.complete) event with status: "completed" before treating the track as complete. An error, truncated stream, or response without audio does not produce a billable track.

Only stateless creation is supported for music: use store: false; background execution, previous_interaction_id, retrieval, and resume are not supported. Use the Google Interactions reference for model-specific input and event formats. Provider errors are returned as-is; model availability still depends on the selected provider.

Lyria 2

Lyria 2 uses a different body and returns predictions:

curl --fail-with-body 'https://api.moonez.ai/api/gemini/v1beta/models/lyria-002:predict' \
  -H "x-goog-api-key: $MOONEZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"instances":[{"prompt":"A gentle instrumental arrangement for marimba and strings."}],"parameters":{"sample_count":1}}'

Read predictions[].bytesBase64Encoded and predictions[].mimeType. The platform routes this model to a Vertex service-account provider; clients do not supply a project ID or service-account secret. See Google’s Lyria 2 reference for model-specific parameters.

Lyria RealTime

The native endpoint is:

wss://api.moonez.ai/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic

The equivalent /api/gemini/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic path is supported. Authenticate with x-goog-api-key; the native protocol also accepts ?key=, but headers avoid putting credentials in URLs and access logs.

The official Python SDK handles setup and control messages:

import asyncio
import os
from pathlib import Path

from google import genai
from google.genai import types

async def main():
    client = genai.Client(
        api_key=os.environ["MOONEZ_API_KEY"],
        http_options={
            "base_url": "https://api.moonez.ai/api/gemini",
            "api_version": "v1alpha",
        },
    )
    try:
        async with asyncio.timeout(30):
            async with client.aio.live.music.connect(model="lyria-realtime-exp") as session:
                await session.set_weighted_prompts(
                    prompts=[types.WeightedPrompt(text="Quiet ambient music with warm synth pads", weight=1)]
                )
                await session.play()
                async for message in session.receive():
                    if not message.server_content:
                        continue
                    for chunk in message.server_content.audio_chunks or []:
                        if chunk.data:
                            Path("live-audio.bin").write_bytes(chunk.data)
                            print("Audio MIME type:", chunk.mime_type)
                            return
    finally:
        await client.aio.aclose()

asyncio.run(main())

This bounded example saves the first audio chunk and closes the session. It is not an audio player. Use the MIME metadata to decode or wrap the audio correctly. For a raw WebSocket client, send {"setup":{"model":"models/lyria-realtime-exp"}} first and wait for setupComplete before sending prompts or playback commands.

During a session, prompts and configuration can change while audio arrives. Native playback controls are PLAY, PAUSE, STOP, and RESET_CONTEXT. Warnings and filtered prompts are forwarded; they do not themselves count as audio. Explicitly close the connection when finished. Reconnecting starts a new session, not a resumable or idempotent retry.

Moonez.ai limits each message to 2 MiB and bounds the session by the configured job lifetime. Slow consumers are subject to backpressure. If the balance cannot cover the next audio chunk, delivery stops with close code 1008. A service failure or timeout can close with 1011; retain audio already received.

Billing and charge visibility

Your account prices are independent of Google’s list prices.

• Tracks: Lyria 3 reserves one track per interaction; Lyria 2 reserves the requested number of predictions. Charge only for completed audio tracks, not individual SSE chunks. No final audio, including safety-blocked responses, releases the reservation. Text or lyrics alone are free.
• RealTime: reserve before sending audio and settle from confirmed audio samples after delivery. Connection time, playback pauses, warnings, and buffered audio discarded after disconnect are not charged. Delivered audio remains payable if the session later fails. Delivery means a successful server socket send, not proof that a person listened.
• The price is fixed when the job starts. A later price change does not reprice an existing session. Unused reservation is released at settlement.
• Request status and billing status are separate. A successful response with no audio can be free; a failed RealTime session can have a partial charge. Check the charge/reservation fields in Jobs and your billing history.

There is no automatic paid replay after a broken stream. Review the result and charges before explicitly starting another generation.