Google

Lyria 3 Pro

lyria-3-pro

Google's advanced music generation model, capable of generating complete tracks of about 3 minutes in 48kHz stereo, understanding section structures such as intro, verse, and chorus, with better prompt adherence than Lyria 3

lyria-3-pro

Try lyria-3-pro

Input

Showcases

View all showcases

Output

audio

Fill in the parameters and run — results show up here.

Pricing

lyria-3-pro per song

Unit Price	$0.140

Overview

lyria-3-pro is a text-to-music model from Google, designed for developers who need complete songs rather than short clips. It describes genre, instruments, mood, tempo, lyrics, and song structure in the prompt, and can use timestamps to guide section arrangement. It also supports up to 10 guiding images to steer the creative direction. It suits teams that generate original soundtracks in bulk for videos, games, social content, and brand projects, and can be integrated into existing production workflows through the unified HiAPI.ai API.

Key Features

Generates structurally complete songs — supports specifying intro, verse, chorus, bridge, and other sections with timestamps in the prompt, producing complete songs with clear starts and ends rather than looped clips.
Higher prompt adherence — as the Pro version, it reproduces genre, instrumentation, and arrangement intent more accurately, reducing the cost of repeated retries and adjustments.
Images can guide the creative direction — upload up to 10 images per request as mood and theme references, transferring the tone of visual assets into music generation.
Seed-based reproducibility — pass a seed parameter for reproducible generation attempts, making it easier to control variables during iteration.

Capabilities

Text-to-music: describe genre, instruments, mood, tempo, lyrics, and song structure in a prompt to directly obtain usable original audio output.

Structured arrangement control: use timestamps such as [0:00 - 0:30] in the prompt to constrain section start and end points, so the output follows the intended narrative pacing.

Image guidance: pass 1 to 10 images as inspiration references to guide the mood, theme, and overall arrangement direction; the images themselves do not become visual assets of the output.

Reproducible generation: a seed parameter is provided for reproducible generation, making it easier to compare adjustments under the same settings, though strict determinism is not guaranteed.

Use Cases

Video production teams: generate soundtracks from shot lists — write shot rhythm and mood descriptions into the prompt to produce original music matching the video length, ready for editing and post-production workflows.
Game developers: custom background music — describe genre and section structure according to level atmosphere and looping needs to generate original BGM assets that can be embedded in games.
Brand and social media creators: custom theme music — use brand tone descriptions or reference images as input to generate exclusive music that fits the content, for ads and social content.
Tool developers: integrate music generation capabilities — connect text-to-music into their own creative tools or content platforms through the unified HiAPI.ai API to provide generation capabilities to end users.

Limitations and Selection Advice

The maximum duration per generation is about 3 minutes; works longer than that need to be generated in segments and then spliced together, and require manual post-editing to reach a final product. It outputs audio only, with no image or video capabilities. The more specific the prompt description, the easier it is to get usable results; vague descriptions may require multiple iterations. The seed improves reproducibility but is not strictly deterministic. If you only need short clips or lighter preview material, consider models in the same series such as Lyria 3.

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: lyria-3-pro

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for lyria-3-pro and route default — see the parameter table below.

seedintegerOptionalmin 0

Optional random seed for reproducible generation results; the same seed does not guarantee a fully deterministic output.

promptstringRequiredminLength 1

Text prompt describing genre, instruments, mood, tempo, lyrics, and song structure; you can add timestamps such as [0:00 - 0:30] to guide the arrangement's progression.

image_urlsarrayOptionalminItems 1maxItems 10

Optional array of inspiration images used to guide the mood, theme, and arrangement of the music; these images are not visual frames or source material for the audio output.

Array [ string ]

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "lyria-3-pro",
  "input": {
    "prompt": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "lyria-3-pro",
    input: {
      "prompt": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "lyria-3-pro",
        "input": {
          "prompt": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}