Lyria 3 Pro Preview

Introduction

lyria-3-pro-preview generates complete music, suitable for fuller song structures such as verses, choruses, and bridges. The output is audio. Gravitex exposes Google Interactions-style endpoints:

Endpoint	Method	Description
Submit generation request	`POST /v1beta/interactions`	Submit a music generation task (sync or async)
Query task result	`GET /v1beta/interactions/{interaction_id}`	Poll async task status and result

Official reference:

Google Lyria 3 music generation

Authentication

string

required

Bearer Token, e.g. Bearer sk-xxxxxxxxxxxxxxxx

string

Alternatively, use X-API-Key: sk-xxxxxxxxxxxxxxxx

Submit a generation request

POST /v1beta/interactions Depending on the background field, requests run in either synchronous or asynchronous mode.

Synchronous generation (default)

When background is omitted, or explicitly set to background: false, the gateway waits for the upstream generation to finish and returns the result directly. No async task record is created.

curl -X POST 'https://api.gravitex.ai/v1beta/interactions' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "lyria-3-pro-preview",
    "input": "Create a warm cinematic country song with acoustic guitar, gentle drums, a memorable chorus, and a calm journey-home atmosphere. Instrumental only.",
    "background": false,
    "store": false
  }'

Successful response:

{
  "id": "interaction_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "completed",
  "output_audio": {
    "data": "<base64-audio>",
    "mime_type": "audio/mpeg"
  },
  "output_text": "<generated lyrics or structure>"
}

output_audio.data is Base64-encoded audio. mime_type is usually audio/mpeg.

Asynchronous generation

With background: true, Gravitex creates a local async task and returns the task ID immediately. Then poll the query task result endpoint.

curl -X POST 'https://api.gravitex.ai/v1beta/interactions' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "lyria-3-pro-preview",
    "input": "Create an instrumental country music track with acoustic guitar, birdsong, and soft summer insect ambience. No lyrics, no artist imitation, and no copyrighted melody.",
    "background": true,
    "store": true
  }'

Submission response:

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}

The returned task_xxx ID is used for subsequent queries.

Query task result

GET /v1beta/interactions/{interaction_id} The async task is handled by the Gravitex worker, which calls the upstream service. Once generation finishes, tasks, logs, and billing are updated. Clients only need to poll this endpoint for the final result.

Request example

curl 'https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

In progress (in_progress)

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}

Completed (completed)

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "completed",
  "output_audio": {
    "data": "<base64-audio>",
    "mime_type": "audio/mpeg"
  },
  "output_text": "<generated lyrics or structure>"
}

Failed (failed)

{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "failed",
  "error": {
    "code": "content_blocked",
    "message": "Request blocked for an unspecified policy reason. Please modify your input and retry."
  }
}

A polling interval of 2–5 seconds is recommended. Stop polling on completed, failed, or cancelled.

Parameters

string

required

Fixed to lyria-3-pro-preview

string

required

Music description, arrangement requirements, or lyrics. Google style uses a plain string

boolean

true uses the Gravitex local async task; synchronous by default

boolean

Compatible with Google Interactions requests. true is recommended for async requests

object

Audio response format configuration, pass {"type": "audio"}; subject to the current channel model configuration

string

Interaction ID for multi-turn linking; single-turn generation is recommended for Lyria 3

Prompting tips

Consider including the following in your prompt:

Genre: country, pop, jazz, cinematic, etc.
Instruments: acoustic guitar, piano, drums, etc.
Mood: warm, dreamy, energetic, etc.
Tempo and key: e.g. 90 BPM, G major
Whether vocals or lyrics are needed
Song structure: [Intro], [Verse], [Chorus], [Bridge]
Duration: the Pro model accepts target duration descriptions in the prompt

Example:

Create a 2-minute warm cinematic country song at 90 BPM in G major, with acoustic guitar, pedal steel, soft drums, verse, chorus, and bridge. Add gentle birdsong and summer evening ambience. Instrumental only.

Status codes and errors

HTTP status	code	Meaning
`200`	-	Request accepted, in progress, or completed; check `status` for async requests
`400`	`invalid_request` / `invalid_argument`	Invalid request format or upstream parameters
`401`	`unauthenticated`	API Key invalid or missing
`403`	`permission_denied` / `content_blocked`	Insufficient permissions, group restrictions, or content safety block
`404`	`not_found`	Model, channel, or task not found
`429`	`resource_exhausted`	Quota, rate, or upstream capacity exhausted
`500`	`internal`	Gateway or upstream internal error
`502`	`bad_gateway`	Upstream response invalid or unparseable
`503`	`unavailable`	Upstream service temporarily unavailable
`504`	`deadline_exceeded`	Upstream request timed out

Content safety block

The following error means the prompt was blocked by Google’s safety filter — it is not a JSON parameter error:

{
  "error": {
    "code": "content_blocked",
    "message": "Request blocked for an unspecified policy reason. Please modify your input and retry."
  }
}

Do not retry the exact same prompt indefinitely. Modify the prompt and avoid artist voices, copyrighted lyrics, or restricted content.

Audio handling example

const response = await fetch('https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx', {
  headers: {
    Authorization: 'Bearer sk-xxxxxxxxxxxxxxxx'
  }
});

const interaction = await response.json();

if (interaction.status === 'completed') {
  const audioBase64 = interaction.output_audio?.data;
  const mimeType = interaction.output_audio?.mime_type || 'audio/mpeg';
  console.log(mimeType, audioBase64);
}

if (interaction.status === 'failed') {
  console.error(interaction.error?.code, interaction.error?.message);
}

Notes

lyria-3-pro-preview outputs music audio, not text chat results.
Do not force generic text model parameters such as top_p or temperature into Lyria requests. Available parameters follow the channel configuration and official model docs.
Async requests must poll with the returned Gravitex task_xxx ID.
Generated audio contains Google’s audio watermarking mechanism; see official model policies for details.

API documentation

Chat & text

Safety & audio

Image Series

Video Series

Completions & Embeddings

Interface module

Introduction

Authentication

Submit a generation request

Synchronous generation (default)

Asynchronous generation

Query task result

Request example

In progress (in_progress)

Completed (completed)

Failed (failed)

Parameters

Prompting tips

Status codes and errors

Content safety block

Audio handling example

Notes

​Introduction

​Authentication

​Submit a generation request

​Synchronous generation (default)

​Asynchronous generation

​Query task result

​Request example

​In progress (in_progress)

​Completed (completed)

​Failed (failed)

​Parameters

​Prompting tips

​Status codes and errors

​Content safety block

​Audio handling example

​Notes

Introduction

Authentication

Submit a generation request

Synchronous generation (default)

Asynchronous generation

Query task result

Request example

In progress (in_progress)

Completed (completed)

Failed (failed)

Parameters

Prompting tips

Status codes and errors

Content safety block

Audio handling example

Notes