Skip to main content
POST
/
v1
/
images
Create a new image generation
curl --request POST \
  --url https://api.aurous-labs.com/v1/images \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "prompt": "A golden sunset over mountains, cinematic lighting, 8k resolution",
  "negative_prompt": "blurry, low quality, watermark, text",
  "lora_id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "character_id": "char_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "width": 2048,
  "height": 2048,
  "steps": 30,
  "guidance_scale": 7.5,
  "cfg_rescale": 0.7,
  "denoise_strength": 0.6,
  "seed": 42,
  "size": "2k_1_1",
  "count": 1,
  "enhance_prompt": false,
  "webhook_url": "https://your-server.com/webhooks/aurouslabs",
  "reference_image_urls": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/ref2.jpg"
  ]
}
'
{
  "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"
}
POST /v1/images submits an image generation request. Credits are deducted immediately from your team balance; the generation is processed asynchronously. Poll GET /v1/images/{id} for status, or pass webhook_url for a push callback when the generation completes or fails. For a step-by-step walkthrough, see the Quickstart. The full request shape, including all generation parameters, is in the playground below.

​
Using a LoRA

Pick a LoRA via GET /v1/loras and pass its id (opaque lora_* or slug) as lora_id. Or omit lora_id and the platform’s dispatcher picks a style based on your prompt. If no clear match exists, the prompt is generated without a style.

​
Using a character

When character_id is set, the platform attaches the character’s saved reference images to the generation as visual anchors for identity consistency. The dispatch path is image-to-image, so denoise_strength becomes effective and influences how closely the output follows the refs vs the prompt. The character must be in status: ready. Use a synthesizing / reviewing / failed character, or a soft-deleted one, and the request returns 400 character_not_ready.
character_id and reference_image_urls are mutually exclusive. Sending both returns 400 mutually_exclusive_input. Pick one path per generation.
cURL
curl -X POST https://api.aurous-labs.com/v1/images \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "Aurora at golden hour on a windswept cliff, cinematic",
    "character_id": "char_01HXMQ7Z3K8Y2ABCDEFGHJKM",
    "size": "2k_2_3"
  }'
If the character has multiple ref poses, the dispatcher consumes all of them as anchors. There is no current way to limit attachment to a subset of poses — the whole ref set goes in.

​
Size

Specify image dimensions one of two ways — never both: Named preset via size:
TierAvailable aspect ratios
2k1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9
4k1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9
Combine into a preset string in <tier>_<ratio> form, e.g. 2k_16_9, 4k_1_1, 2k_2_3. Custom dimensions via width and height:
  • Both required when used.
  • Range [1024, 4096] per side.
  • Snapped server-side to the nearest multiple of 32 — the response width/height reflect the post-snap value.
Sending both size and width/height returns 400 parameter_invalid_combination. Sending only one of width/height returns 400 missing_field.

​
Idempotency

Pass Idempotency-Key (any opaque value, 1–256 chars; UUID v4 recommended). Same key + same body within 24h replays the cached response with Aurous-Idempotent-Replayed: true. Same key + different body returns 409 idempotency_key_in_use. The 24h window and 1–256 char bound are documented in Idempotency.

​
Webhooks

Provide webhook_url to receive a POST callback when the generation reaches a terminal state. The payload is { event: "image.completed" | "image.failed", data: {...} } where data matches the GET /v1/images/{id} response. See Webhooks for signature verification.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Idempotency-Key
string

Stripe-style idempotency key (1-256 chars). Same key + same canonical-JSON body returns the cached response with Aurous-Idempotent-Replayed: true. Same key + different body returns 409 invalid_request / idempotency_key_in_use. UUID v4 recommended. Replay window is 24 hours. Absent header is treated as non-idempotent (each call processes anew).

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

Body

application/json
​
prompt
string
required

The text prompt describing the image to generate. 1-4000 characters; whitespace-only is rejected.

Required string length: 1 - 4000
Example:

"A golden sunset over mountains, cinematic lighting, 8k resolution"

​
negative_prompt
string

Negative prompt - elements to exclude from the generated image. 1-4000 characters.

Required string length: 1 - 4000
Example:

"blurry, low quality, watermark, text"

​
lora_id
string

Optional. Opaque LoRA identifier (lora_*) or URL-friendly slug, from GET /v1/loras. UUIDs are also accepted for legacy back-compat. If omitted, the platform will choose a suitable style based on your prompt; if none matches, your prompt is generated without a style.

Example:

"lora_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
character_id
string

Optional character ID (char_<ulid> from POST /v1/characters; UUID also accepted for legacy back-compat). When set, the character's reference images are sent to the model as visual anchors for identity consistency. The character must be in status: ready — referencing a synthesizing / reviewing / failed character returns 400 character_not_ready. Cross-team character_ids return 404 (existence is never leaked). Mutually exclusive with reference_image_urls: sending both returns 400 mutually_exclusive_input.

Example:

"char_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
width
number

Custom output image width in pixels. Use with height OR use size (preset), not both. Range [1024, 4096]; snapped server-side to the nearest multiple of 32. Sending both size and custom dimensions returns 400 with code parameter_invalid_combination. Sending only one of width/height returns 400 with code missing_field.

Required range: 1024 <= x <= 4096
Example:

2048

​
height
number

Custom output image height in pixels. Use with width OR use size (preset), not both. Range [1024, 4096]; snapped server-side to the nearest multiple of 32. Sending both size and custom dimensions returns 400 with code parameter_invalid_combination. Sending only one of width/height returns 400 with code missing_field.

Required range: 1024 <= x <= 4096
Example:

2048

​
steps
number

Number of diffusion steps (higher = more detail, slower). If omitted, resolves to the default for the selected style, then a platform default of 11. An explicit value always takes precedence.

Required range: 1 <= x <= 100
Example:

30

​
guidance_scale
number

Guidance scale - how closely to follow the prompt (higher = more literal). If omitted, resolves to the default for the selected style, then a platform default of 4.3. An explicit value always takes precedence.

Required range: 0.1 <= x <= 30
Example:

7.5

​
cfg_rescale
number

CFG rescale factor — dampens classifier-free guidance to reduce burn/oversaturation at high guidance_scale values. Range 0.0-1.0. If omitted, resolves to the default for the selected style, then a platform default of 0.7. Applies to every image generation regardless of references. An explicit value always takes precedence.

Required range: 0 <= x <= 1
Example:

0.7

​
denoise_strength
number

Denoising strength applied when reference images or a character are attached. Range 0.0-1.0. If omitted on a request that has references, resolves to the style or character consistency default, then a platform default of 0.6. Ignored (and never defaulted) on bare text-to-image requests with no references. An explicit value always takes precedence.

Required range: 0 <= x <= 1
Example:

0.6

​
seed
number

Random seed for reproducible generations. Omit to let the model pick a random seed — the concrete value it used is returned as seed on the succeeded generation, so you can pass that value back here to reproduce the result.

Example:

42

​
size
enum<string>

Image size as a named preset. Use this OR custom width/height, not both. Format is <tier>_<ratio> where tier is 2k or 4k and ratio matches the supported aspect-ratio set. Sending both size and custom dimensions returns 400 with code parameter_invalid_combination.

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"

​
count
number

Number of images to generate in this request

Required range: 1 <= x <= 4
Example:

1

​
enhance_prompt
boolean

When true, an LLM rewrites your prompt before generation using the LoRA's style template. This is the only customer-facing prompt-shaping toggle in the public API. Pricing: enhanced generations cost a configurable multiplier of the base rate.

Example:

false

​
webhook_url
string

Optional webhook URL. When provided, a POST request will be sent to this URL when the generation completes or fails. The payload contains an event field ("image.completed" or "image.failed") and a data field with the generation details (same shape as GET /v1/images/:id). Delivery is attempted up to 3 times with a 2-second delay between retries.

Example:

"https://your-server.com/webhooks/aurouslabs"

​
reference_image_urls
string[]

Up to 6 reference images. Each entry can be either:

  • an opaque file ID file_<ulid> returned by POST /v1/files, or
  • an https:// URL pointing at a public host (max 2048 chars). URLs are server-side fetched through an SSRF-pinned client (rejects private IPs / loopback / link-local / cloud metadata) and materialized as a 24h-TTL file under your team. Pricing matches the reference-image rate (see Pricing). Empty array or omitted is treated as "no references". Mutually exclusive with character_id — sending both returns 400 mutually_exclusive_input.
Maximum array length: 6
Example:
[
  "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "https://example.com/ref2.jpg"
]

Response

Generation created and pending processing

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

​
id
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.

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.

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