# GPT-6.1 Terra

## Model and endpoint

Use `gpt-6.1-terra` with `POST https://api.toklab.ai/v1/responses`. Keep your TokLab API key on the server.

This reference covers the core text-generation request. Optional reasoning, tool and sampling controls depend on the model and selected route; do not assume that settings from another model version are interchangeable.

## Quick example

```bash
curl https://api.toklab.ai/v1/responses \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-terra", "input": "Explain optimistic concurrency in three bullet points.", "max_output_tokens": 1024}'
```

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKLAB_API_KEY"],
    base_url="https://api.toklab.ai/v1",
)
response = client.responses.create(
    model="gpt-6.1-terra",
    input="Explain optimistic concurrency.",
    max_output_tokens=1024,
)
print(response.output_text)
```

## Request parameters

| Field               | Type                  | Usage                                                           |
| ------------------- | --------------------- | --------------------------------------------------------------- |
| `model`             | string                | Required; `gpt-6.1-terra` or an available full `model:group` ID |
| `input`             | string or input items | Required prompt or conversation input                           |
| `instructions`      | string                | Optional system instructions                                    |
| `max_output_tokens` | integer               | Optional positive output-token budget                           |
| `stream`            | boolean               | Optional; `true` returns server-sent events                     |

Omit optional controls to use the upstream defaults. Token budgets must fit the selected model's context and output limits; this reference does not advertise unverified limits.

## Response and streaming

The JSON response contains `id`, `model`, `status`, `output`, and `usage`. Read `output_text` content blocks inside message items in `output`; the SDK exposes the combined text as `response.output_text`.

Set `stream: true` and add `-N` to cURL to consume the event stream. For streaming, handle `response.output_text.delta` and the terminal `response.completed`, `response.incomplete`, or error event. Read final usage from the terminal response. A closed connection alone does not establish a successful response.

## Chat Completions compatibility

The shared gateway also accepts `POST /v1/chat/completions` with Bearer authentication:

```json
{
  "model": "gpt-6.1-terra",
  "messages": [
    {
      "role": "user",
      "content": "Explain optimistic concurrency."
    }
  ]
}
```

Read the answer from `choices[0].message.content`; streamed deltas appear in `choices[0].delta.content`. Use the native endpoint above for provider-specific features.

## Pricing and route selection

TokLab reads prices from the shared gateway. Input, output, cache usage and any context-length tiers are listed in **Current rates** below; all amounts are USD. The catalogue's starting price is the input rate per million tokens, not the total request cost.

Discover the calling IDs available to your key:

```bash
curl https://api.toklab.ai/v1/models \
  -H "Authorization: Bearer $TOKLAB_API_KEY"
```

Use an exact ID returned by discovery. A listed `model:group` ID selects that group's rates and requires access to that group. Public pricing alone does not guarantee that every key can call a route.

## Errors

Check the HTTP status and response body before reading the output. Authentication failures return 401; access or permission failures may return 403; malformed or unsupported parameters return a 4xx response; rate limits return 429. Retry transient errors with backoff, and avoid automatically resubmitting an interrupted request whose outcome is unknown. See the [shared error reference](https://toklab.ai/docs/api/errors).

## Pricing

Every rate this model is billed at, read live from the price list billing uses. A tier applies when its condition matches, checked top to bottom.

### gpt-6.1-terra

| When | Input (per 1M tokens) | Output (per 1M tokens) | Cache read (per 1M tokens) | Cache write (5 min) (per 1M tokens) | Cache write (1 h) (per 1M tokens) |
| --- | --- | --- | --- | --- | --- |
| Input ≤ 272K | $0.10 | $0.50 | $0.005 | $0.125 | $0.125 |
| Otherwise | $0.20 | $0.75 | $0.01 | $0.25 | $0.25 |

## Related

* [Browse models](https://toklab.ai/models)
* [Pricing](https://toklab.ai/pricing)
* [Download OpenAPI](https://toklab.ai/docs/gpt-6-1-terra.openapi.json)
* [Copyable Markdown](https://toklab.ai/docs/gpt-6-1-terra.md)