Google Lyria 3 Pro API

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

Image, video, and audio models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	lyria-3-pro
Type	Audio generation (text-to-music)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Generate full songs up to approximately three minutes from prompts and optional inspiration images; images guide the music and are not video frames or audio source media.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Full song generation

Generate a complete song with vocals and arrangement from a style and structure prompt, up to approximately three minutes.

prompt

Image-inspired music

Provide one to ten inspiration images so the mood, theme, and arrangement respond to the visual input; images guide the music and are not audio source media.

image_urlsprompt

Lyrics and section control

Use lyrics, [Verse], [Chorus], and timestamp markers in the prompt to guide the song structure.

prompt

Request parameters

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

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "lyria-3-pro",
  "input": {
    "prompt": "Create an atmospheric ambient song inspired by the mood and colors in the inspiration image, with gentle piano, strings, and a gradual cinematic rise.",
    "image_urls": [
      "https://tjzk.replicate.delivery/models_models_featured_image/22671d81-7e89-4db5-bd35-0d2c514fd74e/Lyria-3-Pro_thumbnail.width-13.png"
    ]
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "lyria-3-pro",
  "input": {
    "prompt": "Create an atmospheric ambient song inspired by the mood and colors in the inspiration image, with gentle piano, strings, and a gradual cinematic rise.",
    "image_urls": [
      "https://tjzk.replicate.delivery/models_models_featured_image/22671d81-7e89-4db5-bd35-0d2c514fd74e/Lyria-3-Pro_thumbnail.width-13.png"
    ]
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "lyria-3-pro",
  "input": {
    "prompt": "Create an atmospheric ambient song inspired by the mood and colors in the inspiration image, with gentle piano, strings, and a gradual cinematic rise.",
    "image_urls": [
      "https://tjzk.replicate.delivery/models_models_featured_image/22671d81-7e89-4db5-bd35-0d2c514fd74e/Lyria-3-Pro_thumbnail.width-13.png"
    ]
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value lyria-3-pro.

example lyria-3-pro

input object required

Business parameters. Put Google Lyria 3 Pro-specific configuration here.

prompt string required

Describe genre, instruments, mood, tempo, lyrics, and song structure. Timestamps such as [0:00 - 0:30] can guide the arrangement.

image_urls string[] optional

Optional inspiration images that guide the mood and theme of the musical composition; they are not audio source media.

seed integer optional

Optional seed for reproducible generation; exact determinism is not guaranteed.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Image-inspired score

Use an inspiration image to guide the color and atmosphere of the composition; it guides the audio generation rather than becoming source media.

Request body

{
  "model": "lyria-3-pro",
  "input": {
    "prompt": "Create an atmospheric ambient song inspired by the mood and colors in the inspiration image, with gentle piano, strings, and a gradual cinematic rise.",
    "image_urls": [
      "https://tjzk.replicate.delivery/models_models_featured_image/22671d81-7e89-4db5-bd35-0d2c514fd74e/Lyria-3-Pro_thumbnail.width-13.png"
    ]
  }
}

Summer-night indie pop

Generate a full song from genre, instruments, mood, and section guidance.

Request body

{
  "model": "lyria-3-pro",
  "input": {
    "prompt": "A warm indie-pop song with acoustic guitar, soft drums, and a hopeful summer-night chorus. Include clear verse and chorus sections."
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated audio from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

How long can the generated song be?

Lyria 3 Pro generates songs up to approximately three minutes. Prompt wording and timestamps can guide the duration.

How many inspiration images can I provide?

Provide up to ten inspiration images in the input.image_urls array. They guide the mood and theme of the music; they are not video-style frames.

How do I control lyrics and sections?

Put lyrics and structure tags such as [Verse], [Chorus], and [Bridge] directly in the prompt.