Skip to main content
GET
Get an image generation
GET /v1/images/{image_id} returns the current state of a job created by Generate Image — the same Image object the create request answered with. Poll every 2–3 seconds until status is ready or failed, then download each PNG from images[].url. You can only read jobs created with the same API key. An unknown ID, or one created by a different key, answers 404 NOT_FOUND — the two cases are deliberately indistinguishable.

Request parameters

Response parameters

Returns 200 OK with an Image object.

Ready example

Signature query parameters shortened:

Failed example

Status and errors

A job only moves forward: queued → processing → ready or failed. It is never cancelled. A job either produces all n images or fails as a whole — it never returns a partial set. error.code on a failed job: A failed job is refunded in full, even if some images had already been generated before it failed. Retrying means creating a new job, which reserves its own credits. HTTP errors from this endpoint: These use the same error object as a failed job’s error, wrapped as {"error": {...}}. See Errors and recovery.

Timing

Measured in production on 2026-10-12: two 1K images took about 17–22 seconds; one 2K image with a reference image took about 37 seconds. Images are generated one at a time, so a larger n takes longer, and at peak times a job first waits in queued. A job that hasn’t finished within 15 minutes fails with SERVICE_BUSY.

Data retention

  • Generated images are deleted 24 hours after the job finishes — download them before then. Afterwards this endpoint still returns the job, still ready, but every images[].url is null.
  • Reference images you upload, or that Viggle downloads from a reference_image_url, are deleted within 24 hours.
  • Customer data is never used to train models.

Examples

Quick Start: Viggle Image

Follow the complete create, poll, and download flow.

Authorizations

Authorization
string
header
required

Server-side SDK clients use a project API key. Remote MCP clients use an OAuth access token. Never expose a project API key in browser code.

Headers

X-Request-Id
string

Optional caller-supplied correlation ID, up to 128 characters. The service returns the effective value in the response header for tracing and support.

Required string length: 1 - 128
X-Viggle-Source
string

Optional source-channel label, up to 128 characters, used to attribute traffic to an SDK, integration, product surface, or internal workflow.

Required string length: 1 - 128

Path Parameters

image_id
string
required

Public image job ID (img_ prefix) returned by POST /v1/images. It must have been created with the calling API key.

Minimum string length: 1

Response

Current image generation state.

An image generation job (img_ prefix), returned by both POST /v1/images and GET /v1/images/{image_id}. It only moves forward — queued → processing → ready or failed — and is never cancelled. images stays empty until the job is ready, then lists every generated image in request order. A job either produces all n images or fails; it never returns a partial set.

id
string
required

Public image job ID, img_ prefix.

Minimum string length: 1
status
enum<string>
required

Lifecycle state. ready and failed are terminal.

Available options:
queued,
processing,
ready,
failed
model
string
required

Model used for generation; currently always qwen.

progress
integer | null
required

Share of the requested images generated so far — 0 while queued, 0–99 while processing, 100 when ready, null when failed.

Required range: 0 <= x <= 100
images
object[]
required

Empty until ready, then all n generated images in request order.

created_at
string<date-time> | null
required

Creation timestamp, RFC 3339.

completed_at
string<date-time> | null
required

Terminal-state timestamp; set once the job is ready or failed, null before that.

error
object | null
required

Failure details, only when status is failed; otherwise null. code is SERVICE_BUSY (retryable — the generation service is busy or unavailable, or the job did not finish within 15 minutes), TASK_FAILED (retryable — any other generation or upload failure), or INVALID_REQUEST (not retryable — the model rejected the request, for example an unusable reference image).