Lacuna Lacuna Music API API
The Lacuna Music API API from Lacuna — 0 operation(s) for lacuna music api.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lacuna-lacuna-music-api-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Lacuna Music API
version: 0.1.0
description: 'HTTP API for AI music generation.
## Authentication
All requests must include a Bearer token in the `Authorization` header:
```
Authorization: Bearer lyr_live_xxxxxxxx__xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
API keys are created in your [profile dashboard](/profile/api). The full key is shown once at creation;
store it securely.
## Subscription Required
Music API access requires the **Pro** plan or above. Requests from users on lower tiers
(or whose subscription has lapsed back to a lower tier) return:
```
HTTP 403
{ "error": { "type": "permission_error", "code": "tier_insufficient", "message": "..." } }
```
The check happens on every request — downgrading invalidates active keys without revoking them.
## Errors
All errors follow OpenAI-style envelope:
```json
{ "error": { "type": "...", "code": "...", "message": "...", "param": "..." } }
```
## Rate Limits
- **Concurrent**: per API key, default 10 (Pro) / 20 (Ultra). Account-specific overrides may apply. Exceeding returns `429 concurrent_limit_exceeded`.
- **RPM**: 60 requests per minute per API key. Exceeding returns `429 rpm_exceeded`.
- All 429 responses include `Retry-After` header.
## Pricing
Credits are charged per generation request and vary by model:
| Model | Credits |
| --- | ---: |
| `aether` | 50 |
| `echo` | 80 |
| `nocturne` | 180 |
Credits are deducted on POST and refunded if the provider call fails (synchronously or via async
callback). See your dashboard for current balance.
## Webhooks
Subscribe via the [dashboard](/profile/api). Events are signed with HMAC-SHA256 in `X-Lacuna-Signature`:
```
X-Lacuna-Signature: t=1730000000,v1=<hex>
```
To verify:
```js
const signed = `${timestamp}.${rawBody}`
const expected = crypto.createHmac(''sha256'', secret).update(signed).digest(''hex'')
```
Reject if timestamp is more than 5 minutes old or signatures don''t match.'
servers:
- url: https://www.lacuna.fm/api
description: Production
security:
- bearerAuth: []
tags:
- name: Lacuna Music API
paths: {}
webhooks:
job.completed:
post:
summary: Music generation completed
description: Sent when a task transitions to `ready` state. `tracks` contains final R2-hosted audio URLs.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JobCompletedEvent'
responses:
2XX:
description: Acknowledged. Any 2xx response prevents retry.
tags:
- Lacuna Music API
job.failed:
post:
summary: Music generation failed
description: Sent when the task transitions to `failed`. Credits are refunded automatically.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JobFailedEvent'
responses:
2XX:
description: Acknowledged.
tags:
- Lacuna Music API
credits.low:
post:
summary: Credit balance dropped below threshold
description: 'Edge-triggered: fires once when balance crosses below `creditAlertThreshold`. Will not re-fire until balance returns above threshold and crosses below again.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreditsLowEvent'
responses:
2XX:
description: Acknowledged.
tags:
- Lacuna Music API
key.expiring:
post:
summary: API key expiring within 24 hours
description: Sent once per key, 24 hours before expiry.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KeyExpiringEvent'
responses:
2XX:
description: Acknowledged.
tags:
- Lacuna Music API
components:
schemas:
JobFailedEvent:
allOf:
- $ref: '#/components/schemas/WebhookEnvelope'
- type: object
properties:
type:
type: string
enum:
- job.failed
data:
type: object
properties:
task_id:
type: string
status:
type: string
enum:
- failed
error:
type: object
properties:
code:
type: string
message:
type: string
credits_refunded:
type: integer
created_at:
type: string
format: date-time
JobCompletedEvent:
allOf:
- $ref: '#/components/schemas/WebhookEnvelope'
- type: object
properties:
type:
type: string
enum:
- job.completed
data:
type: object
properties:
task_id:
type: string
status:
type: string
enum:
- ready
tracks:
type: array
items:
$ref: '#/components/schemas/Track'
credits_used:
type: integer
created_at:
type: string
format: date-time
WebhookEnvelope:
type: object
required:
- id
- type
- created
- data
properties:
id:
type: string
example: evt_abc123
type:
type: string
created:
type: integer
description: Unix timestamp (seconds).
data:
type: object
KeyExpiringEvent:
allOf:
- $ref: '#/components/schemas/WebhookEnvelope'
- type: object
properties:
type:
type: string
enum:
- key.expiring
data:
type: object
properties:
api_key_id:
type: string
prefix:
type: string
name:
type: string
expires_at:
type: string
format: date-time
days_until_expiry:
type: integer
Track:
type: object
required:
- id
- audio_url
- duration
- title
- lyrics
- image_url
- tags
- index
properties:
id:
type: string
audio_url:
type: string
format: uri
duration:
type:
- number
- 'null'
description: Seconds
title:
type:
- string
- 'null'
lyrics:
type:
- string
- 'null'
image_url:
type:
- string
- 'null'
format: uri
tags:
type:
- string
- 'null'
index:
type: integer
description: Track index within this task
CreditsLowEvent:
allOf:
- $ref: '#/components/schemas/WebhookEnvelope'
- type: object
properties:
type:
type: string
enum:
- credits.low
data:
type: object
properties:
threshold:
type: integer
balance:
type: integer
subscription_credits:
type: integer
onetime_credits:
type: integer
securitySchemes:
bearerAuth:
type: http
scheme: bearer