# Create a chat completion

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

`POST https://api.gateway.clatterlabs.xyz/v1/chat/completions` (key permission: `models: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).

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create it in [Console › API keys](https://console.clatterlabs.com/api-keys) with the **models:invoke** permission (preset **Model API**).
- `X-Clatter-Account` (string, required): 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

- `model` (string, required): A model id: `supercosmos-flash`, `supercosmos-max` or `supercosmos-heavy`. Or the family id `supercosmos` with `effort`.
- `messages` (object[], 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.
- `stream` (boolean, default false): `true` streams server-sent events (`chat.completion.chunk`) ending with `data: [DONE]`.
- `stream_options` (object): `{"include_usage": true}` adds a final chunk with `usage` and empty `choices`.
- `tools` (object[]): Up to 64 function tools: `{"type": "function", "function": {"name", "description", "parameters"}}`.
- `tool_choice` (string | object): `auto` (default), `none`, `required`, or a specific function.
- `effort` (string): With the family id: `flash` / `max` / `heavy`. `reasoning_effort` `low` / `medium` / `high` works too.
- `max_tokens` (integer): Most output tokens (reasoning included). `max_completion_tokens` is accepted too. Capped per model (24,576 to 49,152).
- `temperature` (number): 0 to 2.
- `top_p` (number): Nucleus sampling, (0, 1].
- `stop` (string | string[]): Up to 4 stop sequences.
- `seed` (integer): Best-effort repeatable sampling.
- `presence_penalty` (number): Passed to the model.
- `frequency_penalty` (number): Passed to the model.

## Response

- `id` (string): `chatcmpl-…`. The same id is the request's entry in Console › Logs.
- `model` (string): The model id that answered.
- `choices[0].message` (object): `role`, `content`, `tool_calls` (when the model calls tools) and `reasoning_content` (Max and Heavy).
- `choices[0].finish_reason` (string): `stop`, `length` or `tool_calls`.
- `usage` (object): `prompt_tokens`, `completion_tokens` (reasoning included) and `total_tokens`: what's billed.

## Example request

```bash
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."}]
  }'
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `400` | `invalid_request / unsupported_content / unsupported_parameter / invalid_effort` | The body isn't valid, has image parts, asks for `n` > 1 or `logprobs`, or names an unknown effort. |
| `401` | `invalid_api_key / expired_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `out_of_credits` | Your credits are used up. Add credits in Console › Billing › Credits. |
| `403` | `insufficient_scope` | The key doesn't have `models:invoke`. |
| `403` | `account_suspended` | Your account is paused for 24 hours under the [Abuse policy](/policies/abuse). The body has `resets_at`; wait for `Retry-After`. |
| `404` | `model_not_found` | Unknown model id. |
| `410` | `model_retired` | A retired model id (Line Code). Use a SuperCosmos id. See [Line Code retirement](/models/line-code-retired). |
| `429` | `rate_limited` | The key's requests-per-minute limit is reached. Wait for `Retry-After`. |
| `503` | `model_overloaded / model_unavailable` | The model is at capacity or briefly unavailable. Retry after `Retry-After`. |

## Example response

```json
{
  "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
  }
}
```

<Tip>
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](/model-api/quickstart).
</Tip>