此文暂无当前语言版本,显示原文。
博客

Guide

Lyria 3 Pro Developer Guide: Capabilities, Pricing, and API Integration

Nov 16, 2026 13 min read
Cover art for the Lyria 3 Pro guide: a stack of offset bone-white paper sheets with charcoal edges and one rust-red interleaf, under flat studio light.
本页内容
Instrumental demo track generated with Lyria 3 Pro from a structured prompt — the same prompt is broken down line by line in the guide.

What Lyria 3 Pro Does and Where It Stops

Lyria 3 Pro is Google's text-to-music model, exposed on HiAPI as a single route with one capability: text-to-music. You send a text description — optionally accompanied by reference images — and you get back one piece of audio. That is the whole contract.

Understanding the boundary is more useful than reading a feature list, because most integration bugs come from expecting the model to do something adjacent to what it actually does.

What it produces

  • One audio output containing music, generated from a text prompt.
  • Music whose genre, instrumentation, mood, tempo, lyrical content, and arrangement you describe in natural language.
  • A result influenced by up to ten optional inspiration images, which steer mood and theme.

What it does not do

  • It does not generate images or video. There is no visual output of any kind.
  • It does not render a waveform picture, a score, MIDI, or timing metadata alongside the audio.
  • It does not sample, remix, or continue from source audio you supply. There is no audio input parameter.
  • It does not accept reference images as frames, cover art, or literal content. Images influence mood and theme only — nothing from them is reproduced visually or as sampled sound.
  • It does not offer resolution or quality tiers. There is one route and one output class.

If your product needs stems, per-instrument tracks, or editable MIDI, this model is not the tool for that job — the pipeline has to be designed around a finished mixed song as the atomic unit. That single-output assumption shapes everything downstream: storage, preview UX, and how you price the feature to your own users.

The model's dedicated page on HiAPI documents the route and its parameters; treat that as the source of truth for anything not covered here.

The Request Shape: Prompt, Images, and Seed

The request body is small. Three fields, one of them required.

prompt (required)

A string, minimum length 1, maximum length 5,000 characters. This is the only mandatory input. If you send nothing else, generation still succeeds — but a bare one-line prompt wastes most of the 5,000-character budget and produces generic results. The next section covers how to use that budget well.

image_urls (optional)

An array of URLs. minItems is 1 and maxItems is 10. These are inspiration images that guide mood, theme, and musical composition. They are explicitly not visual frames and not source media for the audio output. Omit the field entirely if you have no images; do not send an empty array, since the minimum is 1.

seed (optional)

An integer with a minimum of 0. Supplying a seed makes generation reproducible in the practical sense — the same prompt and seed together give you a stable reference point for re-runs — but exact determinism is not guaranteed. Log it alongside the prompt (details in the seed section below).

A minimal valid call

{
  "prompt": "Warm lo-fi hip hop, 82 BPM, dusty vinyl crackle, mellow Rhodes chords, instrumental",
  "seed": 12345
}

And the same request with inspiration images attached:

{
  "prompt": "Warm lo-fi hip hop, 82 BPM, dusty vinyl crackle, mellow Rhodes chords, instrumental",
  "image_urls": [
    "https://example.com/moodboard-1.jpg",
    "https://example.com/moodboard-2.jpg"
  ],
  "seed": 12345
}

Validation rules worth enforcing client-side

  • Trim whitespace before checking length; a prompt of only spaces will fail the minLength check server-side and costs you a round trip.
  • Count characters, not bytes, against the 5,000 limit — but leave headroom for user-added text if you are building a prompt composer.
  • Reject image_urls arrays with more than 10 entries before sending.
  • Reject negative seeds; zero is valid, so guard against falsy-value bugs in your own code.

Endpoint URL, auth headers, and response envelope follow the standard HiAPI route conventions rather than anything model-specific, so a working client for another route needs only a new model slug and the field map above.

Writing Prompts That Produce Usable Music

The prompt is where nearly all of the quality variance lives. A well-structured prompt covers six dimensions; a weak one covers one or two and lets the model guess the rest. Write them in a consistent order so results are comparable across iterations.

The six dimensions

  1. Genre and subgenre. Be specific. "Electronic" is a coin flip; "melodic techno with progressive structure" is a direction.
  2. Instruments. Name the lead and the rhythm section. "Analog polysynth lead, 808 kick, brushed snare, sub bass" gives the arrangement something to hold onto.
  3. Mood. Emotional register: melancholic, triumphant, tense, playful, hopeful. Mood words affect harmony and dynamics more than developers expect.
  4. Tempo. State BPM directly. It is unambiguous and cheap to include.
  5. Lyrics. If the track should have vocals, spell out the words and label which section they belong to. If it should be instrumental, say so explicitly — silence on this point invites vocals you did not want.
  6. Song structure. Intro, verse, chorus, bridge, outro, and how long each lasts.

Timestamps are the arrangement lever

The parameter documentation calls out bracketed timestamps such as [0:00 - 0:30] as a way to guide the arrangement. This is the most direct control you have over structure — use it to pin section boundaries instead of hoping the model infers them.

[0:00 - 0:15] Sparse intro: single Rhodes chord, vinyl noise, no drums
[0:15 - 0:45] Verse: add 808 kick and brushed snare, instrumental
[0:45 - 1:15] Chorus: full drums, sub bass enters, brighter chord voicing
[1:15 - 1:30] Outro: strip back to Rhodes, fade on vinyl noise

Lyrics inside a prompt

Put lyrics in a labeled, delimited block after the production description so the model does not confuse them with styling instructions:

Genre: indie folk. Instruments: fingerpicked acoustic guitar, upright bass,
light tambourine. Mood: wistful and warm. Tempo: 96 BPM.
Structure: [0:00 - 0:20] intro, [0:20 - 1:00] verse, [1:00 - 1:30] chorus.

Lyrics:
[verse]
Morning light on the kitchen floor
...
[chorus]
...

Practical iteration habits

  • Change one dimension per iteration. If you rewrite genre, tempo, and structure at once, you cannot attribute the difference.
  • Keep a library of prompts that worked as templates, and swap only the variable parts.
  • Put the most important constraints first. If the track must be instrumental, lead with that.
  • Keep prompts well under 5,000 characters. Long prompts are not automatically better; contradictory details are the usual failure mode, not insufficient length.

Steering Mood With Inspiration Images

The image_urls parameter is the most commonly misunderstood part of the request. It takes between 1 and 10 image URLs, and it influences mood, theme, and musical composition. It does not produce frames, cover art, or sampled audio, and nothing in the images is reproduced literally in the output.

What images actually do

Think of the array as a mood board. A set of photographs with a consistent emotional palette — cold blue night streets, or golden-hour desert textures — nudges the model toward a corresponding musical register. Combined with a text prompt, images refine a direction that text alone states too abstractly.

What images do not do

The model performs no frame output and no audio sampling. You cannot hand it a photo of a vinyl record and expect crackle to be lifted from the image; you cannot hand it a spectrogram and expect the audio to match it. If a crackle texture matters, describe it in the prompt.

Coordination between text and images

Images and prompt should agree. If your prompt says "bright major-key pop" and your images read as bleak and industrial, you are averaging two conflicting signals and the result will be muddy. Two workable patterns:

  • Text leads, images refine. Specify genre, instruments, and tempo in text; use images only to settle mood and texture.
  • Images lead, text constrains. Pick images first for emotional direction, then write a prompt that locks down genre and instrumentation so the mood does not drift into the wrong style.

Engineering concerns

  • Validate the array length on the client: at least 1, at most 10. Omit the field rather than sending an empty array.
  • Make URLs reliably fetchable. Prefer stable, long-lived public URLs over signed links that may expire before the generation runs.
  • Store the image URLs with each generation record. If an image later disappears, you lose the ability to explain or recreate the result.
  • Do not treat this parameter as a must-have. For production templates where mood is already specified in text, images add surface area without adding control — and every URL is one more thing that can fail.

Pricing and Cost Control at $0.14 per Song

Billing for Lyria 3 Pro is per song, at $0.14, with a single price tier. There is no resolution tier, no quality tier, and no duration-based multiplier to choose between. One successful generation of one song is one billable unit.

Why the single-tier model simplifies budgeting

Because there is exactly one price and one output class, your cost model collapses to a single multiplication: number of generations times the per-song rate. You do not need to reason about which tier a user selected, and you cannot accidentally route a request into a more expensive variant. Cost per user action is fixed and knowable in advance.

That property is unusual in media generation APIs and worth exploiting in product design: you can afford to show users an exact cost before they click generate.

Where spend actually leaks

Iteration, not unit price. A developer tuning a prompt through trial and error can easily burn through dozens of generations — the per-song rate is small, but it is charged on every attempt, including the ones you discard. Three habits keep that under control:

  • Batch your thinking, not your calls. Rewrite the whole prompt deliberately between attempts instead of firing variations to see what happens. Each call should test a hypothesis.
  • Pin down the cheap dimensions first. Genre, instrumentation, and tempo are textual and predictable. Settle them in a small number of exploratory calls, then spend calls only on mood and arrangement.
  • Treat seeds as free reproducibility. Once a seed produces something close, adjust the prompt around that seed rather than restarting from scratch.

Guardrails for user-facing features

  • Enforce a per-user or per-session generation cap. Regeneration is the most common user behavior and the most predictable cost driver.
  • Log every generation with its prompt, parameters, and billed status so you can reconcile usage against your own records.
  • Distinguish failed requests from successful ones in your accounting. A rejected call is a validation problem, not a billing decision — but you should be able to prove the difference.
  • For subscription products, map the per-song cost to your internal credit system rather than exposing raw billing units to end users.

Current pricing for the route lives on the HiAPI price panel; treat that panel as authoritative if anything here ever drifts from it.

Making Generation Reproducible With Seed

The seed parameter is an optional integer, minimum 0. It exists so you can get back to a generation you liked.

What the seed guarantees — and what it doesn't

The documentation is precise: seed supports reproducible generation, but exact determinism is not guaranteed. Read that literally. Same prompt plus same seed gives you a strong expectation of a similar result, not a byte-identical file. Treat the seed as a stable anchor, not a checksum.

This matters for how you present the feature. Do not tell users that regenerating with the same seed yields the identical track — say it re-runs the same creative direction.

The practical logging pattern

The seed is only useful if it is stored next to everything else that shaped the output. For every generation, persist:

  • the full prompt text, exactly as sent (including whitespace and bracketed timestamps);
  • the seed value;
  • the image_urls array, if any;
  • the created timestamp and the resulting asset reference.

Storing the seed alone is worthless — a seed without its prompt does not reproduce anything. A single record containing prompt plus seed plus images is what makes a generation replayable.

Choosing seed values

  • User-pinned seeds. Let a power user fix a seed and iterate the prompt around it, which is the highest-value use of the feature.
  • Server-assigned seeds for auditability. Assign a random valid integer server-side and store it with every generation, even when the user did not ask for one. You then always have an anchor for later refinement.
  • Do not reuse seeds across unrelated projects. A seed that works beautifully on one arrangement carries no meaning for another; it just adds confusion to your records.

Handling the non-determinism

If your pipeline does any automated comparison of regenerated output, treat an identical match as a bonus and a near-match as success. Build the UX around "come back to this direction" rather than "restore this exact file," and store the actual rendered asset for anything the user has saved or published.

Integration Checklist Before You Ship

A short list to run through before the feature goes live.

Parameters

  • prompt is present, trimmed, non-empty, and within the 5,000-character limit.
  • image_urls is either omitted or an array of 1 to 10 fetchable URLs — never an empty array.
  • seed is a non-negative integer; zero is handled correctly by your validation code.
  • The route slug is correct for this family, and no sibling model slugs have leaked into your config.

Failure handling

  • Validation errors surface to the caller as actionable messages before a request is billed.
  • Generation timeouts have a defined retry policy, and retries are counted against user quotas so a flaky network does not silently multiply spend.
  • Non-music or unsupported requests (stem separation, audio continuation, visual output) are rejected at your own layer with a clear explanation rather than forwarded to the model.

Cost guardrails

  • Per-user generation caps exist and are enforced before the call, not after.
  • Every generation record carries its billing status so your usage numbers reconcile.
  • The displayed per-song cost is sourced from the live price panel rather than hardcoded.

Records

  • Prompt, seed, image URLs, timestamp, and output asset are stored together for every generation.
  • Saved and published generations have their rendered asset persisted, not just their parameters.
  • You can reconstruct any generation a user can still see in their history.

When those boxes are checked, the integration is straightforward: one required string, two optional fields, one audio output, one per-song charge. The Lyria 3 Pro model page is the place to confirm the route details and current pricing before you ship.

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档