Clatter Labs
Console

Model API

Create a chat completion

View as Markdown

Send messages to a SuperCosmos 1.1 model and get a reply, streamed or not, with tool calls and token usage.

POSTapi.gateway.clatterlabs.xyz/v1/chat/completionsmodels:invoke

Creates a model reply for the conversation. Billed per token at the price of the model id, from your credits (plans don't cover API calls).

Any OpenAI SDK works: set the base URL to https://api.gateway.clatterlabs.xyz/v1 and add X-Clatter-Account as a default header. See the quickstart.

Authorizations

Authorizationstringrequired

Your API key as a bearer token: Bearer clsk_.... Create it in Console › API keys with the models:invoke permission (preset Model API).

X-Clatter-Accountstringrequired

The Account ID that owns the key, like CL-7K2M9QXA (Console › Settings). A missing value answers 401 missing_account_id; someone else's answers 401 account_mismatch.

Body

application/json

modelstringrequired

A model id: supercosmos-flash, supercosmos-max or supercosmos-heavy. Or the family id supercosmos with effort.

messagesobject[]required

The conversation: system, developer, user, assistant (with optional tool_calls) and tool (with tool_call_id) messages. Content is a string or an array of {"type": "text"} parts. Up to 800 messages.

streambooleandefault: false

true streams server-sent events (chat.completion.chunk) ending with data: [DONE].

stream_optionsobject

{"include_usage": true} adds a final chunk with usage and empty choices.

toolsobject[]

Up to 64 function tools: {"type": "function", "function": {"name", "description", "parameters"}}.

tool_choicestring | object

auto (default), none, required, or a specific function.

effortstring

With the family id: flash / max / heavy. reasoning_effort low / medium / high works too.

max_tokensinteger

Most output tokens (reasoning included). max_completion_tokens is accepted too. Capped per model (24,576 to 49,152).

temperaturenumber

0 to 2.

top_pnumber

Nucleus sampling, (0, 1].

stopstring | string[]

Up to 4 stop sequences.

seedinteger

Best-effort repeatable sampling.

presence_penaltynumber

Passed to the model.

frequency_penaltynumber

Passed to the model.

Response

200 · application/json

idstring

chatcmpl-…. The same id is the request's entry in Console › Logs.

modelstring

The model id that answered.

choices[0].messageobject

role, content, tool_calls (when the model calls tools) and reasoning_content (Max and Heavy).

choices[0].finish_reasonstring

stop, length or tool_calls.

usageobject

prompt_tokens, completion_tokens (reasoning included) and total_tokens: what's billed.

Errors

StatusCodeWhen
400invalid_request / unsupported_content / unsupported_parameter / invalid_effortThe body isn't valid, has image parts, asks for n > 1 or logprobs, or names an unknown effort.
401invalid_api_key / expired_api_key / missing_account_id / account_mismatchThe key or Account ID is wrong.
402out_of_creditsYour credits are used up. Add credits in Console › Billing › Credits.
403insufficient_scopeThe key doesn't have models:invoke.
403account_suspendedYour account is paused for 24 hours under the Abuse policy. The body has resets_at; wait for Retry-After.
404model_not_foundUnknown model id.
410model_retiredA retired model id (Line Code). Use a SuperCosmos id. See Line Code retirement.
429rate_limitedThe key's requests-per-minute limit is reached. Wait for Retry-After.
503model_overloaded / model_unavailableThe model is at capacity or briefly unavailable. Retry after Retry-After.
curl https://api.gateway.clatterlabs.xyz/v1/chat/completions \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "supercosmos-flash",
    "messages": [{"role": "user", "content": "Write a haiku about the sea."}]
  }'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.gateway.clatterlabs.xyz/v1",
    api_key=os.environ["CLATTER_API_KEY"],
    default_headers={"X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"]},
)
resp = client.chat.completions.create(
    model="supercosmos-flash",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.gateway.clatterlabs.xyz/v1",
  apiKey: process.env.CLATTER_API_KEY,
  defaultHeaders: { "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID },
});
const resp = await client.chat.completions.create({
  model: "supercosmos-flash",
  messages: [{ role: "user", content: "Write a haiku about the sea." }],
});
console.log(resp.choices[0].message.content);
{
  "id": "chatcmpl-c12f22770a744952a4457d3a",
  "object": "chat.completion",
  "created": 1793280843,
  "model": "supercosmos-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Waves fold into foam,\nsalt wind carries gull voices,\nthe tide keeps its time."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 148,
    "completion_tokens": 22,
    "total_tokens": 170
  }
}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"supercosmos-flash","choices":[{"index":0,"delta":{"role":"assistant","content":"Waves"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"supercosmos-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":148,"completion_tokens":22,"total_tokens":170}}

data: [DONE]
{
  "error": {
    "message": "You're out of credits for the Model API: your free $5 trial and your credit balance are used up. See https://console.clatterlabs.com/billing.",
    "type": "insufficient_quota",
    "code": "out_of_credits",
    "param": null
  }
}