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

# Lyria 3 API

> Generate original music from text with Lyria 3. Choose clip or pro model variants and guide the mood with optional reference images for video, games, and ads.

<Card title="Lyria 3 integration" icon="music">
  Powered by Lyria 3, this API generates original music tracks from text descriptions with selectable model variants.
</Card>

Lyria 3 is an AI-powered music generation API that creates original music from text descriptions. Describe the genre, mood, instruments, and tempo you want, choose between the `clip` and `pro` model variants, and optionally attach reference images to inform the atmosphere of the composition. The generated track is delivered as a URL, making it ideal for video production, games, podcasts, and multimedia projects.

### Key capabilities

* **Text-guided generation**: describe any music style to generate (e.g., "Cinematic ambient track with warm synth pads and soft piano")
* **Model variants (`clip` or `pro`)**: `clip` for faster generation optimized for short clips (default), `pro` for higher-fidelity, professional-quality tracks
* **Reference images**: guide mood and style with optional reference images (PNG, JPEG, or WebP) via public URL or GCS format
* **Audio URL output**: the generated track is delivered via a URL for download
* **Async processing**: webhook notifications or polling for task completion

### Use cases

* **Video production**: background music tailored to a scene's visual mood
* **Game development**: custom soundtracks for games and apps
* **Content creation**: unique music for podcasts, streams, and social media
* **Advertising**: original background tracks and cues for ads
* **Film production**: temp tracks or production music guided by reference imagery

### Generate music with Lyria 3

Submit a text description of the music you want to create, choose a model variant, and optionally attach reference images. The service returns a task ID for async polling or webhook notification.

<div className="my-11">
  <Columns cols={2}>
    <Card title="POST /v1/ai/music-generation/lyria-3" icon="music" href="/api-reference/music-generation/lyria-3/generate">
      Create a new Lyria 3 music generation task
    </Card>

    <Card title="GET /v1/ai/music-generation/lyria-3" icon="list" href="/api-reference/music-generation/lyria-3/lyria-3-tasks">
      List all Lyria 3 tasks
    </Card>

    <Card title="GET /v1/ai/music-generation/lyria-3/{task-id}" icon="magnifying-glass" href="/api-reference/music-generation/lyria-3/task-by-id">
      Get task status and results by ID
    </Card>
  </Columns>
</div>

### Parameters

| Parameter          | Type           | Required | Default | Description                                                                                                                                                     |
| ------------------ | -------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`           | `string`       | Yes      | -       | Text description of the music to generate (10-2000 characters). Be specific about genre, mood, instruments, and tempo                                           |
| `model`            | `string`       | No       | `clip`  | Model variant: `clip` (faster, optimized for short clips) or `pro` (higher-fidelity, professional-quality)                                                      |
| `reference_images` | `array`        | No       | -       | Optional reference images to guide mood and style. Each entry requires `image` (public URL or GCS) and `mime_type` (`image/png`, `image/jpeg`, or `image/webp`) |
| `webhook_url`      | `string` (uri) | No       | -       | Optional callback URL that receives task status notifications                                                                                                   |

The `reference_images` array items have the following shape:

| Field       | Type     | Required | Description                                                                  |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `image`     | `string` | Yes      | Image URL (publicly accessible URL or GCS format)                            |
| `mime_type` | `string` | Yes      | MIME type of the reference image: `image/png`, `image/jpeg`, or `image/webp` |

### Prompt tips

For best results, include details about:

* **Genre**: cinematic, jazz, electronic, ambient, etc.
* **Mood**: dramatic, playful, tense, peaceful
* **Instruments**: grand piano, saxophone, synth pads, percussion, etc.
* **Tempo**: andante, fast-paced, steady groove

**Example prompts:**

* "Cinematic ambient track with warm synth pads, soft piano, and a gentle build"
* "Dramatic orchestral cue with rising strings and deep percussion"
* "Playful jazz trio with upright bass, brushed drums, and grand piano"
* "Tense electronic score with pulsing synths and a steady groove"

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is Lyria 3 and how does it work?">
    Lyria 3 is an AI-powered text-to-music API. You submit a text description of the music you want, choose a model variant, and optionally attach reference images. You receive a task ID immediately, then poll for results or receive a webhook notification. The generated track is delivered via a URL.
  </Accordion>

  <Accordion title="What is the difference between the clip and pro models?">
    `clip` (default) is optimized for faster generation of short clips, while `pro` produces higher-fidelity, professional-quality tracks. Select the variant with the `model` parameter.
  </Accordion>

  <Accordion title="How do reference images work?">
    Attach one or more entries in `reference_images` to guide the mood and style of the composition. Each entry needs a publicly accessible `image` URL (or GCS format) and its `mime_type` (`image/png`, `image/jpeg`, or `image/webp`).
  </Accordion>

  <Accordion title="What is the output format?">
    Lyria 3 returns an audio track delivered via a URL that remains accessible for download after task completion.
  </Accordion>

  <Accordion title="What is the prompt length limit?">
    The `prompt` must be between 10 and 2000 characters. Be specific about genre, mood, instruments, and tempo for the best results.
  </Accordion>

  <Accordion title="What are the rate limits for Lyria 3?">
    Rate limits vary by subscription tier. See [Rate Limits](/ratelimits) for current limits.
  </Accordion>

  <Accordion title="How much does Lyria 3 cost?">
    See the [Pricing page](/pricing) for current rates and subscription options.
  </Accordion>
</AccordionGroup>

## Best practices

* **Model selection**: use `clip` for fast iteration and short clips; switch to `pro` for final, professional-quality tracks
* **Reference images**: attach imagery that captures the target atmosphere to steer mood and style
* **Prompt specificity**: describe genre, mood, instruments, and tempo in detail for better accuracy
* **Production integration**: use webhooks instead of polling for scalable applications
* **Error handling**: implement retry logic with exponential backoff for 503 errors

## Related APIs

* **Google Lyria**: text-to-music that produces fixed 30-second instrumental tracks. See the [Google Lyria overview](/api-reference/music-generation/google-lyria/overview).
* **[ElevenLabs Music](/api-reference/music-generation/overview)**: generate 10-240 second music tracks from text
* **[Sound Effects](/api-reference/sound-effects/overview)**: generate sound effects from text descriptions
* **[Audio Isolation](/api-reference/audio-isolation/overview)**: isolate specific sounds from audio files