> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lyria 3 Pro Preview

> Google Lyria 3 music generation, outputs complete song audio

## 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](https://ai.google.dev/gemini-api/docs/music-generation)

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer Token, e.g. `Bearer sk-xxxxxxxxxxxxxxxx`
</ParamField>

<ParamField header="X-API-Key" type="string">
  Alternatively, use `X-API-Key: sk-xxxxxxxxxxxxxxxx`
</ParamField>

## 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.

```bash theme={null}
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:

```json theme={null}
{
  "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](#query-task-result) endpoint.

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl 'https://api.gravitex.ai/v1beta/interactions/task_xxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'
```

### In progress (in\_progress)

```json theme={null}
{
  "id": "task_xxxxxxxxx",
  "object": "interaction",
  "role": "model",
  "model": "lyria-3-pro-preview",
  "status": "in_progress"
}
```

### Completed (completed)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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."
  }
}
```

<Note>
  A polling interval of 2–5 seconds is recommended. Stop polling on `completed`, `failed`, or `cancelled`.
</Note>

## Parameters

<ParamField body="model" type="string" required>
  Fixed to `lyria-3-pro-preview`
</ParamField>

<ParamField body="input" type="string" required>
  Music description, arrangement requirements, or lyrics. Google style uses a plain string
</ParamField>

<ParamField body="background" type="boolean">
  `true` uses the Gravitex local async task; synchronous by default
</ParamField>

<ParamField body="store" type="boolean">
  Compatible with Google Interactions requests. `true` is recommended for async requests
</ParamField>

<ParamField body="response_format" type="object">
  Audio response format configuration, pass `{"type": "audio"}`; subject to the current channel model configuration
</ParamField>

<ParamField body="previous_interaction_id" type="string">
  Interaction ID for multi-turn linking; single-turn generation is recommended for Lyria 3
</ParamField>

### 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:

```text theme={null}
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:

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

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

## Audio handling example

```javascript theme={null}
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

1. `lyria-3-pro-preview` outputs music audio, not text chat results.
2. 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.
3. Async requests must poll with the returned Gravitex `task_xxx` ID.
4. Generated audio contains Google's audio watermarking mechanism; see official model policies for details.