Generate an image

POST

/images/generations

const url = 'https://api.katara.com/v1/images/generations';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"katara/glm-image@1","prompt":"A watercolor koi pond at dawn","size":"1280x1280"}'
};

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/glm-image@1", "prompt": "A watercolor koi pond at dawn", "size": "1280x1280" }'

The OpenAI image generation request. One image per request from katara/glm-image@1, returned as base64. Every image has one price, listed in /v1/models as image_price: a USDC key is charged it, a credits key is charged the credit rate, 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

bearerAuth
None

Parameters

Header Parameters

PAYMENT-SIGNATURE

string

Without a key, base64 of the x402 payment payload that signs the quote from a previous 402.

X-PAYMENT

string

The same payload under the header name of the first x402 version, paid with exact.

Request Body^required

application/json

object

model

required

string

prompt

required

What to draw.

string

<= 4000 characters

size

WIDTHxHEIGHT, each side 1024 to 2048 and a multiple of 32, at most 4,194,304 pixels; or auto for the default.

string

default: 1280x1280

quality

hd (about 20 seconds) or standard (5 to 10 seconds); high and auto mean hd, medium and low mean standard.

string

default: hd

Allowed values: hd standard high medium low auto

One image per request.

integer

Allowed values: 1

response_format

string

Allowed values: b64_json

user

Accepted and not passed on.

string

Example

{
  "model": "katara/glm-image@1",
  "prompt": "A watercolor koi pond at dawn",
  "size": "1280x1280"
}

Responses

200

The image.

application/json

object

created

required

integer

data

required

Array<object>

<= 1 items

object

b64_json

The image, base64-encoded.

string

output_format

string

Allowed values: png jpeg webp

usage

required

object

images

The images charged for.

integer

katara

Any of:

object
object

What this reply cost and who produced it.

object

cost_usdc

required

The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the 0.025 USDC minimum included.

string

cost_usd

The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.

string

billing_method

string

Allowed values: credits usdc

payment

On a request paid with x402, the payment that settles the reply.

object

scheme

string

Allowed values: upto exact

network

string

asset

The token paid.

string

amount

The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.

string

provider

The provider’s address, or managed when a vendor answered.

string

served

The concrete model behind every successful named-model or Cortex reply.

object

model

required

string

bundleId

string

provider

The address that served, or the managed identity.

string

managed

True when a managed vendor answered.

boolean

reason

named for a selected model, available, pinned, failover:<n> after n models failed before delivering, or managed:<why>.

string

What this reply cost and who produced it.

object

cost_usdc

The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the 0.025 USDC minimum included.

string

cost_usd

required

The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.

string

billing_method

string

Allowed values: credits usdc

payment

On a request paid with x402, the payment that settles the reply.

object

scheme

string

Allowed values: upto exact

network

string

asset

The token paid.

string

amount

The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.

string

provider

The provider’s address, or managed when a vendor answered.

string

served

The concrete model behind every successful named-model or Cortex reply.

object

model

required

string

bundleId

string

provider

The address that served, or the managed identity.

string

managed

True when a managed vendor answered.

boolean

reason

named for a selected model, available, pinned, failover:<n> after n models failed before delivering, or managed:<why>.

string

Example

{
  "output_format": "png",
  "katara": {
    "cost_usdc": "0.000018",
    "cost_usd": "0.000018",
    "billing_method": "credits",
    "payment": {
      "scheme": "upto",
      "network": "eip155:43114",
      "amount": "25000"
    },
    "served": {
      "model": "katara/qwen3-coder-30b-a3b@1"
    }
  }
}

Headers

PAYMENT-RESPONSE

string

On a call paid with x402, as for chat completions; amount is the charge.

400

A field the route does not take (unsupported_parameter, with param), a malformed request (invalid_request), a model that does not generate images (feature_not_supported), or a credits key and a model its credits cannot pay for (model_requires_usdc).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

Allowed values: invalid_api_key model_not_found invalid_request feature_not_supported insufficient_quota account_suspended wrong_environment no_capacity test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited stateless_only unsupported_parameter provider_failed provider_rejected_request internal_error

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

401

Unknown key, or a call to the Test network without one (invalid_api_key).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

402

Without a key, a quote (with PAYMENT-REQUIRED) or a payment that does not verify (payment_invalid); with a credits key, insufficient_credits.

application/json

One of:

object
object

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

An x402 quote for one request.

object

x402Version

required

integer

Allowed values: 2

error

required

string

accepts

required

The ways this request can be paid, for the same maximum. upto entries, where offered, come before exact. Sign one.

Array<object>

object

scheme

required

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.

string

Allowed values: upto exact

network

required

The chain as a CAIP-2 id.

string

asset

required

The USDC contract the authorization is for.

string

amount

required

The most this request can cost, in the token’s base units. At least 25000 (0.025 USDC).

string

payTo

required

The settlement contract; the authorization’s to.

string

maxTimeoutSeconds

required

Validity to give the authorization.

integer

extra

required

object

name

required

The token’s EIP-712 domain name.

string

version

required

The token’s EIP-712 domain version.

string

nonce

exact only. The job this quote is bound to. It may be signed as the authorization nonce; a random nonce also works.

string

ticketHash

required

The job this quote is bound to.

string

assetTransferMethod

upto only.

string

Allowed values: permit2

facilitatorAddress

upto only. The address that settles; the signed witness names it.

string

provider

required

The address paid for the reply.

string

model

required

The model the request named.

string

served

required

The model that will answer.

string

managed

True when a vendor’s model will answer.

boolean

extensions

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

PAYMENT-REQUIRED

string

Base64 of the PaymentRequired object in the body. Present only on a quote.

404

Unknown model (model_not_found).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

429

A USDC key whose balance cannot cover the call (insufficient_quota), or too many unpaid quotes from one address (quote_rate_limited).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Headers

Retry-After

integer

502

The image provider failed (provider_failed) or refused the prompt (provider_rejected_request). Nothing was charged.

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

503

The model cannot be served right now (no_capacity). Retry after Retry-After.

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota rate_limit_error server_error

code

required

Stable. Branch on this.

string

param

string | null

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Headers

Retry-After

integer

Generate an image

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Example

401

Example

402

Example

Headers

404

Example

429

Example

Headers

502

Example

503

Example

Headers

Request Body^required