Skip to main content
POST
Estimate the credit cost of an image generation

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). Omit the header to receive the platform default, currently 2026-08-26.

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

"2026-08-26"

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"

​
lora_id
string | null

Optional. Style identifier (lora_*) or slug, from GET /v1/loras. Tri-state: omit and matching runs automatically when your prompt names a look; send null to disable style matching for this request; send an id to pin that style. Styles now compose with action_id and subjects — a composition-act id in this field cannot be combined with a different action_id. Retired style ids keep working: aliased ids apply their successor style (echoed in response.style); other retired ids generate without a style and add a warnings[] entry.

Example:

"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

​
character_id
string
deprecated

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. The output follows your prompt. Superseded by subjects[]; fully supported — successful responses carry an advisory Deprecation: true header when this field is used.

Example:

"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

​
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. Output pixels (width × height) <= 2,360,000 bill the standard tier; above that, the large tier — see GET /v1/models for current per-tier pricing. 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:

1472

​
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. Output pixels (width × height) <= 2,360,000 bill the standard tier; above that, the large tier — see GET /v1/models for current per-tier pricing. 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:

1472

​
size
enum<string>

Image size as a named preset. Use this OR custom width/height, not both. Format is <tier>_<ratio> where tier is 1_5k, 2k, or 4k and ratio matches the supported aspect-ratio set. Defaults to 1_5k_1_1 (1472×1472, standard tier) when omitted. Output pixels (width × height) <= 2,360,000 bill the standard tier; above that, the large tier — see GET /v1/models for current per-tier pricing. Sending both size and custom dimensions returns 400 with code parameter_invalid_combination.

Available options:
1_5k_1_1,
1_5k_3_2,
1_5k_2_3,
1_5k_4_3,
1_5k_3_4,
1_5k_16_9,
1_5k_9_16,
1_5k_21_9,
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:

"1_5k_1_1"

​
count
number

Number of images to generate in this request (1-4, whole number). Images generate in parallel and you are billed per image; if some images in the batch fail, you receive the ones that succeeded and the difference is refunded automatically — the response image_count reflects the number actually delivered.

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

1

​
enhance_prompt
boolean

When true, an LLM rewrites your prompt before generation to a more detailed, model-friendly form; the rewritten prompt is what reaches the model. This is the only customer-facing prompt-shaping toggle in the public API. It is price-neutral on image generations: turning it on never adds a surcharge, cost.amount is unaffected, and breakdown carries no line item for it. Styled generations (a pinned or auto-matched style) always shape the prompt around the style through a separate, built-in pass — distinct from this flag, never fails a request, and — like this flag — never bills anything extra.

Example:

false

​
reference_image_urls
string[]
deprecated

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. Image files only — a file_<ulid> uploaded with purpose reference_video/reference_audio is rejected (400 invalid_format). 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. Superseded by subjects[]; fully supported — successful responses carry an advisory Deprecation: true header when this field is used.
Maximum array length: 6
Example:
​
subjects
object[]

Ordered subjects composed into one image (Image 1, Image 2, …). Max 10 subjects and 10 input images total. Mutually exclusive with character_id/reference_image_urls (both → 400 mutually_exclusive_input). Composes with lora_id when it names a style; the few styles that pick their own model still return 400 parameter_invalid_combination. Omit or [] for text-to-image/style.

Maximum array length: 10
​
context_images
string[]

Up to 10 loose reference images for multi-image composition, interpreted from your prompt — no identity grouping or per-subject framing is applied, and no identity consistency is guaranteed. Positions follow array order and can be addressed in the prompt as "Image 1" … "Image 10" (e.g. "the outfit in Image 3"). Each entry is a file_<ulid> ID from POST /v1/files or an https URL to a public host (max 2048 chars). Empty array or omitted is treated as "no context images". Mutually exclusive with subjects, character_id, and reference_image_urls (400 mutually_exclusive_input) and with lora_id (400 parameter_invalid_combination — multi-image composition picks its own model; styles cannot be stacked). The response echoes only a count (context_images: { image_count }), never the image URLs.

Maximum array length: 10
Example:
​
action_id
string | null

Pin a composition act from GET /v1/actions. Treat the id as opaque — it comes from the catalog and nowhere else. With subjects, the act must support your subject count (see supported_character_counts) — an unsupported count returns 400 action_not_available. Without subjects, the act renders with a new person described by your prompt. Omit to let act detection run automatically; send null to disable detection for this request. Combinable with lora_id when that id names a prompt style (the act and the style compose); a composition-act id sent in lora_id already acts as the pin, so it cannot be combined with a DIFFERENT action_id (400 parameter_invalid_combination). Mutually exclusive with context_images (400 mutually_exclusive_input). An id that is unknown or not visible to your team returns 404 resource_not_found — the same uniform 404 as GET /v1/actions/{id}.

Example:

"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c"

​
output_format
enum<string>

Output format. png yields a transparent background where the composition supports it. Default jpeg.

Available options:
jpeg,
png
Example:

"jpeg"

Response

Cost estimate

​
object
enum<string>
required

Discriminator

Available options:
estimate
Example:

"estimate"

​
estimated_cost
object
required

Cost breakdown for this would-be generation.

​
currency
enum<string>
required

Currency unit. All amounts in this response are in credit.

Available options:
credit
Example:

"credit"

​
warnings
object[]

Non-fatal request adjustments the real create would also report (e.g. a retired style pin that generates without a style, or a parameter with no effect on this generation path). Same shape and codes as the warnings on the POST /v1/images 201 body — the estimate warns exactly when the create would. Omitted when empty. Codes are an OPEN set: ignore unknown codes.

Example: