# Lyria API

> Provider: **Google**
> Source: https://www.pixazo.ai/models/lyria

Google's advanced AI music generation model for creating high-quality audio content.

## Lyria 2

### Text to Music

## Base URL

```
https://gateway.pixazo.ai/lyria-2/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Music Request - Lyria 2

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/lyria-2/v1/lyria-2/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "Futuristic country music, steel guitar, huge 808s"
}
```

```
import requests

url = "https://gateway.pixazo.ai/lyria-2/v1/lyria-2/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Futuristic country music, steel guitar, huge 808s"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/lyria-2/v1/lyria-2/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
};
const data = {
  prompt: 'Futuristic country music, steel guitar, huge 808s'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/lyria-2/v1/lyria-2/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Futuristic country music, steel guitar, huge 808s"
  }'
```

## Output

```
{
  "request_id": "lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=lyria-2&operation=music-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Music Request

Parameter

Required

Type

Description

prompt

Yes

string

Text prompt describing the music to generate

negative\_prompt

No

string

Description of what to exclude from the generated audio

seed

No

integer

Random seed for reproducible generation

webhook

No

string

Webhook URL for async notifications when generation completes

webhook\_events\_filter

No

array

Event types to receive (e.g. \["completed"\])

## Example Request

```
{
  "prompt": "Futuristic country music, steel guitar, huge 808s, synth wave elements space western cosmic twang soaring vocals",
  "negative_prompt": "low quality, distorted, noise, static, vocals out of tune",
  "seed": 42,
  "webhook": "https://your-webhook.com/callback",
  "webhook_events_filter": ["completed"]
}
```

## Response

```
{
  "request_id": "lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Music Status - Lyria 2

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/lyria-2/v1/lyria-2/prediction
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prediction_id": "abc123def456"
}
```

```
import requests

url = "https://gateway.pixazo.ai/lyria-2/v1/lyria-2/prediction"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prediction_id": "abc123def456"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/lyria-2/v1/lyria-2/prediction';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
};
const data = {
  prediction_id: 'abc123def456'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/lyria-2/v1/lyria-2/prediction" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prediction_id": "abc123def456"
  }'
```

## Output

```
{
  "success": true,
  "request_id": "abc123def456",
  "status": "succeeded",
  "audio": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/lyria-2/abc123def456_output_0.wav",
  "created_at": "2026-02-25T10:00:00.000Z"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=lyria-2&operation=music-status)

## Request Parameters - Music Status

Parameter

Required

Type

Description

prediction\_id

Yes

string

The prediction ID returned from the generate endpoint

## Example Request

```
{
  "prediction_id": "abc123def456"
}
```

## Response

```
{
  "audio": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/lyria-2/abc123def456_output_0.wav",
  "success": true,
  "request_id": "abc123def456",
  "status": "succeeded",
  "input": {
    "prompt": "Futuristic country music, steel guitar, huge 808s"
  },
  "created_at": "2026-02-25T10:00:00.000Z"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Music Status.

Code

Meaning

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

500

Internal Server Error

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'lyria-2' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "lyria-2",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "lyria-2_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "lyria-2",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/lyria-2_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Lyria 3

### Text to Music

_Documentation could not be fetched at build time._

## Lyria 3 Pro

### Text to Music

## Base URL

```
https://gateway.pixazo.ai/lyria-3-pro/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Music generate request - Lyria 3 Pro API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/lyria-3-pro/v1/lyria-3-pro/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A calm acoustic folk song with gentle guitar and soft strings. Instrumental only."
}
```

```
import requests

url = "https://gateway.pixazo.ai/lyria-3-pro/v1/lyria-3-pro/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A calm acoustic folk song with gentle guitar and soft strings. Instrumental only."
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/lyria-3-pro/v1/lyria-3-pro/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: 'A calm acoustic folk song with gentle guitar and soft strings. Instrumental only.'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/lyria-3-pro/v1/lyria-3-pro/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A calm acoustic folk song with gentle guitar and soft strings. Instrumental only."
  }'
```

## Output

```
{
  "request_id": "lyria-3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/lyria-3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=lyria-3-pro&operation=music-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Music generate request

Parameter

Required

Type

Description

prompt

Yes

string

Text prompt describing the song to generate. Include details like genre, instruments, mood, tempo, lyrics, and song structure (e.g. \[Verse\], \[Chorus\], \[Bridge\]). Use timestamps like \[0:00 - 0:30\] to control timing.

images

No

array

Input images to inspire the music composition (up to 10 images). Array of URL strings.

webhook

No

string

Webhook URL for async notifications when generation completes.

webhook\_events\_filter

No

array

Filter for webhook event types to receive (e.g. \["completed"\]).

## Example Request

```
{
  "prompt": "[Verse 1]\nWalking through the neon glow,\ncity lights reflect below,\nevery shadow tells a story,\nevery corner, fading glory.\n\n[Chorus]\nWe are the echoes in the night,\nburning brighter than the light,\nhold on tight, don't let me go,\nwe are the echoes down below.\n\n[Verse 2]\nFootsteps lost on empty streets,\nrhythms sync to heartbeats,\nwhispers carried by the breeze,\ndancing through the autumn leaves.\n\nGenre: Dreamy indie pop. Mood: Nostalgic and uplifting. Tempo: 110 BPM.",
  "images": [
    "https://example.com/sunset-beach.jpg",
    "https://example.com/forest-path.jpg"
  ]
}
```

## Response

```
{
  "request_id": "lyria-3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/lyria-3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.08"
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'lyria-3-pro' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "lyria-3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "lyria-3-pro",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/lyria-3-pro_019d5721-c333-7002-426f-b50cf48bab672"
```

## Response (Completed)

```
{
  "request_id": "lyria-3-pro_019d5721-c333-7002-426f-b50cf48bab672",
  "status": "COMPLETED",
  "model_id": "lyria-3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/lyria-3-pro_019d5721-c333-7002-426f-b50cf48bab672/output.mpeg"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-04-04T06:15:23.699Z",
  "updated_at": "2026-04-04T06:16:20.000Z",
  "completed_at": "2026-04-04T06:16:20.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (audio/mpeg)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.