Skip to content
KataraKatara documentation

Edit an image

POST
/images/edits
curl --request POST \
  --url https://api.katara.com/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=katara/cortex \
  --form prompt=example \
  --form image=@file \
  --form previous_edit_id=example \
  --form size=1536x1024 \
  --form image_size=1K \
  --form aspect_ratio=1:1 \
  --form n=1 \
  --form response_format=b64_json

Changes a picture by an instruction, optionally with reference pictures. Any model name is served by Katara Cortex, which edits with the main image model. One image per request, returned as base64. The price is the model’s per-image price for the size made, plus input_image_price for each picture sent, and is charged only when an image comes back. A reply carries katara.edit_id; send it as previous_edit_id to keep editing the same picture without sending it again. The id lasts 7 days and works only for the account or wallet that paid for the turn.

Pictures are PNG, JPEG or WebP, at most 7 MB each and 11 in all (the one edited and 10 references); the request body is at most 19 MB. Links and file ids are not fetched, and there is no mask. Every image carries an invisible watermark.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “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 Bodyrequired

Section titled “Request Bodyrequired”
object
model
required
string
Example
katara/cortex
prompt
required
string
<= 4000 characters
image

The picture to edit. Send several as image[]; the first is edited, the rest are references.

string format: binary
previous_edit_id
string
size
string
Example
1536x1024
image_size
string
Allowed values: 1K 2K 4K
aspect_ratio
string
Allowed values: 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9
n
integer
Allowed values: 1
response_format
string
Allowed values: b64_json

Responses

Section titled “Responses”

200

Section titled “200”

The edited image, in the same shape as a generated one.

Media typeapplication/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
object
Any of:

What this reply cost.

object
cost_usdc
required

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

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
cached_tokens

Prompt tokens the vendor read from its cache, billed at the cached input rate.

integer
cache_saving_usdc

What the cached tokens saved against the input rate, in USDC.

string
cache_saving_usd

The same saving in Credits, on a reply paid with account credits.

string
compaction

When katara.compaction summarised the conversation.

object
message

The system message to send in place of the summarised messages.

object
replaces_from

First index in this request’s messages that the summary replaces.

integer
replaces_to

First index kept after it.

integer
model
string
tokens_before
integer
summary

The summary request’s usage and its cost (cost_usdc or cost_usd).

object
skipped

Why no summary was made; the request went whole.

string
context_edits
object
cleared_tool_results
integer
cleared_tokens
integer
through_turn
integer
cache_written_tokens

Tokens this request wrote to a new explicit cache (katara.cache).

integer
cache_ttl_seconds

How long that cache is kept.

integer
cache_storage_usdc

What keeping it costs, in USDC; included in cost_usdc.

string
simulated

On Test, a reply with fixed text that no model wrote, served when no Test provider was free.

boolean
stop_sequence

The stop sequence at which Katara ended the reply.

string
web_search

The searches this request was charged for.

object
requests

The successful searches; only those are charged, and none when the request ended without an answer.

integer
cost_usdc
string
cost_usd
string
model_calls

On a web search request, how many model calls it made.

integer
web_searches

Every search the model made, in order. Not on stream chunks, which carry each search as it runs.

Array<object>
object
id
required
string
query
required
string
results
required
Array<object>
object
url
string
title
string
page_age
string
content
string
error
string
Allowed values: invalid_input query_too_long too_many_requests unavailable max_uses_exceeded insufficient_quota
edit_id

On an image reply from a model that edits, the id to send as previous_edit_id.

string
edit_id

From a model that edits: send as previous_edit_id to keep editing this picture.

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"
    },
    "web_searches": [
      {
        "error": "invalid_input"
      }
    ]
  }
}

Headers

Section titled “Headers”
PAYMENT-RESPONSE
string

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

400

Section titled “400”

A malformed request (invalid_request), edit_expired when previous_edit_id is no longer kept or belongs to another payer, too_many_images, image_refused when the provider refused the prompt, or a field the route does not take (unsupported_parameter).

Media typeapplication/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. Errors says what each code means and what to do; new codes may be added.

string
Allowed values: invalid_api_key model_not_found model_requires_x402 model_requires_usdc invalid_request invalid_value invalid_web_search context_length_exceeded feature_not_supported media_too_large insufficient_quota insufficient_credits funding_pending community_off account_suspended billing_suspended wrong_environment no_capacity upstream_timeout test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited unsupported_parameter provider_failed provider_output_invalid provider_rejected_request provider_rate_limited provider_overloaded request_too_large not_found method_not_allowed storage_unavailable internal_error
param
string | null
request_id

The response’s x-katara-request-id.

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

401

Section titled “401”

Unknown key (invalid_api_key).

Media typeapplication/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. Errors says what each code means and what to do; new codes may be added.

string
Allowed values: invalid_api_key model_not_found model_requires_x402 model_requires_usdc invalid_request invalid_value invalid_web_search context_length_exceeded feature_not_supported media_too_large insufficient_quota insufficient_credits funding_pending community_off account_suspended billing_suspended wrong_environment no_capacity upstream_timeout test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited unsupported_parameter provider_failed provider_output_invalid provider_rejected_request provider_rate_limited provider_overloaded request_too_large not_found method_not_allowed storage_unavailable internal_error
param
string | null
request_id

The response’s x-katara-request-id.

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

402

Section titled “402”

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

Media typeapplication/json
One of:
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. Errors says what each code means and what to do; new codes may be added.

string
Allowed values: invalid_api_key model_not_found model_requires_x402 model_requires_usdc invalid_request invalid_value invalid_web_search context_length_exceeded feature_not_supported media_too_large insufficient_quota insufficient_credits funding_pending community_off account_suspended billing_suspended wrong_environment no_capacity upstream_timeout test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited unsupported_parameter provider_failed provider_output_invalid provider_rejected_request provider_rate_limited provider_overloaded request_too_large not_found method_not_allowed storage_unavailable internal_error
param
string | null
request_id

The response’s x-katara-request-id.

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

Headers

Section titled “Headers”
PAYMENT-REQUIRED
string

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

413

Section titled “413”

The body is over 19 MB (request_too_large).

Media typeapplication/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. Errors says what each code means and what to do; new codes may be added.

string
Allowed values: invalid_api_key model_not_found model_requires_x402 model_requires_usdc invalid_request invalid_value invalid_web_search context_length_exceeded feature_not_supported media_too_large insufficient_quota insufficient_credits funding_pending community_off account_suspended billing_suspended wrong_environment no_capacity upstream_timeout test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited unsupported_parameter provider_failed provider_output_invalid provider_rejected_request provider_rate_limited provider_overloaded request_too_large not_found method_not_allowed storage_unavailable internal_error
param
string | null
request_id

The response’s x-katara-request-id.

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

500

Section titled “500”

The image provider failed. Nothing was charged.

Media typeapplication/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. Errors says what each code means and what to do; new codes may be added.

string
Allowed values: invalid_api_key model_not_found model_requires_x402 model_requires_usdc invalid_request invalid_value invalid_web_search context_length_exceeded feature_not_supported media_too_large insufficient_quota insufficient_credits funding_pending community_off account_suspended billing_suspended wrong_environment no_capacity upstream_timeout test_network_unavailable payment_invalid permit2_allowance_required quote_rate_limited unsupported_parameter provider_failed provider_output_invalid provider_rejected_request provider_rate_limited provider_overloaded request_too_large not_found method_not_allowed storage_unavailable internal_error
param
string | null
request_id

The response’s x-katara-request-id.

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