# Models API

> List the models your OpenCheese API key can use with GET /v1/models: every field explained, from modalities and reasoning levels to context and output limits.
>
> Web page: https://opencheese.dev/en/docs/models/ · Every docs page: https://opencheese.dev/llms.txt

`GET https://api.opencheese.dev/v1/models` lists the models your API key can use right now, in
the OpenAI list shape. What it contains depends on your plan, the key's model restrictions and
the models you switched off on the **Prices** page, so read it instead of copying model IDs
from examples.

## Request

```bash
curl https://api.opencheese.dev/v1/models \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

`x-api-key` works too. An invalid key answers `401` with a JSON error.

## Response

A text model (the values are examples):

```json
{
  "object": "list",
  "data": [
    {
      "id": "MODEL_ID",
      "object": "model",
      "created": 0,
      "owned_by": "opencheese",
      "displayName": "Example Model",
      "name": "Example Model",
      "capabilities": { "streaming": true, "tools": true },
      "pricing": { "inputRate": 0.5, "outputRate": 2, "cacheReadRate": 0.05, "cacheWriteRate": 0.6 },
      "modalities": { "input": ["text", "image"], "output": ["text"] },
      "reasoning": true,
      "reasoningEfforts": { "max": "max", "medium": "medium", "low": "low" },
      "supported_reasoning_levels": ["max", "medium", "low"],
      "efforts": ["max", "medium", "low"],
      "default_reasoning_level": "max",
      "context_window": 1000000,
      "contextWindow": 1000000,
      "max_output_tokens": 131000,
      "maxTokens": 131000,
      "maxOutputTokens": 131000
    }
  ]
}
```

## Fields

| Field | Meaning |
| --- | --- |
| `id` | The ID to send as `model`. |
| `displayName`, `name` | The model's name as the dashboard shows it. |
| `capabilities` | Whether the model streams and calls tools. |
| `pricing` | Your rates in credits (USD) per million tokens: input, output, cached input read and cache write. Free models show zeros. |
| `modalities` | What the model reads (`input`) and produces (`output`): `text`, `image`, `video`, `audio`, `pdf`. |
| `supported_reasoning_levels` | The effort levels you may send, strongest first. `efforts` and the keys of `reasoningEfforts` repeat them for clients that read those names. |
| `default_reasoning_level` | The first, strongest level of that list. |
| `context_window` | The most tokens the model reads in one request, prompt included. `contextWindow` is the same number. |
| `max_output_tokens` | The longest answer the model writes. `maxTokens` and `maxOutputTokens` are the same number. |

A field is left out when it does not apply: a model with no selectable effort has no level
fields, and a model without a known limit has no limit fields. Send the effort only with a
level from `supported_reasoning_levels`; [Chat Completions](https://opencheese.dev/en/docs/chat-completions.md),
[Responses](https://opencheese.dev/en/docs/responses.md) and [Messages](https://opencheese.dev/en/docs/messages.md) show where it goes.

## Image models

Models whose `modalities.output` is `["image"]` generate pictures. They carry only the basic
fields above; their parameters (sizes, aspect ratios, quality, how many images a request may
return) come from `GET /v1/images/capabilities`, described in the
[Image API](https://opencheese.dev/en/docs/images.md).

## Filter the list

All text models with `jq`:

```bash
curl -s https://api.opencheese.dev/v1/models \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  | jq -r '.data[] | select(.modalities.output | index("text")) | .id'
```

Free models:

```bash
curl -s https://api.opencheese.dev/v1/models \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  | jq -r '.data[] | select(.pricing.inputRate == 0 and .pricing.outputRate == 0) | .id'
```

Free models still need a small minimum balance on your account; see the
[FAQ](https://opencheese.dev/en/faq/#free-models).

## With an SDK

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
for model in client.models.list():
    print(model.id)
```

There is no `GET /v1/models/{id}`: read the model from the list.