Docs / Media Generation

Media Generation

The public media endpoint is POST /api/inference/media. It creates a job and returns a job id. You then poll the media job endpoint.

Lifecycle

Step	What happens
1. POST /api/inference/media	Create a media generation job.
2. Receive job_id	The initial response returns only the job id and status.
3. Poll /api/inference/media/:jobId	Poll until the job leaves `queued`, `submitted`, or `processing`.
4. Fetch the result	Once the job succeeds, use the returned file URL.

POST /api/inference/media

This is the external media generation endpoint. It is separate from the internal /api/generate route.

json

{
  "type": "image",
  "model": "gpt-image-1.5",
  "prompt": "A brutalist poster for a jazz festival",
  "aspectRatio": "1:1",
  "resolution": "standard"
}

Initial response

json

{
  "job_id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "status": "queued",
  "poll_url": "/api/inference/media/4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6"
}

GET /api/inference/media/:jobId

Poll this endpoint until the job completes.

In-progress response

json

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

Succeeded response

json

{
  "job_id": "4c660f2d-2ee0-4f58-8f8e-8dfd52d4e0f6",
  "status": "succeeded",
  "result_url": "/api/files/7fdc12c1-3d4d-4d4c-8de8-f53cc5d82370",
  "file_id": "7fdc12c1-3d4d-4d4c-8de8-f53cc5d82370",
  "mime_type": "image/png"
}

Failed response

json

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

Models endpoint

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