Version: v1.0.0 | Last Updated: 2026-06-18 | Model: lyria-3-pro-preview | Status: Preview This document is based on live production request/response testing. All field names, types, and values are strictly consistent with actual API responses.
generateContent) to deliver high-fidelity AI music generation.| Capability | Description |
|---|---|
| Text-to-Music | Generate complete songs from natural language descriptions |
| Full-length Song | Generate complete tracks up to approximately 150 seconds in a single call |
| Vocal + Instrumental | Supports lead vocals and multi-track instrumental arrangement |
| Auto Lyrics | Automatically generates lyrics with precise timestamps and section structure annotations |
| Music Analysis | Returns metadata including BPM, duration, and per-section instrumentation analysis |
| MP3 Output | Output in standard MP3 format (audio/mpeg), ready for direct playback |
generateContent interface.Authorization: Bearer YOUR_API_KEY| Header | Value | Required |
|---|---|---|
Authorization | Bearer <API_KEY> | Yes |
Content-Type | application/json | Yes |
Security Notice: The API Key is a sensitive credential. Never expose it in client-side code, public repositories, or logs. Inject it via environment variables or a secrets management service.
| Model ID | Description | Output Format | Max Duration | Status |
|---|---|---|---|---|
lyria-3-pro-preview | Google DeepMind flagship music generation model. Supports high-fidelity full-song creation with lead vocals, multi-track instrumental arrangement, automatic lyrics generation, and song structure analysis. | audio/mpeg (MP3) | ~150 seconds | Preview |
POST https://platform.dataeyes.ai/v1/models/{model_id}:generateContent| Parameter | Type | Description |
|---|---|---|
model_id | string | Model identifier. Currently available value: lyria-3-pro-preview |
| Parameter | Type | Required | Description |
|---|---|---|---|
contents | array<object> | Yes | Array of conversation content objects. |
contents[].parts | array<object> | Yes | Array of content parts. Must contain at least one text part. |
contents[].parts[].text | string | Yes | The generation prompt. Use natural language to describe the desired music style, instruments, mood, tempo, vocal style, etc. |
generationConfig | object | No | Generation configuration. |
generationConfig.responseModalities | array<string> | Yes | List of response modalities. Music generation must include "AUDIO". Including "TEXT" is recommended to also receive lyrics and analysis. Accepted values: "AUDIO", "TEXT". |
{
"contents": [
{
"parts": [
{
"text": "<music generation prompt>"
}
]
}
],
"generationConfig": {
"responseModalities": ["AUDIO", "TEXT"]
}
}| Field | Type | Description |
|---|---|---|
candidates | array<object> | Array of candidate results. Currently always returns exactly 1 candidate. |
usageMetadata | object | Token usage statistics. |
modelVersion | string | The actual model version used, e.g. "lyria-3-pro-preview". |
createTime | string (ISO 8601) | Response creation time, e.g. "2026-06-18T11:59:11.049072Z". |
responseId | string | Unique identifier for this response, useful for troubleshooting and log correlation. |
| Field | Type | Description |
|---|---|---|
content.role | string | Fixed value "model". |
content.parts | array<object> | Array of content parts. See detailed description below. |
finishReason | string | Reason generation stopped. |
| Value | Meaning |
|---|---|
STOP | Normal completion; output is complete. |
MAX_TOKENS | Token limit reached; output may be truncated. |
SAFETY | Content safety policy triggered; request was blocked. |
| Index | Type | Field | Description | Observed Size |
|---|---|---|---|---|
| Part 0 | Text | text | Lyrics: Contains section identifiers [[X0]] and precise timestamps [sec:]. See 4.4 Lyrics Format Specification. | 1,497 characters |
| Part 1 | Text | text | Music Analysis: BPM, duration, quality score, and per-section instrumentation/vocal/mood analysis. See 4.5 Music Analysis Metadata. | 7,263 characters |
| Part 2 | Binary | inlineData | Audio File: Base64-encoded MP3 data. | 3.39 MB (decoded) |
| Field | Type | Description |
|---|---|---|
mimeType | string | MIME type, always "audio/mpeg". |
data | string | Base64-encoded audio data. Decodes to a standard MP3 file. |
| Field | Type | Description |
|---|---|---|
promptTokenCount | integer | Tokens consumed by the input prompt. |
candidatesTokenCount | integer | Tokens consumed by the generated output (includes audio tokens). |
totalTokenCount | integer | Total = promptTokenCount + candidatesTokenCount. |
trafficType | string | Traffic type, e.g. "ON_DEMAND". |
promptTokensDetails | array<object> | Breakdown of input tokens by modality. Each entry contains modality (e.g. "TEXT") and tokenCount. |
candidatesTokensDetails | array<object> | Breakdown of output tokens by modality. Each entry contains modality (e.g. "AUDIO") and tokenCount. |
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "[[A0]]\n[[B1]]\n[10.9:] The kettle's singing in the morning light,\n[:] Dusting off the shadows of the night.\n[:] My boots are heavy but my heart is high,\n[:] Matching every color in the eastern sky.\n..."
},
{
"text": "mosic: 4.5\nbpm: 110.0\nduration_secs: 150.5\ngood_crop: 1.0\n[[A0]]\n[0.0:] A bright and inviting Acoustic Folk intro defined by its rhythmic clarity..."
},
{
"inlineData": {
"mimeType": "audio/mpeg",
"data": "<Base64-encoded, 3,554,545 bytes / 3.39 MB when decoded>"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 13,
"candidatesTokenCount": 3199,
"totalTokenCount": 3212,
"trafficType": "ON_DEMAND",
"promptTokensDetails": [
{ "modality": "TEXT", "tokenCount": 13 }
],
"candidatesTokensDetails": [
{ "modality": "AUDIO", "tokenCount": 3199 }
]
},
"modelVersion": "lyria-3-pro-preview",
"createTime": "2026-06-18T11:59:11.049072Z",
"responseId": "j90zarD_Asaa9LsP5t7F8QU"
}text field in Part 0 uses a structured annotation format containing two types of markers: section identifiers and timestamps.[[LetterNumber]]| Letter | Type | Description | Observed in Testing |
|---|---|---|---|
A | Intro / Interlude / Solo | Instrumental section (intro, interlude, or solo) — no vocals | [[A0]], [[A5]] |
B | Verse | Verse section with narrative vocals | [[B1]], [[B3]] |
C | Chorus | Chorus section — highest energy, melodic repetition | [[C2]], [[C4]], [[C6]] |
D | Outro | Closing section — fades out and resolves | [[D7]] |
Note: The Atype does not exclusively mean "intro." In live testing,[[A0]]was the intro while[[A5]]was a harmonica solo interlude mid-song. The letter indicates the functional role (instrumental/no vocals), not a fixed position in the song.
| Marker | Meaning | Example |
|---|---|---|
[seconds:] | The absolute start time (in seconds) for that lyric line | [10.9:] = at the 10.9-second mark |
[:] | Immediately follows the previous line; no independent timestamp | — |
[[A0]] <- Intro (instrumental only, no lyric lines)
[[B1]] <- Verse 1
[10.9:] The kettle's singing <- starts at 10.9 seconds
[:] in the morning light, <- continues immediately
[:] Dusting off the shadows...
[[C2]] <- Chorus
[37.1:] Oh, let the good... <- starts at 37.1 seconds
[[B3]] <- Verse 2
[54.6:] I met a friend... <- starts at 54.6 seconds
[[C4]] <- Chorus (repeat)
[80.8:] Oh, let the good...
[[A5]] <- Interlude / harmonica solo (instrumental only)
[[C6]] <- Chorus (final)
[111.3:] Oh, let the good...
[[D7]] <- Outro
[128.8:] The luckiest man...text field in Part 1 is a music analysis automatically generated by the model, structured as a key-value header followed by per-section descriptions.| Field | Type | Description | Observed Value |
|---|---|---|---|
mosic | float | Music Quality Score — model self-assessment, range 0–5 | 4.5 |
bpm | float | Beats Per Minute | 110.0 |
duration_secs | float | Total audio duration in seconds | 150.5 |
good_crop | float | Usable crop ratio; 1.0 means the entire track is usable | 1.0 |
Note: The field name mosicis the actual value returned by the API (it is not a typo ofmusic). Parse it as-is in your code.
[[A0]]) is followed by a detailed musicological analysis of that section, covering:| Analysis Dimension | Description | Example Excerpt |
|---|---|---|
| Instrumentation | Instruments used and how they are played | "steel-string acoustic guitar playing a steady, rhythmic strumming pattern" |
| Rhythm | Beat patterns and groove characteristics | "rhythmic hand-clapping on the two and four beats" |
| Vocal Characteristics | Voice type, range, and singing style | "male tenor with a warm, crystalline, and slightly raspy timbre" |
| Mood / Atmosphere | Emotional tone of the section | "jubilant atmosphere of collective celebration" |
| Musical Reference | Similar styles or scene associations | "reminiscent of traveling singer-songwriters" |
[sec:] marking the section's start time in the audio.Tip: Music generation takes considerable time (30–120 seconds). When using curl, add --max-time 180to prevent timeout.
| HTTP Status | Error Code | Description | Recommended Action |
|---|---|---|---|
400 | INVALID_ARGUMENT | Invalid request parameters. Missing contents, malformed parts, or responseModalities does not include "AUDIO". | Verify the JSON structure against the schema in 4.2 Request Body. |
401 | UNAUTHENTICATED | API Key is missing, malformed, or has expired. | Confirm the header format is Authorization: Bearer <key> and that the key has not expired or been revoked. |
403 | PERMISSION_DENIED | The current key does not have access to the specified model. | Verify that music generation permissions are enabled for your account, or contact an administrator to adjust model authorization. |
429 | RESOURCE_EXHAUSTED | Request rate limit exceeded or token quota exhausted. | Reduce request frequency; review rate limit information in the response headers; upgrade your subscription plan if necessary. |
500 | INTERNAL | Internal server error. | Retry with exponential backoff (see 7. Rate Limits). If the issue persists, contact technical support with the responseId. |
503 | UNAVAILABLE | Service temporarily unavailable or overloaded. | Retry with exponential backoff. |
| Metric | Description |
|---|---|
| RPM (Requests Per Minute) | Maximum number of requests per minute. Exceeding the limit returns 429. |
| TPM (Tokens Per Minute) | Maximum token consumption per minute. Audio output is measured in AUDIO tokens. |
| Concurrent Requests | Maximum number of simultaneously processed requests. A single generation takes 30–120 seconds; manage concurrency accordingly. |
429 or 503, use Exponential Backoff with Jitter:wait = min(base * 2^attempt + random(0, 1), max_wait)| Parameter | Recommended Value |
|---|---|
base (initial wait) | 1 second |
max_wait (maximum wait) | 32 seconds |
max_attempts (maximum retries) | 5 |
acoustic folk, electronic, jazz), instruments (guitar, piano, drums), and mood (cheerful, melancholic, energetic)."male tenor vocal", "female soprano, breathy tone")."make a song" produces far inferior results compared to "Create a melancholic jazz ballad with piano and saxophone, slow tempo, female vocal"..mp3 file.text / inlineData) individually. Do not hardcode the index or length of the parts array — future model versions may change the number of parts.finishReason; only "STOP" indicates a complete output.responseId to facilitate troubleshooting and correlation with platform records.usageMetadata. The candidatesTokenCount for the AUDIO modality is the primary cost driver.| Date | Version | Changes |
|---|---|---|
| 2026-06-18 | v1.0.0 | Initial release. Supports lyria-3-pro-preview model. |