Lacuna Lacuna Music API API

openapi: 3.2.0
info:
  title: Lacuna Music Lacuna Music API 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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer