Skip to main content
POST
/
v1
/
images
/
estimate
Estimate the credit cost of an image generation
curl --request POST \
  --url https://api.aurous-labs.com/v1/images/estimate \
  --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": "estimate",
  "estimated_cost": {
    "amount": 2,
    "breakdown": {
      "base": 1,
      "enhance": 1
    }
  },
  "currency": "credit"
}

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"

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

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"