Retrieve an image

Get a single generation by ID

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

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.aurous-labs.com/v1/images/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/images/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/images/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/images/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden sunset over mountains, cinematic lighting",
  "created_at": "2026-05-04T10:00:00Z",
  "media_type": "image",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output/0"
  ],
  "video_url": "https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output?token=...",
  "reference_image_urls": [
    "https://example.com/ref1.jpg"
  ],
  "error_message": "Content policy violation",
  "error_code": "generation_interrupted",
  "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_generate_audio": true,
  "video_task": "reference",
  "extend_direction": "forward",
  "reference_video_url": "https://cdn.example.com/clips/dance-loop.mp4",
  "reference_audio_url": "https://cdn.example.com/audio/voiceover.mp3",
  "video_lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "video_lora_name": "Cinematic Pan",
  "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "subjects": [
    {
      "type": "character",
      "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "image_count": 1
    },
    {
      "type": "reference",
      "character_id": null,
      "image_count": 2
    }
  ],
  "context_images": {
    "image_count": 3
  },
  "action": {
    "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "name": "Over-the-shoulder"
  },
  "style": {
    "id": "lora_06AAAAAAAAAAAAAAAAAAAAAAAA",
    "name": "Ring-Light Creator"
  },
  "warnings": [
    {
      "code": "style_retired_plain",
      "param": "lora_id",
      "message": "Style lora_06AAAAAAAAAAAAAAAAAAAAAAAA is retired and no longer applies a style — this request generates without one."
    }
  ],
  "enhancer_outcome": "succeeded",
  "loras": [
    {
      "id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "name": "Sunset Style"
    }
  ],
  "aurous_version": "2026-07-16",
  "creation_request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "completed_at": "2026-05-04T10:00:14Z"
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

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>'

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.aurous-labs.com/v1/images/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/images/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/images/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/images/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden sunset over mountains, cinematic lighting",
  "created_at": "2026-05-04T10:00:00Z",
  "media_type": "image",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output/0"
  ],
  "video_url": "https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output?token=...",
  "reference_image_urls": [
    "https://example.com/ref1.jpg"
  ],
  "error_message": "Content policy violation",
  "error_code": "generation_interrupted",
  "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_generate_audio": true,
  "video_task": "reference",
  "extend_direction": "forward",
  "reference_video_url": "https://cdn.example.com/clips/dance-loop.mp4",
  "reference_audio_url": "https://cdn.example.com/audio/voiceover.mp3",
  "video_lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "video_lora_name": "Cinematic Pan",
  "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "subjects": [
    {
      "type": "character",
      "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "image_count": 1
    },
    {
      "type": "reference",
      "character_id": null,
      "image_count": 2
    }
  ],
  "context_images": {
    "image_count": 3
  },
  "action": {
    "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "name": "Over-the-shoulder"
  },
  "style": {
    "id": "lora_06AAAAAAAAAAAAAAAAAAAAAAAA",
    "name": "Ring-Light Creator"
  },
  "warnings": [
    {
      "code": "style_retired_plain",
      "param": "lora_id",
      "message": "Style lora_06AAAAAAAAAAAAAAAAAAAAAAAA is retired and no longer applies a style — this request generates without one."
    }
  ],
  "enhancer_outcome": "succeeded",
  "loras": [
    {
      "id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "name": "Sunset Style"
    }
  ],
  "aurous_version": "2026-07-16",
  "creation_request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "completed_at": "2026-05-04T10:00:14Z"
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

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, video_url is the polled URL, not output_urls — see Create a video.

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM \
  -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. A failed generation settles at cost.amount: 0 with cost.refunded: true — the reserved hold was released, never charged. refunded is only ever present on failed rows; it’s omitted on succeeded, pending, and processing generations.

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-07-16 for unauthenticated requests.

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

Example:

"2026-07-16"

Path Parameters

string

required

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

Example:

"img_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

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"

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output/0"
]

video_url

string | null

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM/output?token=..."

reference_image_urls

string[] | null

The reference image URLs you supplied as visual anchors for this generation, echoed back (snapshotted at inference time). Present only when the generation was driven by your own reference images (reference_image_urls or reference subjects). Omitted entirely for character-driven generations — a character's reference images are managed platform assets and are never echoed.

Example:

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

error_message

string | null

Human-readable error message if the generation failed. Non-contractual prose — do not parse or match on this value. Switch on error_code instead.

Example:

"Content policy violation"

error_code

string | null

Machine-readable failure reason when status is failed, for the cases where you need to branch in code. null on every successful generation, on failures recorded before this field existed, and on failure paths that have no stable code — error_message is human-facing copy that is re-tuned over time, so never pattern-match it. Currently emitted: generation_interrupted, reference_preparation_failed, content_filtered, generation_failed, and first_frame_too_small (an https:// first_frame_url attached to a video model whose dimensions were below the minimum — a file_<ulid> frame is rejected with the same code as a 400 before any credits are held; see Errors). The set is additive: new codes may appear, so treat an unrecognized value as a generic failure, keep a default branch in your switch statement, and fall back to error_message.

Example:

"generation_interrupted"

duration_ms

integer | null

Processing duration in milliseconds (set on terminal status)

Example:

14820

cost

object | null

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 — 0 (with refunded: true) on a failed generation, since the reserved hold was released, never charged.

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 in the batch. Reflects the requested count while the generation is running; on a terminal status it reflects the number actually DELIVERED — when part of a batch fails you receive the successful images, this count re-stamps to match, and the difference is refunded automatically.

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. Images: t2i (text-to-image) — reference images and characters are supplementary inputs to the t2i flow, not a separate mode. Videos (this list also returns vid_* rows): t2v (text-to-video), i2v (image-to-video — frame-driven, subject-driven, or a pinned video model on its own), or r2v (reference mode — the generation was driven by a motion reference). r2v does NOT imply you supplied that reference: it covers BOTH your own clip sent as reference_video_url AND a platform-built reference, produced when a first frame rides with a video model (pinned via video_lora_id, or auto-matched from the image). On the platform-built variant reference_video_url is null — branch on that field, not on inference_type, to tell the two apart. i2i is reserved for a future image-edit endpoint and is not currently emitted.

Available options:

t2i,

t2v,

i2v,

r2v,

i2i

Example:

"t2i"

cfg_rescale

number | null

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

Required range: 0 <= x <= 1

Example:

0.7

denoise_strength

number | null

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

Required range: 0 <= x <= 1

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

integer | null

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,

adaptive

Example:

"16:9"

video_generate_audio

boolean | null

Whether the generated video includes synchronized audio (video generations only). Echoes the request generate_audio (default true).

Example:

true

video_task

enum<string> | null

Resolved reference-video task (video generations only). reference: the generation borrows the clip's motion for a new scene. extend: the generation continues the clip itself. null on every generation that did not supply reference_video_url (including all pre-existing rows). Additional task types may be introduced in future API versions — treat an unrecognized value as opaque.

Available options:

reference,

extend

Example:

"reference"

extend_direction

enum<string> | null

Resolved extend direction (video generations only). Non-null only when video_task is extend; null otherwise (including every reference-mode and non-reference generation).

Available options:

forward,

backward

Example:

"forward"

reference_video_url

string | null

The reference video URL you submitted, echoed back VERBATIM as you sent it — never re-signed, never a storage path. null for generations that did not supply reference_video_url (including every dashboard-originated row, and including an inference_type: "r2v" generation whose motion reference the platform built from a first frame plus a pinned or matched video model — this field, not inference_type, is what distinguishes your own clip from a platform-built reference).

Example:

"https://cdn.example.com/clips/dance-loop.mp4"

reference_audio_url

string | null

The reference audio URL you submitted, echoed back VERBATIM as you sent it. null for generations that did not supply reference_audio_url.

Example:

"https://cdn.example.com/audio/voiceover.mp3"

video_lora_id

string | null

The video model (an id or slug from GET /v1/video_loras) behind this generation (video generations only) — either the video_lora_id you pinned on the request, or the model the platform auto-matched to your prompt when none was pinned. null for a plain (no video model) generation, and always null on image generations.

Example:

"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

video_lora_name

string | null

Display name of the video model in video_lora_id, if any. Omitted for plain generations (no pinned or matched video model).

Example:

"Cinematic Pan"

character_id

string | null

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

Example:

"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

subjects

object[] | null

Ordered subjects composed into this generation (positional — entry N echoes entry N of the identity inputs sent on create; legacy character_id / reference_image_urls inputs are normalized into the same projection). Character entries carry the opaque char_<ulid>; reference entries echo only their image count, never URLs. Video generations echo their cast the same way (up to 2 entries), matching the subjects[] array accepted by POST /v1/videos. Character entries on generations created before cast snapshotting may carry character_id: null; the id is never substituted with an internal identifier. null for generations that did not compose subjects (plain prompt-only or style generations, and context-image generations). The engine is not exposed.

Show child attributes

Example:

[
  {
    "type": "character",
    "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "image_count": 1
  },
  {
    "type": "reference",
    "character_id": null,
    "image_count": 2
  }
]

context_images

object | null

Count-only echo of the context_images[] sent on create — the number of loose reference images supplied, never the image URLs themselves. null for every generation that did not use context_images (plain prompt-only, style, subject, and video generations).

Show child attributes

Example:

{ "image_count": 3 }

action

object | null

The composition act applied to this generation, echoed as { id, name }. An act is applied either because you pinned it with action_id or because act detection matched one automatically. id is the act identifier from GET /v1/actions; name is its display name (or null when the name was not recorded). null for every generation that did not apply an act — plain prompt-only, style, context-image, and video generations. A new, always-present, nullable key: existing integrations that do not read it are unaffected.

Show child attributes

Example:

{
  "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
  "name": "Over-the-shoulder"
}

style

object | null

The prompt style applied to this generation, echoed as { id, name }. A style is applied either because you pinned it with lora_id or because style matching resolved one from your prompt — the echo always reflects the style that actually ran (a retired id that aliases to a successor echoes the successor). id is the lora_* identifier from GET /v1/loras and round-trips into lora_id. null for every generation without a style — including lora_id: null requests, retired styles that generate plain, video generations, and all rows minted before styles shipped. A new, always-present, nullable key: existing integrations that do not read it are unaffected.

Show child attributes

Example:

{
  "id": "lora_06AAAAAAAAAAAAAAAAAAAAAAAA",
  "name": "Ring-Light Creator"
}

warnings

object[]

Non-fatal request adjustments, present ONLY on the POST /v1/images 201 body (and the estimate response) — never on GET reads, list rows, or webhook payloads. Omitted entirely when empty. Current codes: parameter_ignored, style_retired_plain; new codes may be added without a version bump — ignore unknown codes. Idempotent replays return the original warnings verbatim.

Show child attributes

Example:

[
  {
    "code": "style_retired_plain",
    "param": "lora_id",
    "message": "Style lora_06AAAAAAAAAAAAAAAAAAAAAAAA is retired and no longer applies a style — this request generates without one."
  }
]

enhancer_outcome

string | null

Outcome of the prompt-optimization step, echoed for observability. Current values: no_request (the request did not invoke it), succeeded, identical, refused, transport_error, length_overflow; null on rows minted before this field existed. INFORMATIONAL and deliberately an OPEN set (no schema enum — codegen clients must not mint a closed union): do not branch control flow on it; new values may be added without a version bump.

Example:

"succeeded"

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-07-16"

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

completed_at

string | null

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

Example:

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

Get started

Guides

Concepts

API Reference

Resources

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

Authorizations

Headers

Path Parameters

Response

Reading the `loras` array

Output URLs

Polling cadence

Cost on the response