Google Lyria 3 Clip Music API Documentation

Google Lyria 3 Clip Music API Documentation

Playground

Google Lyria 3 Clip generates novel music tracks from text prompts and optional image input. Produces complete songs with lyrics, descriptions, and audio output. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Google Lyria 3 Clip is Google’s advanced AI music generation model. Describe the sound you want in natural language — genre, tempo, instruments, mood, and style — and get a high-quality music clip in seconds. Optionally guide the output with a reference image.

Why Choose This?

• Detailed text-to-music generation Describe your track with as much or as little detail as you want — genre, BPM, instruments, energy level, and mood all influence the output.

• Image-guided generation Upload a reference image to inspire the musical mood and atmosphere of the clip.

• Prompt Enhancer Built-in tool to automatically refine your music descriptions for richer results.

Parameters

How to Use

1. Write your prompt — describe the genre, tempo, instruments, mood, and style. Use the Prompt Enhancer for better results.
2. Upload a reference image (optional) — provide an image to inspire the musical atmosphere.
3. Submit — generate and download your music clip.

Example Prompt

Driving techno track, heavy kick drum at 130 BPM, dark industrial synths, repetitive hypnotic bassline, Berlin underground club style, no vocals.

Pricing

Just $0.04 per clip.

Best Use Cases

• Content Creation — Generate background music for videos, podcasts, reels, and social media content.
• Game & Interactive Media — Produce atmospheric tracks and sound design for games and apps.
• Advertising — Create custom music beds for promotional videos without licensing fees.
• Creative Exploration — Rapidly prototype musical ideas and styles from text descriptions.
• Mood & Ambience — Generate focus music, relaxation tracks, or energetic workout playlists on demand.

Pro Tips

• Be specific about BPM, key instruments, and energy level for the most accurate results.
• Put exclusions in the prompt itself, for example “no vocals” or “no drums”.
• Generation is not deterministic; run the same prompt again to get a new variation.
• Try pairing abstract or atmospheric images with a minimal prompt to let the image drive the mood.
• Use the Prompt Enhancer to expand a simple style reference into a detailed music description.

Notes

• Only prompt is required; image is optional.
• Please ensure your content complies with Google’s usage policies.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/google/lyria-3-clip/music" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters