Lacuna Music

lacuna-music

Generate AI music programmatically through the Lacuna Music API.

When to use this

Activate when the user wants to:

• Generate a track from a style description ("lofi piano, 70 bpm", "synthwave, retro drums")
• Add background music to a video, demo, presentation, or app
• Produce a jingle, intro, outro, or stinger from a brief
• Compose a vocal song from custom lyrics

Pick a transport

Three packages, same underlying API. Pick the first that fits the user's environment:

lacuna-mcp (preferred for AI agents)

claude mcp add lacuna -- npx -y lacuna-mcp

Set LACUNA_API_KEY in the MCP env block. After adding, three tools become available: generate_music, get_generation, wait_for_generation. Call generate_music then wait_for_generation to receive the final audio_url.

lacuna-sdk

import Lacuna from 'lacuna-sdk'

const lacuna = new Lacuna({ apiKey: process.env.LACUNA_API_KEY })

const task = await lacuna.music.generations.create({
  style: 'lofi piano, 70 bpm, mellow',
  title: 'Study session',
  instrumental: true,
})

const finished = await lacuna.music.generations.waitFor(task.id)
console.log(finished.tracks[0]?.audio_url)

lacuna-toolkit

npx lacuna-toolkit music generate \
  --style "synthwave, retro drums, 110 bpm" \
  --title "Neon Drive" \
  --instrumental \
  --wait \
  --output json

Authentication

Get a key at lacuna.fm/profile/api. It begins with lyr_live_ and is shown once at creation. Pass it via LACUNA_API_KEY env var.

Music API access requires a Pro plan or above. Lower tiers receive 403 permission_error / tier_insufficient — do not retry; tell the user to upgrade.

Generation parameters

The API rejects model-incompatible fields with 400 invalid_param (e.g. passing style_weight with model: 'echo').

Models

Lifecycle

1. create returns immediately with a task in pending status.
2. Generation typically completes in 60–120 seconds.
3. waitFor (SDK) / --wait (CLI) / wait_for_generation (MCP) polls until ready or failed.
4. On ready, task.tracks[] contains one or more renders, each with audio_url, duration, title, lyrics, image_url, tags.
5. On failed, inspect task.error — credits are refunded automatically.

For production workflows, prefer the job.completed webhook over polling. See the SDK webhook docs for verification helpers.

Credits and pricing

• Cost depends on the selected model — confirm on the pricing page.
• Failed generations refund automatically.
• If a request returns 402 insufficient_credits, do not retry — tell the user to top up.

Working with audio_url

audio_url points to the generated output on Lacuna's CDN and does not have a 24-hour expiry. Downloading a separate copy is optional and depends on the user's own storage or processing workflow.

Constraints to respect

• Use the default 5-second polling interval unless the workflow has a specific reason to change it.
• Don't hardcode API keys; always read from LACUNA_API_KEY.
• Don't retry on 403 tier_insufficient or 402 insufficient_credits — these are user-action errors.
• On 503 model_unavailable, the requested model is temporarily circuit-broken (error.model names which one). Switch to a different model and retry; do not loop on the same one. The SDK does not auto-fallback because each model has a different credit cost.

Resources

• API and pricing: https://lacuna.fm
• Get an API key: https://lacuna.fm/profile/api
• SDK: lacuna-sdk
• CLI: lacuna-toolkit
• MCP server: lacuna-mcp
• Source code: https://github.com/JOYLINK-LTD/lacuna-toolkit