Generations

API

Submit a generation and collect the finished asset. Every feature in the platform runs through this one collection.

Generated from the live contract. The same page as markdown, and the whole surface as openapi.json.

In this collection

GET List Generations
POST Create Generation
GET Get Generation
DELETE Delete Generation

List Generations

GET /v3/generations

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.

curl -X GET "https://api.neurall.io/v3/generations" \
  -H "Authorization: nl-YOUR_API_KEY"

Query

featurestring: Only generations for one feature, e.g. `video/logo-reveal`. The legacy flat spelling is accepted too and matches the same rows.
limitinteger: Generations per page. Defaults to 24, and anything above 100 is clamped to 100 rather than rejected.
cursorstring: The `nextCursor` of the previous page

Responses

200 One page of generations

generationsobject[]: 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`.
nextCursorstring: 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 Unauthorized

Create Generation

POST /v3/generations

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).

curl -X POST "https://api.neurall.io/v3/generations" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "<feature>",
    "args": { },
    "webhookUrl": "<webhookUrl>"
  }'

Body

featurestringrequired: 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.; image/self-portraitimage/generationimage/product-shotimage/youtube-thumbnailimage/advideo/logo-revealvideo/object-revealvideo/avataraudio/voiceover
argsobjectrequired: 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.
webhookUrlstring: 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.

Responses

200 The pending generation

generationobject: 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`.

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 Bad request (unknown feature, invalid args)

401 Unauthorized

402 Insufficient balance

Get Generation

GET /v3/generations/{id}

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.

curl -X GET "https://api.neurall.io/v3/generations/<id>" \
  -H "Authorization: nl-YOUR_API_KEY"

Path

idstringrequired: The generation id returned by POST /v3/generations.

Responses

200 The generation

generationobject: 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`.

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 Unauthorized

404 Generation not found

Delete Generation

DELETE /v3/generations/{id}

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.

curl -X DELETE "https://api.neurall.io/v3/generations/<id>" \
  -H "Authorization: nl-YOUR_API_KEY"

Path

idstringrequired: The generation id returned by POST /v3/generations.

Responses

200 Deleted

successboolean

Example

{
  "success": true
}

401 Unauthorized

404 Generation not found