neurall-io Generations API

openapi: 3.2.0
info:
  title: Neurall API (v3) Generations API
  version: 1.0.0
  description: 'The public v3 surface: /v3/generations for async generations that produce a content asset, /v3/voices for the voice catalog and your own cloned voices, plus file uploads, per-feature pricing, read-only templates, and signed webhooks. Authenticate every call with an API key in the Authorization header. This document is machine-readable at https://api.neurall.io/v3/openapi.json (import it into Postman, or generate a client).'
servers:
- url: https://api.neurall.io
tags:
- name: Generations
  description: Async generations that produce content assets (v3)
paths:
  /v3/generations:
    post:
      summary: Create Generation
      description: Submits an async generation and returns immediately with status `pending`. Poll GET /v3/generations/{id} until the status is terminal, then read `output`, or pass `webhookUrl` to be notified instead (polling still works as a fallback).
      security:
      - ApiKeyAuth: []
      tags:
      - Generations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                feature:
                  type: string
                  description: 'The generation feature to run, namespaced by output kind (''<kind>/<name>''). The pre-namespacing flat spellings (e.g. image-generation, logo-reveal) are still accepted.

                    '
                  enum:
                  - image/self-portrait
                  - image/generation
                  - image/product-shot
                  - image/youtube-thumbnail
                  - image/ad
                  - video/logo-reveal
                  - video/object-reveal
                  - video/avatar
                  - audio/voiceover
                args:
                  type: object
                  description: Feature-specific inputs. Reference images and audio are file ids from /v3/files/upload. Every input is validated before the generation is accepted or billed; a file that fails answers a descriptive 400 and nothing is charged. Each feature's own docs page lists its arguments, formats and size caps.
                webhookUrl:
                  type: string
                  description: 'Optional https URL to POST the finished generation to when it reaches a terminal status (done / error / timeout). Deliveries are always signed with your project''s webhook secret, revealed on the playground''s API Keys page. Delivery is best-effort with a brief retry; polling remains authoritative.

                    '
              required:
              - feature
              - args
      callbacks:
        generationFinished:
          '{$request.body#/webhookUrl}':
            post:
              summary: Generation finished
              description: 'Sent once when the generation reaches a terminal status. The body matches GET /v3/generations/{id}, plus an `event` discriminator (`generation.done` | `generation.error` | `generation.timeout`). Headers: X-Neurall-Timestamp (unix seconds) and X-Neurall-Signature, one or more space-delimited entries of sha256=HMAC-SHA256(secret, "<timestamp>.<raw body>"), signed with your project''s webhook secret (two entries during the 24h window after a rotation). Verify against the RAW body and accept if any entry matches; reject stale timestamps to prevent replays.

                '
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        event:
                          type: string
                          enum:
                          - generation.done
                          - generation.error
                          - generation.timeout
                        generation:
                          $ref: '#/components/schemas/Generation'
              responses:
                '200':
                  description: Acknowledged (any 2xx stops retries)
      responses:
        '200':
          description: The pending generation
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation:
                    $ref: '#/components/schemas/Generation'
              example:
                generation:
                  id: 9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43
                  projectId: 3e8b2f60-91c4-4d7a-8f02-6b1de0a97c55
                  feature: image/self-portrait
                  kind: image
                  status: pending
                  params:
                    image: f_9c21e0b4
                    prompt: Cinematic studio portrait, moody side light against a deep grey backdrop.
                    aspectRatio: '3:4'
                  balanceUsed: 0.05
                  requestDate: '2026-08-25T17:04:12.000Z'
                  expiresAt: '2026-08-26T17:04:12.000Z'
        '400':
          description: Bad request (unknown feature, invalid args)
        '401':
          description: Unauthorized
        '402':
          description: Insufficient balance
      operationId: postV3Generations
      x-operation-id-source: derived
    get:
      summary: List Generations
      description: 'The project''s generations, newest first, keyset-paginated via `cursor`. Use it to recover ids you lost (a process that crashed between submitting and recording the id can find its work here) and to show recent activity in your own dashboard.


        It is NOT an archive: a generation created through the API drops out of this list once its `expiresAt` passes, 24 hours after the request, so treat it as a window on the last day rather than as storage.'
      security:
      - ApiKeyAuth: []
      tags:
      - Generations
      parameters:
      - name: feature
        in: query
        required: false
        description: Only generations for one feature, e.g. `video/logo-reveal`. The legacy flat spelling is accepted too and matches the same rows.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Generations per page. Defaults to 24, and anything above 100 is clamped to 100 rather than rejected.
        schema:
          type: integer
          default: 24
          maximum: 100
      - name: cursor
        in: query
        required: false
        description: The `nextCursor` of the previous page
        schema:
          type: string
      responses:
        '200':
          description: One page of generations
          content:
            application/json:
              schema:
                type: object
                properties:
                  generations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Generation'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: Pass it back as `?cursor=` for the next page; null on the last one.
              example:
                generations:
                - id: 9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43
                  feature: image/self-portrait
                  kind: image
                  status: done
                  output:
                    image: https://cdn.neurall.io/…/image.png
                    mime: image/png
                  balanceUsed: 0.05
                  requestDate: '2026-08-25T17:04:12.000Z'
                  responseDate: '2026-08-25T17:04:41.000Z'
                  expiresAt: '2026-08-26T17:04:12.000Z'
                nextCursor: null
        '401':
          description: Unauthorized
      operationId: getV3Generations
      x-operation-id-source: derived
  /v3/generations/{id}:
    get:
      summary: Get Generation
      description: 'The one call you make after submitting: poll it every few seconds (5 to 10 for the minute-scale renders: video, voice cloning) until `status` leaves `pending` and `running`, then read `output`. Statuses are `pending`, `running`, `done`, `error` and `timeout`; loop while the status is one of the first two rather than waiting for `done`, or a failed generation spins forever.


        The asset in `output` (`image`, `video` or `audio`, named by the generation''s kind) is a signed URL you should download, NOT a permanent address: a generation created through the API is reaped at `expiresAt`, 24 hours after the request, and this call then answers 404 as though the generation never existed.'
      security:
      - ApiKeyAuth: []
      tags:
      - Generations
      parameters:
      - name: id
        in: path
        required: true
        description: The generation id returned by POST /v3/generations.
        schema:
          type: string
      responses:
        '200':
          description: The generation
          content:
            application/json:
              schema:
                type: object
                properties:
                  generation:
                    $ref: '#/components/schemas/Generation'
              example:
                generation:
                  id: 9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43
                  projectId: 3e8b2f60-91c4-4d7a-8f02-6b1de0a97c55
                  feature: image/self-portrait
                  kind: image
                  status: done
                  params:
                    image: f_9c21e0b4
                    prompt: Cinematic studio portrait, moody side light against a deep grey backdrop.
                    aspectRatio: '3:4'
                  output:
                    image: https://cdn.neurall.io/…/image.png
                    mime: image/png
                  balanceUsed: 0.05
                  requestDate: '2026-08-25T17:04:12.000Z'
                  responseDate: '2026-08-25T17:04:41.000Z'
                  expiresAt: '2026-08-26T17:04:12.000Z'
        '401':
          description: Unauthorized
        '404':
          description: Generation not found
      operationId: getV3GenerationsById
      x-operation-id-source: derived
    delete:
      summary: Delete Generation
      description: 'Removes the generation and its rendered assets now, instead of waiting for the 24 hour expiry to do it. Reach for this when something has to be gone on request rather than on schedule: a user withdrew consent, or a render came back wrong and you do not want it reachable while your retry runs.


        It does not refund anything, since the render already happened, and it cannot cancel work that is still in flight.'
      security:
      - ApiKeyAuth: []
      tags:
      - Generations
      parameters:
      - name: id
        in: path
        required: true
        description: The generation id returned by POST /v3/generations.
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
              example:
                success: true
        '401':
          description: Unauthorized
        '404':
          description: Generation not found
      operationId: deleteV3GenerationsById
      x-operation-id-source: derived
components:
  schemas:
    Generation:
      type: object
      description: An async generation. `status` moves from `pending` through `running` to `done`, `error` or `timeout`; once done, `output` holds the asset as a signed URL named by the kind (image, video or audio) plus its `mime`.
      properties:
        id:
          type: string
        projectId:
          type: string
        feature:
          type: string
        kind:
          type: string
          enum:
          - image
          - video
          - audio
          - text
        status:
          type: string
          enum:
          - pending
          - running
          - done
          - timeout
          - error
        title:
          type: string
        params:
          type: object
          description: The submitted args (echoed back)
        output:
          type: object
          description: 'Set once status is done. The finished asset is served under the generation''s kind, mirroring the args side: exactly one of image, video or audio is present.'
          properties:
            image:
              type: string
              description: URL of the result (kind image)
            video:
              type: string
              description: URL of the result (kind video)
            audio:
              type: string
              description: URL of the result (kind audio)
            mime:
              type: string
              description: Media type of the result
        error:
          type: string
        balanceUsed:
          type: number
        requestDate:
          type: string
          format: date-time
        responseDate:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: 'API-created generations only: when the generation and its assets are deleted, 24 hours after the request. Absent on generations made in the app, which stay in its library.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization