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",
  "lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "width": 2048,
  "height": 2048,
  "size": "2k_1_1",
  "count": 1,
  "enhance_prompt": false,
  "reference_image_urls": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/ref2.jpg"
  ],
  "subjects": [
    {
      "type": "character",
      "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "image_urls": [
        "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"
      ]
    }
  ],
  "context_images": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/outfit.jpg"
  ],
  "action_id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
  "output_format": "jpeg"
}
'

import requests

url = "https://api.aurous-labs.com/v1/images/estimate"

payload = {
    "prompt": "A golden sunset over mountains, cinematic lighting, 8k resolution",
    "lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "width": 2048,
    "height": 2048,
    "size": "2k_1_1",
    "count": 1,
    "enhance_prompt": False,
    "reference_image_urls": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN", "https://example.com/ref2.jpg"],
    "subjects": [
        {
            "type": "character",
            "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
            "image_urls": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"]
        }
    ],
    "context_images": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN", "https://example.com/outfit.jpg"],
    "action_id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "output_format": "jpeg"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: 'A golden sunset over mountains, cinematic lighting, 8k resolution',
    lora_id: 'lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    character_id: 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    width: 2048,
    height: 2048,
    size: '2k_1_1',
    count: 1,
    enhance_prompt: false,
    reference_image_urls: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN', 'https://example.com/ref2.jpg'],
    subjects: [
      {
        type: 'character',
        character_id: 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
        image_urls: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN']
      }
    ],
    context_images: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN', 'https://example.com/outfit.jpg'],
    action_id: '3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c',
    output_format: 'jpeg'
  })
};

fetch('https://api.aurous-labs.com/v1/images/estimate', 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/estimate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => 'A golden sunset over mountains, cinematic lighting, 8k resolution',
    'lora_id' => 'lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    'character_id' => 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    'width' => 2048,
    'height' => 2048,
    'size' => '2k_1_1',
    'count' => 1,
    'enhance_prompt' => false,
    'reference_image_urls' => [
        'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN',
        'https://example.com/ref2.jpg'
    ],
    'subjects' => [
        [
                'type' => 'character',
                'character_id' => 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
                'image_urls' => [
                                'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN'
                ]
        ]
    ],
    'context_images' => [
        'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN',
        'https://example.com/outfit.jpg'
    ],
    'action_id' => '3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c',
    'output_format' => 'jpeg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/images/estimate"

	payload := strings.NewReader("{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/images/estimate")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}"

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

{
  "object": "estimate",
  "estimated_cost": {
    "amount": 2,
    "breakdown": {
      "tokens_max": 108000,
      "enhance_flat_credits": 0.5
    },
    "adaptive": false,
    "amount_min": 10,
    "amount_max": 37.5
  },
  "currency": "credit",
  "warnings": [
    {
      "code": "parameter_ignored",
      "param": "seed",
      "message": "`seed` has no effect on this generation and was ignored."
    }
  ]
}

{
  "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"
  }
}

{
  "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"
  }
}

Images

Estimate the credit cost of an image generation

Same DTO as POST /v1/images. Returns the projected credit cost and a per-line-item breakdown (base + optional enhance) without enqueuing the work. Reference images are free and do not affect price. Inputs are validated with the same rules as the create path — a private style from another team, a retired style that no longer generates (400 style_retired), a foreign or not-ready character subject, an over-budget subjects[] all return the same error a real POST /v1/images would — with one difference: the estimate never fetches inline https reference URLs, so a problem specific to a URL (unreachable host, non-image content) only surfaces at create. count multiplies the quote on every request shape — plain, subjects[], and context_images alike: images generate in parallel and you are billed per image, with partial failures delivering fewer images and auto-refunding the difference, so estimate(count: 4) equals 4 × estimate(count: 1). The response carries the same warnings[] the real create would return — a retired style that generates without a style, or a parameter with no effect on the selected generation path — so you can surface them before spending credits. Isolated rate-limit bucket (estimate_post, 120/min) so pricing-check loops do not crowd out real generations. Reference images can be supplied via reference_image_urls (mutually exclusive with character_id) or as reference subjects. A context_images estimate fires the same 400 combination errors a real POST /v1/images would, and never fetches inline https entries (file IDs are still ownership-checked). When you pin an action_id, the estimate runs the identical composition-act gates as POST /v1/images — existence/visibility (an unknown or inaccessible act → 404 resource_not_found) and, when subjects are present, the subject-count check (an unsupported count → 400 action_not_available, whose message names the counts the act supports) — but never picks or signs a reference still. The same gates run when your lora_id is a composition-act id (it acts as the pin). Acts and styles do not change the price.

POST

images

estimate

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",
  "lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "width": 2048,
  "height": 2048,
  "size": "2k_1_1",
  "count": 1,
  "enhance_prompt": false,
  "reference_image_urls": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/ref2.jpg"
  ],
  "subjects": [
    {
      "type": "character",
      "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
      "image_urls": [
        "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"
      ]
    }
  ],
  "context_images": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/outfit.jpg"
  ],
  "action_id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
  "output_format": "jpeg"
}
'

import requests

url = "https://api.aurous-labs.com/v1/images/estimate"

payload = {
    "prompt": "A golden sunset over mountains, cinematic lighting, 8k resolution",
    "lora_id": "lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "width": 2048,
    "height": 2048,
    "size": "2k_1_1",
    "count": 1,
    "enhance_prompt": False,
    "reference_image_urls": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN", "https://example.com/ref2.jpg"],
    "subjects": [
        {
            "type": "character",
            "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
            "image_urls": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"]
        }
    ],
    "context_images": ["file_01HXMQ7Z3K8Y2NABCDEFGHJKMN", "https://example.com/outfit.jpg"],
    "action_id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "output_format": "jpeg"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: 'A golden sunset over mountains, cinematic lighting, 8k resolution',
    lora_id: 'lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    character_id: 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    width: 2048,
    height: 2048,
    size: '2k_1_1',
    count: 1,
    enhance_prompt: false,
    reference_image_urls: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN', 'https://example.com/ref2.jpg'],
    subjects: [
      {
        type: 'character',
        character_id: 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
        image_urls: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN']
      }
    ],
    context_images: ['file_01HXMQ7Z3K8Y2NABCDEFGHJKMN', 'https://example.com/outfit.jpg'],
    action_id: '3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c',
    output_format: 'jpeg'
  })
};

fetch('https://api.aurous-labs.com/v1/images/estimate', 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/estimate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => 'A golden sunset over mountains, cinematic lighting, 8k resolution',
    'lora_id' => 'lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    'character_id' => 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
    'width' => 2048,
    'height' => 2048,
    'size' => '2k_1_1',
    'count' => 1,
    'enhance_prompt' => false,
    'reference_image_urls' => [
        'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN',
        'https://example.com/ref2.jpg'
    ],
    'subjects' => [
        [
                'type' => 'character',
                'character_id' => 'char_01HXMQ7Z3K8Y2VNABCDEFGHJKM',
                'image_urls' => [
                                'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN'
                ]
        ]
    ],
    'context_images' => [
        'file_01HXMQ7Z3K8Y2NABCDEFGHJKMN',
        'https://example.com/outfit.jpg'
    ],
    'action_id' => '3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c',
    'output_format' => 'jpeg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/images/estimate"

	payload := strings.NewReader("{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/images/estimate")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"A golden sunset over mountains, cinematic lighting, 8k resolution\",\n  \"lora_id\": \"lora_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n  \"width\": 2048,\n  \"height\": 2048,\n  \"size\": \"2k_1_1\",\n  \"count\": 1,\n  \"enhance_prompt\": false,\n  \"reference_image_urls\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/ref2.jpg\"\n  ],\n  \"subjects\": [\n    {\n      \"type\": \"character\",\n      \"character_id\": \"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM\",\n      \"image_urls\": [\n        \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\"\n      ]\n    }\n  ],\n  \"context_images\": [\n    \"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN\",\n    \"https://example.com/outfit.jpg\"\n  ],\n  \"action_id\": \"3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c\",\n  \"output_format\": \"jpeg\"\n}"

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

{
  "object": "estimate",
  "estimated_cost": {
    "amount": 2,
    "breakdown": {
      "tokens_max": 108000,
      "enhance_flat_credits": 0.5
    },
    "adaptive": false,
    "amount_min": 10,
    "amount_max": 37.5
  },
  "currency": "credit",
  "warnings": [
    {
      "code": "parameter_ignored",
      "param": "seed",
      "message": "`seed` has no effect on this generation and was ignored."
    }
  ]
}

{
  "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"
  }
}

{
  "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"
  }
}

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"

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

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 (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, and the only one that changes the price: enhanced generations cost a configurable multiplier of the base rate. Styled generations (a pinned or auto-matched style) always shape the prompt around the style — that built-in pass is not the enhancer, never fails a request, and never bills the enhancer multiplier unless you set this flag yourself.

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:

[
  "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "https://example.com/ref2.jpg"
]

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

Show child attributes

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:

[
  "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "https://example.com/outfit.jpg"
]

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.

Show child attributes

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.

Show child attributes

Example:

[
  {
    "code": "parameter_ignored",
    "param": "seed",
    "message": "`seed` has no effect on this generation and was ignored."
  }
]

Get started

Guides

Concepts

API Reference

Resources

Estimate the credit cost of an image generation

Authorizations

Headers

Body

Response