Generate AI music
programmatically.

Music API access requires the Pro plan or above. From your dashboard, create a key — it's shown once at creation; copy it into a secrets manager immediately. Keys begin with lyr_live_.

The official SDK is lacuna-sdk — typed TypeScript client on Node 18+. Prefer the command line? Install lacuna-toolkit instead.

npm install lacuna-sdk
# or
pnpm add lacuna-sdk
# or
yarn add lacuna-sdk

Create a task. Credits are deducted up-front at the selected model's rate and refunded automatically if the upstream provider fails. The response is a complete task object; use its id to poll.

import Lacuna from 'lacuna-sdk'

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

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

console.log(task.id, task.status) // 'cm123abc...' 'pending'

Tasks run asynchronously. waitFor polls until the task reaches a terminal state. For production traffic, prefer webhooks — see step 5.

const finished = await lacuna.music.generations.waitFor(task.id, {
  pollInterval: 5_000, // poll every 5s
  timeout: 600_000,    // up to 10 minutes
})

if (finished.status === 'ready') {
  for (const track of finished.tracks) {
    console.log(track.audio_url, track.duration, track.lyrics)
  }
}

Subscribe to job.completed and job.failed events and verify their HMAC-SHA256 signatures. The SDK ships a verifier with replay protection.

// Next.js (App Router) — app/api/webhooks/lacuna/route.ts
import { Webhooks } from 'lacuna-sdk/webhooks'

export async function POST(request: Request) {
  const body = await request.text()
  const event = Webhooks.constructEvent(
    body,
    request.headers.get('x-lacuna-signature'),
    process.env.LACUNA_WEBHOOK_SECRET!,
  )

  if (Webhooks.isJobCompleted(event)) {
    // event.data.tracks is fully typed
  }

  return new Response(null, { status: 200 })
}