Retrieve an image - Aurous Labs

Get a single generation by ID

curl --request GET \
  --url https://api.aurous-labs.com/v1/images/{id} \
  --header 'X-Api-Key: <api-key>'

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden sunset over mountains, cinematic lighting",
  "created_at": "2026-05-04T10:00:00Z",
  "media_type": "image",
  "negative_prompt": "blurry, low quality",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0"
  ],
  "output_video_url": "https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2ABCDEFGHJKM/output?token=...",
  "reference_image_urls": [
    "https://example.com/ref1.jpg"
  ],
  "error_message": "Content policy violation",
  "duration_ms": 14820,
  "cost": {
    "amount": 2,
    "currency": "credit",
    "breakdown": {
      "base": 1,
      "enhance": 1
    }
  },
  "width": 2048,
  "height": 2048,
  "image_count": 1,
  "size_preset": "2k_1_1",
  "inference_type": "t2i",
  "cfg_rescale": 0.7,
  "denoise_strength": 0.6,
  "seed": 819572108,
  "video_duration": 5,
  "video_resolution": "480p",
  "video_ratio": "16:9",
  "video_camera_fixed": {},
  "character_id": "char_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "loras": [
    {
      "id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
      "name": "Sunset Style"
    }
  ],
  "aurous_version": "2026-05-15",
  "creation_request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "completed_at": "2026-05-04T10:00:14Z"
}

GET

images

{id}

Get a single generation by ID

curl --request GET \
  --url https://api.aurous-labs.com/v1/images/{id} \
  --header 'X-Api-Key: <api-key>'

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden sunset over mountains, cinematic lighting",
  "created_at": "2026-05-04T10:00:00Z",
  "media_type": "image",
  "negative_prompt": "blurry, low quality",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0"
  ],
  "output_video_url": "https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2ABCDEFGHJKM/output?token=...",
  "reference_image_urls": [
    "https://example.com/ref1.jpg"
  ],
  "error_message": "Content policy violation",
  "duration_ms": 14820,
  "cost": {
    "amount": 2,
    "currency": "credit",
    "breakdown": {
      "base": 1,
      "enhance": 1
    }
  },
  "width": 2048,
  "height": 2048,
  "image_count": 1,
  "size_preset": "2k_1_1",
  "inference_type": "t2i",
  "cfg_rescale": 0.7,
  "denoise_strength": 0.6,
  "seed": 819572108,
  "video_duration": 5,
  "video_resolution": "480p",
  "video_ratio": "16:9",
  "video_camera_fixed": {},
  "character_id": "char_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "loras": [
    {
      "id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
      "name": "Sunset Style"
    }
  ],
  "aurous_version": "2026-05-15",
  "creation_request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "completed_at": "2026-05-04T10:00:14Z"
}

GET /v1/images/{id} returns the current state of a generation. Poll it to track async progress until status reaches a terminal value: succeeded, failed, cancelled, expired, or moderation_rejected. The same endpoint serves both image generations (img_*) and video generations (vid_*) — they share a status surface. See the Videos overview for the polling pattern.

Reading the `loras` array

The loras field reports the styles applied to this generation. Each entry is a { id, name } pair where id is the opaque LoRA ID resolved at dispatch time. The array is null for prompt-only generations (no LoRA picked) and for pure-reference generations. When you dispatch with a “bundle” style (a multi-style stack the dashboard exposes as a single pick), the loras array carries one entry — the bundle, surfaced as a LoRA. The V1 surface presents bundles and single LoRAs uniformly: one entry, one ID, one name.

Output URLs

output_urls is populated when status === "succeeded". Each URL is a signed proxy URL on api.aurous-labs.com:

No X-Api-Key header needed — the signature is in the query string.
URLs expire ~7 days after generation (410 Gone with code: output_expired after that). If the generation reached a terminal status without producing output (failed, cancelled, moderation_rejected, polling-timeout expired), the proxy returns 422 Unprocessable Entity with code: output_not_available instead.
Save what you want to keep — long-term storage is intentionally not part of the platform.

For video generations, output_video_url is the polled URL; output_urls may or may not be populated depending on the video flow used.

Polling cadence

Most image generations finish in 10–30 seconds. Poll on a 2-second interval with light exponential backoff. Tighter polling burns rate-limit budget without finishing your generation any faster — see Rate limits.

cURL

curl https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM \
  -H "X-Api-Key: $AUROUS_API_KEY"

Cost on the response

Once status is terminal, cost.amount reports the credits actually charged. For pending and processing generations, cost.amount reports the held amount — the upper bound that will be deducted on success. Cancelled generations refund any held credits.

Authorizations

X-Api-Key

string

header

required

Your team API key (starts with al_live_).

Headers

Aurous-Version

string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-05-15"

Path Parameters

string

required

Opaque generation ID (img_* for image, vid_* for video)

Example:

"img_01HXMQ7Z3K8Y2ABCDEFGHJKM"

Response

Generation details

object

enum<string>

default:inference

required

Discriminator — always inference. Mirrors OpenAI's object-field convention so SDK clients can branch on the resource type without inspecting the ID prefix. A single canonical value (inference) covers both image and video generations; use media_type to distinguish the rendering kind.

Available options:

inference

Example:

"inference"

string

required

Opaque generation ID

Example:

"img_01HXMQ7Z3K8Y2ABCDEFGHJKM"

status

enum<string>

required

Current generation status. Lifecycle: pending (created, awaiting dispatch) → processing (running) → one of the terminal values succeeded / failed / cancelled. Additional terminal values may be introduced in future API versions and will be announced via the changelog before they appear on the wire.

Available options:

pending,

processing,

succeeded,

failed,

cancelled

Example:

"succeeded"

prompt

string

required

The text prompt used for generation

Example:

"A golden sunset over mountains, cinematic lighting"

created_at

string

required

Creation timestamp (ISO 8601)

Example:

"2026-05-04T10:00:00Z"

media_type

enum<string> | null

Distinguishes image vs video generation. May be null for older rows minted before this column existed.

Available options:

image,

video

Example:

"image"

negative_prompt

object

Negative prompt to exclude from generation

Example:

"blurry, low quality"

output_urls

string[] | null

Generated image proxy URLs. Each URL is anonymous-read (no auth header required) and edge-cached for 24 hours. Available for ~24 hours after generation. Save what you want to keep — long-term storage is intentionally not part of the platform. URLs return 410 Gone after expiry.

Example:

[
  "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0"
]

output_video_url

object

Generated video proxy URL (only present on media_type: video). Same 24h TTL as image output_urls.

Example:

"https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2ABCDEFGHJKM/output?token=..."

reference_image_urls

string[] | null

Reference image URLs that were used as visual anchors for this generation, if any. Snapshotted at inference time — for character-attached generations, these are the resolved character refs at submission, not the live character state.

Example:

["https://example.com/ref1.jpg"]

error_message

object

Error message if the generation failed

Example:

"Content policy violation"

duration_ms

object

Processing duration in milliseconds (set on terminal status)

Example:

14820

cost

object

Per-generation cost breakdown — same shape as the estimated_cost returned by POST /v1/{images,videos}/estimate. May be null for older rows from before this field existed; populated for all new generations. The amount reflects the committed charge for terminal-status rows.

Show child attributes

Example:

{
  "amount": 2,
  "currency": "credit",
  "breakdown": { "base": 1, "enhance": 1 }
}

width

number

Resolved output image width in pixels (image generations only). Reflects the post-snap dimension actually generated; may differ from a custom-requested width by up to 31 px due to multiple-of-32 snapping.

Example:

2048

height

number

Resolved output image height in pixels (image generations only). Reflects the post-snap dimension actually generated; may differ from a custom-requested height by up to 31 px due to multiple-of-32 snapping.

Example:

2048

image_count

number

Number of images requested in the batch

Example:

1

size_preset

enum<string> | null

Named size preset applied to this generation. null when the request used custom width/height instead of a preset.

Available options:

2k_1_1,

2k_3_2,

2k_2_3,

2k_4_3,

2k_3_4,

2k_16_9,

2k_9_16,

2k_21_9,

4k_1_1,

4k_3_2,

4k_2_3,

4k_4_3,

4k_3_4,

4k_16_9,

4k_9_16,

4k_21_9

Example:

"2k_1_1"

inference_type

enum<string> | null

Inference mode dispatched. t2i (text-to-image) for every current image generation — reference images and characters are supplementary inputs to the t2i flow, not a separate mode. i2i is reserved for a future image-edit endpoint.

Available options:

t2i,

i2i

Example:

"t2i"

cfg_rescale

object

CFG rescale factor the customer supplied on the request body, echoed back here. Range 0.0-1.0. Omitted when the customer did not supply a per-request value (the platform applied a precedence-chain default — LoRA, character override, or the global 0.7 — which is not exposed on the response).

Example:

0.7

denoise_strength

object

Denoising strength the customer supplied on the request body, echoed back here. Range 0.0-1.0. Omitted when the customer did not supply a value or when the generation was a bare text-to-image request (denoise is only applied when reference images or a character are attached).

Example:

0.6

seed

integer | null

The random seed the model actually used for this image generation. Populated even when you omit seed on the request — the platform requests a random seed and records the concrete value the provider rolled, so you can reproduce the result by passing it back as seed. Available once status is succeeded; null before then and for failed/cancelled generations. For multi-image batches (image_count > 1) this is the seed of the first image (output_urls[0]); per-image seeds are not yet exposed. Image generations only.

Example:

819572108

video_duration

object

Video duration in seconds (video generations only)

Example:

5

video_resolution

enum<string> | null

Video resolution (video generations only)

Available options:

480p,

720p,

1080p

Example:

"480p"

video_ratio

enum<string> | null

Video aspect ratio (video generations only)

Available options:

16:9,

4:3,

1:1,

3:4,

9:16,

21:9

Example:

"16:9"

video_camera_fixed

object

Whether the camera was held fixed during the video

character_id

object

Character ID supplied on the request (char_<ulid> or legacy UUID), echoed back. null when no character was attached to this generation.

Example:

"char_01HXMQ7Z3K8Y2ABCDEFGHJKM"

loras

object[] | null

LoRAs applied to this generation. null for prompt-only and pure-reference generations.

Show child attributes

aurous_version

string

API contract version applied at the time this row was minted (D25 — frozen for replay across future version bumps).

Example:

"2026-05-15"

creation_request_id

string

Aurous-Request-Id of the POST that created this row. Quote in support tickets to trace the original create request.

Example:

"req_01HXMQ7Z3K8Y2ABCDEFGHJKM"

completed_at

object

Terminal-status timestamp (ISO 8601). NULL until the generation reaches a terminal state.

Example:

"2026-05-04T10:00:14Z"

List your generation history Cancel a pending or processing generation

​Reading the loras array

​Output URLs

​Polling cadence

​Cost on the response

Authorizations

Headers

Path Parameters

Response

Reading the `loras` array

Output URLs

Polling cadence

Cost on the response