Create a chat completion

POST

/chat/completions

const url = 'https://api.katara.com/v1/chat/completions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"katara/llama-3.1-8b-instruct@1","messages":[{"role":"user","content":"Explain a Merkle tree in two sentences."}],"max_tokens":200}'
};

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/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "katara/llama-3.1-8b-instruct@1", "messages": [ { "role": "user", "content": "Explain a Merkle tree in two sentences." } ], "max_tokens": 200 }'

Same request body as OpenAI chat completions. Set stream: true for server-sent events.

The reply carries a katara object with what you were charged and who served you. In a stream it arrives as one final chunk with an empty choices array, after the content and before data: [DONE].

Admission is checked before any work starts: the balance behind the key must cover the maximum this request could cost (input estimate plus max_tokens at the offer price). Otherwise the request is refused with insufficient_quota and nothing is charged.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

<= 128 characters

Retry a request safely. The same key with the same body returns the first response and charges once.

Request Body^required

application/json

object

model

required

string

messages

required

Array<object>

object

role

required

string

Allowed values: system user assistant tool

content

required

Any of:

string
Array<object>

string

name

string

tool_call_id

string

stream

boolean

max_tokens

Bounds the output and therefore the maximum charge.

integer

temperature

number

top_p

number

tools

Array<object>

object

tool_choice

response_format

object

stop

Example

{
  "model": "katara/llama-3.1-8b-instruct@1",
  "messages": [
    {
      "role": "user",
      "content": "Explain a Merkle tree in two sentences."
    }
  ],
  "max_tokens": 200
}

Responses

200

The completion, or a server-sent event stream when stream is true.

object

required

string

object

required

string

Allowed value: chat.completion

model

required

string

system_fingerprint

Who served the request. <bundle>:<profile> for a marketplace provider, fallback:<mapping> for the managed fallback.

string

choices

required

Array<object>

object

index

integer

finish_reason

string

Allowed values: stop length tool_calls

message

object

role

string

content

string

tool_calls

Array<object>

object

usage

required

object

prompt_tokens

integer

completion_tokens

integer

total_tokens

integer

katara

required

What this reply cost and who produced it.

object

cost_usdc

required

The settled price, in USDC, as a decimal string.

string

provider

required

The provider’s address, or fallback.

string

fallback

required

True when the managed fallback answered because no provider could.

boolean

mapping

Which fallback mapping served the request. Only present when fallback is true.

string

Example

{
  "id": "chatcmpl-7f3a9c2e1b0d",
  "object": "chat.completion",
  "model": "katara/llama-3.1-8b-instruct@1",
  "system_fingerprint": "0xb353…:0x620b…",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "A Merkle tree hashes data in pairs up to one root hash…"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 52,
    "total_tokens": 70
  },
  "katara": {
    "cost_usdc": "0.000018",
    "provider": "0xfFe5…38DC",
    "fallback": false
  }
}

data: {chunk} lines ending with data: [DONE]. The last content chunk carries usage; a further chunk with empty choices carries katara.

string

Headers

x-katara-request-id

string

Request id for support and for matching usage records.

400

Malformed request, or a feature the model does not support (feature_not_supported).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota 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 no_capacity internal_error

param

string | null

Example

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

401

Missing or unknown key (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 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 no_capacity internal_error

param

string | null

Example

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

403

The account is suspended (account_suspended).

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota 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 no_capacity internal_error

param

string | null

Example

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

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 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 no_capacity internal_error

param

string | null

Example

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

429

The balance behind the key cannot cover this request (insufficient_quota). Add USDC, or raise the budget cap, then retry.

application/json

object

error

required

object

message

required

For people. Wording may change.

string

type

required

string

Allowed values: invalid_request_error insufficient_quota 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 no_capacity internal_error

param

string | null

Example

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

Headers

Retry-After

integer

503

No provider can take the request right now and no fallback applies (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 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 no_capacity internal_error

param

string | null

Example

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

Headers

Retry-After

integer

Create a chat completion

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Example

401

Example

403

Example

404

Example

429

Example

Headers

503

Example

Headers

Request Body^required