Models — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Models

List and retrieve models available to your API key.

## List models

```
GET <BASE_URL>/v1/models
```

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 500 | Max items (1–1000) |

### Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-chat",
      "object": "model",
      "name": "DeepSeek Chat",
      "context_length": 128000,
      "architecture": {
        "input_modalities": ["text"],
        "output_modalities": ["text"]
      },
      "supported_parameters": ["temperature", "max_tokens", "top_p"],
      "default_parameters": {"temperature": 0.7}
    }
  ]
}
```

Only models **available to your API key** are returned. Unavailable or deprecated models are excluded.

## Retrieve model

```
GET <BASE_URL>/v1/models/{id}
```

The `{id}` path segment supports slashes (e.g. `deepseek/deepseek-chat`).

### Response

Same object shape as a single entry in the list `data` array.

### Errors

| HTTP | `error.code` | Cause |
|------|--------------|-------|
| 400 | — | Missing model id |
| 404 | `model_not_found` | Unknown or not available for your key |
| 502 | — | Model list temporarily unavailable |

## Model id format

Use the **`id`** from `GET /v1/models` as the `model` parameter in chat requests (typically `{vendor}/{model}` such as `deepseek/deepseek-chat`).

**Sell prices** (input / cached input / output) are **not** returned by this endpoint. See the [console Models marketplace](https://console.supanexus.ai/models) — [Model pricing](./model-pricing.md).

## Response fields

List and detail responses may include metadata beyond the minimal OpenAI model object:

| Field | Description |
|-------|-------------|
| `name` | Display name |
| `context_length` | Max context window |
| `architecture` | Input/output modalities (`input_modalities` / `output_modalities`; common values: `text`, `image`, `video`) |
| `supported_parameters` | Parameters supported by the model |
| `default_parameters` | Suggested defaults |

Before sending images or video, check that the model’s `architecture.input_modalities` includes `"image"` / `"video"`.

| Upstream type | Recommended endpoint | Request format |
|---------------|----------------------|----------------|
| Non-Anthropic (OpenAI-compatible upstream) | [`POST /v1/chat/completions`](./chat-completions.md) | `image_url` (URL or data URI); `video_url` (**public http(s) only**) — see [Parameters → Multimodal input](./parameters.md) |
| `anthropic/*` (Anthropic Messages upstream) | [`POST /v1/messages`](./messages.md) | Anthropic image content blocks — see [Messages → Multimodal input](./messages.md) (video is not on this path) |

Cross-protocol image requests (e.g. Chat Completions against Anthropic models, or Messages against OpenAI-protocol upstreams) are **unreliable** today: images may be dropped silently or rejected by the upstream. Pick the endpoint from the table above. Whale does **not** allow video as a data URI through the gateway.

## Related

- [Chat Completions](./chat-completions.md)
- [Model pricing](./model-pricing.md)
- [Parameters](./parameters.md)