Generate an image
const url = 'https://api.katara.com/v1/images/generations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"model":"katara/cortex","prompt":"A watercolor koi pond at dawn","aspect_ratio":"16:9"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.katara.com/v1/images/generations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "katara/cortex", "prompt": "A watercolor koi pond at dawn", "aspect_ratio": "16:9" }'The OpenAI image generation request. One image per request, returned as base64. Any model
name is served by Katara Cortex, which makes the picture with the main image model (priced by
image_size: 0.05112 at 1K, 0.07128 at 2K, 0.1464 at 4K) and, when it cannot,
a lower-cost image model (0.018 USDC or credits). A USDC key is charged that price, a credits key the credit price, and without a
key the x402 quote is exactly that price. Nothing is charged unless the image comes back. Images
never reach Katara Community. Images describes the fields.
Authorizations
Section titled “Authorizations”- bearerAuth
- None
Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Without a key, base64 of the x402 payment payload that signs the quote from a previous 402.
The same payload under the header name of the first x402 version, paid with exact.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Any name; Katara Cortex serves every image request.
What to draw.
WIDTHxHEIGHT, each side 1024 to 2048 and a multiple of 32, at most 4,194,304 pixels; or auto for the default. For a model priced by size, the closest listed shape within 3% at the smallest size with at least that many pixels. Not sent with image_size or aspect_ratio.
For a model priced by size. Defaults to the model’s default_image_size.
For a model priced by size.
hd (about 20 seconds) or standard (5 to 10 seconds); high and auto mean hd, medium and low mean standard.
One image per request.
Accepted and not passed on.
Example
{ "model": "katara/cortex", "prompt": "A watercolor koi pond at dawn", "aspect_ratio": "16:9"}Responses
Section titled “Responses”The image.
object
object
The image, base64-encoded.
object
The images charged for.
object
What this reply cost.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).
The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.
On a request paid with x402, the payment that settles the reply.
object
The token paid.
The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.
The provider’s address, or managed when a vendor answered.
Prompt tokens the vendor read from its cache, billed at the cached input rate.
What the cached tokens saved against the input rate, in USDC.
The same saving in Credits, on a reply paid with account credits.
When katara.compaction summarised the conversation.
object
The system message to send in place of the summarised messages.
object
First index in this request’s messages that the summary replaces.
First index kept after it.
The summary request’s usage and its cost (cost_usdc or cost_usd).
object
Why no summary was made; the request went whole.
object
Tokens this request wrote to a new explicit cache (katara.cache).
How long that cache is kept.
What keeping it costs, in USDC; included in cost_usdc.
On Test, a reply with fixed text that no model wrote, served when no Test provider was free.
The stop sequence at which Katara ended the reply.
The searches this request was charged for.
object
The successful searches; only those are charged, and none when the request ended without an answer.
On a web search request, how many model calls it made.
Every search the model made, in order. Not on stream chunks, which carry each search as it runs.
object
object
On an image reply from a model that edits, the id to send as previous_edit_id.
What this reply cost.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).
The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.
On a request paid with x402, the payment that settles the reply.
object
The token paid.
The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.
The provider’s address, or managed when a vendor answered.
Prompt tokens the vendor read from its cache, billed at the cached input rate.
What the cached tokens saved against the input rate, in USDC.
The same saving in Credits, on a reply paid with account credits.
When katara.compaction summarised the conversation.
object
The system message to send in place of the summarised messages.
object
First index in this request’s messages that the summary replaces.
First index kept after it.
The summary request’s usage and its cost (cost_usdc or cost_usd).
object
Why no summary was made; the request went whole.
object
Tokens this request wrote to a new explicit cache (katara.cache).
How long that cache is kept.
What keeping it costs, in USDC; included in cost_usdc.
On Test, a reply with fixed text that no model wrote, served when no Test provider was free.
The stop sequence at which Katara ended the reply.
The searches this request was charged for.
object
The successful searches; only those are charged, and none when the request ended without an answer.
On a web search request, how many model calls it made.
Every search the model made, in order. Not on stream chunks, which carry each search as it runs.
object
object
On an image reply from a model that edits, the id to send as previous_edit_id.
From a model that edits: send as previous_edit_id to keep editing this picture.
Example
{ "output_format": "png", "katara": { "cost_usdc": "0.000018", "cost_usd": "0.000018", "billing_method": "credits", "payment": { "scheme": "upto", "network": "eip155:43114", "amount": "25000" }, "web_searches": [ { "error": "invalid_input" } ] }}Headers
Section titled “Headers”On a call paid with x402, as for chat completions; amount is the charge.
A field the route does not take (unsupported_parameter, with param), a malformed request (invalid_request), a prompt the model refused (image_refused), an expired previous_edit_id (edit_expired), or a credits key and a model its credits cannot pay for (model_requires_usdc).
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Unknown key (invalid_api_key).
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Without a key, a quote (with PAYMENT-REQUIRED) or a payment that does not verify (payment_invalid); with a credits key, insufficient_credits; with a USDC key whose balance cannot cover the call, insufficient_quota.
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
An x402 quote for one request.
object
The ways this request can be paid, for the same maximum. upto entries, where offered, come before exact. Sign one.
object
upto: a Permit2 transfer of at most amount, of which only the charge is pulled. exact: an EIP-3009 transfer of amount, with the difference refunded. Neither collects more than was signed.
The chain as a CAIP-2 id.
The USDC contract the authorization is for.
The most this request can cost, in the token’s base units. At least the model’s minimum: 25000 (0.025 USDC), 50000 for katara/cortex-genius, 10000 for katara/cortex-smart.
The settlement contract; the authorization’s to.
Validity to give the authorization.
object
The token’s EIP-712 domain name.
The token’s EIP-712 domain version.
exact only. The job this quote is bound to. It may be signed as the authorization nonce; a random nonce also works.
The job this quote is bound to.
upto only.
upto only. The address that settles; the signed witness names it.
The address paid for the reply.
The model paid for: katara/cortex-genius or katara/cortex-smart when the request named one, otherwise katara/cortex for a chat, Messages, Responses or image request; the embedding model for embeddings.
katara/cortex for a chat, Messages, Responses or image request, whatever it named; the embedding model for embeddings.
True when a vendor’s model will answer.
eip2612GasSponsoring, when present: the token takes EIP-2612 permits, and a permit for
Permit2 sent with an upto payment is submitted with the settlement at Katara’s cost.
object
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Headers
Section titled “Headers”Base64 of the PaymentRequired object in the body. Present only on a quote.
Too many unpaid quotes from one address (quote_rate_limited).
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Headers
Section titled “Headers”The image provider failed (provider_failed, with Retry-After) or could not take the request Katara built (provider_rejected_request). Nothing was charged.
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}The model cannot be served right now (no_capacity). Retry after Retry-After.
object
object
For people. Wording may change.
Stable. Branch on this. Errors says what each code means and what to do; new codes may be added.
The response’s x-katara-request-id.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}