Model API quickstart - Clatter Labs Docs

Before you start

You need a Clatter Labs account (accounts.clatterlabs.com). New accounts get $5 of free credit, so you can try every model before adding anything.

Create a key with models:invoke

In the Console, go to API keys › Create API key and pick the Model API preset (permission models:invoke). The key starts with clsk_ and is shown once. Your Account ID (like CL-7K2M9QXA) is in Settings.

Terminal

export CLATTER_API_KEY="clsk_..."          # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX"    # Console › Settings

Make a call

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."}]
  }'
# pip install openai
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)
print(resp.usage)
// npm install openai
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, resp.usage);

Check the cost

The response carries usage (prompt_tokens, completion_tokens). The same call shows in Console › Logs with its price, paid from your credits.

Stream

Set "stream": true to get server-sent events in the OpenAI chunk format, ending with data: [DONE]. Add "stream_options": {"include_usage": true} for a final chunk with usage (the last content chunk also carries it).

Python

stream = client.chat.completions.create(
    model="supercosmos-flash",
    messages=[{"role": "user", "content": "Explain recursion in two sentences."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Max and Heavy think before answering. Their reasoning streams as delta.reasoning_content (and message.reasoning_content without streaming) and is billed as output.

Call tools

Pass tools as OpenAI function definitions. When the model wants a tool, the reply has tool_calls and finish_reason: "tool_calls"; run the tool and send the result back as a tool message.

Python

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    },
}]
msgs = [{"role": "user", "content": "What's the weather in Paris?"}]
r = client.chat.completions.create(model="supercosmos-max", messages=msgs, tools=tools)
call = r.choices[0].message.tool_calls[0]

msgs += [r.choices[0].message, {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 18, "sky": "light rain"}'}]
print(client.chat.completions.create(model="supercosmos-max", messages=msgs, tools=tools).choices[0].message.content)

Pick a model

If you need	Use
Fast, cheap answers and tool loops	`supercosmos-flash`
Planning, debugging, multi-step work	`supercosmos-max`
The hardest problems, long reasoning	`supercosmos-heavy`

Prices for each are on the Model API overview.