Luma Dream Machine API Callback

asyncapi: '2.6.0'
id: 'urn:com:lumalabs:dream-machine:callback'
info:
  title: Luma Dream Machine API Callback
  version: '1.0.0'
  description: |
    Server-to-server callback delivered by the Luma Dream Machine API when
    an asynchronous generation transitions between states. Luma POSTs a
    JSON document carrying the `Generation` object to a customer-supplied
    `callback_url` provided at submission time on the generation create
    endpoints (for example `POST /dream-machine/v1/generations/video`,
    `/generations/image`, and related modify, reframe, upscale, and audio
    endpoints).

    The documented surface, taken from the Luma Labs developer
    documentation (https://docs.lumalabs.ai/) and the
    "Callbacks & Credits Balance" changelog entry at
    https://docs.lumalabs.ai/changelog/callbacks-and-credits-balance,
    states:

      - The callback is an HTTP `POST` request.
      - The request body is the `Generation` object JSON.
      - All updates are sent over the callback channel (state, video URL,
        failure reason).
      - Luma retries delivery 3 times with a 100ms delay and a 5 second
        request timeout when the receiver does not return HTTP 200.

    Fields that are not part of the documented callback contract — for
    example a signed-payload header (no `X-Luma-Signature` is documented
    at the time of writing), an idempotency key, or a discrete event
    envelope wrapping the `Generation` object — are intentionally NOT
    modeled here. The receiver should treat the body as the same
    `Generation` representation returned by
    `GET /dream-machine/v1/generations/{id}` and dispatch on the `state`
    field.

    For details not covered by this AsyncAPI document (per-field schemas
    of every request variant, error codes, rate limits, billing), consult
    the corresponding REST OpenAPI definition at
    `openapi/luma-ai-openapi.yml` and the live docs at
    https://docs.lumalabs.ai/.
  contact:
    name: Luma Labs
    url: https://docs.lumalabs.ai/
  license:
    name: Proprietary
    url: https://lumalabs.ai/legal/tos

defaultContentType: application/json

servers:
  customer-callback:
    url: '{callback_url}'
    protocol: https
    description: |
      Customer-hosted HTTPS endpoint that receives the callback POST.
      Configured per-generation via the `callback_url` parameter on the
      Dream Machine generation create endpoints (video, image, modify,
      reframe, upscale, add-audio). The endpoint must return HTTP 200;
      Luma retries 3 times with a 100ms delay and a 5 second timeout if
      a non-200 response is observed.
    variables:
      callback_url:
        description: >-
          Fully qualified HTTPS URL of the customer endpoint that receives
          the callback POST. Supplied on the generation request body as
          the `callback_url` field.
        default: https://example.com/luma/callback

channels:
  generation-callback:
    description: |
      The customer endpoint that receives one HTTP POST from Luma each
      time a generation transitions to a state that Luma reports
      out-of-band. The same channel carries every documented `state`
      value for every generation type (video, image, modify, reframe,
      upscale, add-audio); the receiver dispatches on the `state` field
      of the `Generation` payload.

      Receivers should return HTTP 200 as soon as the payload has been
      durably accepted. Non-200 responses, timeouts longer than 5
      seconds, or transport errors cause Luma to retry up to 3 times
      with a 100ms delay between attempts.
    bindings:
      http:
        type: request
        method: POST
    subscribe:
      summary: >-
        Receive a Generation state update from the Luma Dream Machine API.
      operationId: receiveGenerationCallback
      bindings:
        http:
          type: request
          method: POST
      message:
        $ref: '#/components/messages/GenerationCallback'

components:
  messages:
    GenerationCallback:
      name: GenerationCallback
      title: Generation state callback
      summary: >-
        A Generation object delivered by Luma when a generation
        transitions to a new state (for example `dreaming`, `completed`,
        or `failed`).
      contentType: application/json
      bindings:
        http:
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                const: application/json
      payload:
        $ref: '#/components/schemas/Generation'
      examples:
        - name: completed-video
          summary: A completed text-to-video generation
          payload:
            id: 'd1ad97c4-9d8f-4e3a-9c2e-3b8c0b9b1e2a'
            state: completed
            failure_reason: null
            created_at: '2026-05-30T12:34:56.000Z'
            assets:
              video: 'https://storage.cdn-luma.com/.../generation.mp4'
            version: ray-2
            request:
              prompt: >-
                A teddy bear in sunglasses playing electric guitar
                and dancing
              aspect_ratio: '16:9'
              loop: false
        - name: failed-video
          summary: A failed generation
          payload:
            id: 'fbb8c4c1-6f0a-4f9d-8a64-4c6c1f6c9f00'
            state: failed
            failure_reason: 'Generation failed due to invalid keyframe asset.'
            created_at: '2026-05-30T12:34:56.000Z'
            assets: null
            request:
              prompt: 'A surfer riding a wave at sunset'

  schemas:
    Generation:
      type: object
      description: |
        The Generation object as returned by `GET /dream-machine/v1/generations/{id}`
        and POSTed verbatim to the customer `callback_url`. Only fields
        whose presence is supported by the public Luma developer
        documentation are modeled here.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the generation.
        state:
          type: string
          description: |
            Lifecycle state of the generation. Documented values include
            `dreaming` (in progress), `completed` (success), and `failed`.
          enum:
            - dreaming
            - completed
            - failed
        failure_reason:
          type:
            - string
            - 'null'
          description: >-
            Human-readable failure description when `state` is `failed`.
            `null` for non-failed states.
        created_at:
          type: string
          format: date-time
          description: ISO-8601 timestamp at which the generation was created.
        assets:
          oneOf:
            - $ref: '#/components/schemas/GenerationAssets'
            - type: 'null'
          description: >-
            Resulting media assets. Populated when `state` is
            `completed`. May be `null` for in-progress or failed
            generations.
        version:
          type: string
          description: >-
            Model identifier used to produce the generation (for example
            `ray-2`).
        request:
          $ref: '#/components/schemas/GenerationRequestEcho'
      required:
        - id
        - state

    GenerationAssets:
      type: object
      description: |
        URLs to the rendered media produced by the generation. The set
        of fields varies by generation type; only `video` and `image`
        are documented as members of the assets object.
      properties:
        video:
          type: string
          format: uri
          description: HTTPS URL to the generated video file (video generations).
        image:
          type: string
          format: uri
          description: HTTPS URL to the generated image file (image generations).

    GenerationRequestEcho:
      type: object
      description: |
        Echo of the original request body that produced this generation.
        The shape mirrors the request body sent to the corresponding
        REST endpoint; only fields explicitly documented for Dream
        Machine generations are listed here. Additional request fields
        observed in the live response (for example `model`, `duration`,
        `resolution`, or modify/reframe-specific inputs) are permitted
        via `additionalProperties: true`.
      additionalProperties: true
      properties:
        prompt:
          type: string
          description: Natural-language prompt provided at submission.
        aspect_ratio:
          type: string
          description: >-
            Aspect ratio of the requested output (for example `16:9`,
            `9:16`, `1:1`).
        loop:
          type: boolean
          description: Whether the resulting video should loop.
        keyframes:
          type: object
          description: >-
            Keyframe inputs for video generation (`frame0`, `frame1`),
            each carrying a `type` and a referenced asset URL or
            generation id. See the REST OpenAPI for full schema.
          additionalProperties: true
        callback_url:
          type: string
          format: uri
          description: >-
            The callback URL originally supplied on the generation
            create request. Echoed when present in the request body.