Docs / Media Generation

Media Generation

The public media endpoint is POST /api/inference/assets/generate. It creates a job and returns a generation/job id. You can check the status via GET or subscribe to updates.

Lifecycle

Step	What happens
1. POST /api/inference/assets/generate	Create a media generation job.
2. Receive id and status	The initial response returns the generation ID and processing status.
3. Get /api/inference/assets/:id/status	Poll or listen via SSE until the job leaves `queued` or `processing`.
4. Fetch the result	Once the job succeeds, retrieve the file via `resultUrl`.

POST /api/inference/assets/generate

This is the external media generation endpoint.

json

{
  "model": "gpt-image-2",
  "inputs": {
    "prompt": "A brutalist poster for a jazz festival",
    "aspectRatio": "1:1"
  }
}

Initial response

json

{
  "id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "status": "processing",
  "sparksUsed": 2,
  "newSparkBalance": 98
}

GET /api/inference/assets/:id/status

Poll or subscribe to this endpoint until the job completes. Supports Server-Sent Events (SSE) when requested with Accept: text/event-stream.

In-progress response

json

{
  "id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "status": "processing"
}

Succeeded response

json

{
  "status": "succeeded",
  "id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "resultUrl": "/api/files/7fdc12c1-3d4d-4d4c-8de8-f53cc5d82370",
  "fileId": "7fdc12c1-3d4d-4d4c-8de8-f53cc5d82370",
  "mimeType": "image/png"
}

Failed response

json

{
  "id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "status": "failed",
  "error": "Generation failed."
}

Models endpoint

Discover live media models at GET /api/inference/models?type=media.