# Model API quickstart

> Create a key with models:invoke, make your first call with cURL, Python or JavaScript, stream, and call tools.

## Before you start

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

<Steps>
<Step title="Create a key with models:invoke">
In the [Console](https://console.clatterlabs.com/api-keys), 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**.

```bash
export CLATTER_API_KEY="clsk_..."          # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX"    # Console › Settings
```
</Step>
<Step title="Make a call">
<CodeGroup>
```bash cURL
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."}]
  }'
```

```python Python
# 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)
```

```javascript JavaScript
// 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);
```
</CodeGroup>
</Step>
<Step title="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.
</Step>
</Steps>

## 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](/model-api/overview).