> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Understand chat requests, response content, finish reasons, and usage.

Send messages to `POST https://api.apione.ai/v1/chat/completions` using the OpenAI-compatible chat format. Verify a minimal request before adding model-specific parameters.

## Send a request

Set `APIONE_API_KEY` and `APIONE_MODEL` using the [quickstart](https://apione.ai/docs/en/quickstart.md). Copy the model ID from the [available model list](https://apione.ai/docs/en/models/catalog.md) and check the key's permissions and billing group.

```bash theme={null}
: "${APIONE_API_KEY:?Set APIONE_API_KEY first}"
: "${APIONE_MODEL:?Set APIONE_MODEL first}"

curl -sS https://api.apione.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIONE_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"model\":\"$APIONE_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Suggest three navigation groups for a documentation site.\"}]}"
```

For multi-turn conversations, your application sends the necessary history in `messages`. Do not assume the next request automatically carries the previous context. For SDK examples, see [Python and Node.js](https://apione.ai/docs/en/guides/sdks.md).

## Common request fields

| Field | Type | Purpose |
| - | - | - |
| `model` | string | Required model ID available to the key |
| `messages` | object\[] | Required message history with `role` and `content` |
| `stream` | boolean | Enable SSE; defaults to `false` |
| `max_tokens` | integer | Output limit; support and valid values depend on the model |
| `temperature` | number | Sampling control; support and range depend on the model |
| `top_p` | number | Alternative sampling control; usually avoid changing it together with `temperature` |
| `tools` / `tool_choice` | object\[] / string or object | Tool definitions and selection, requiring model support |
| `response_format` | object | JSON or JSON Schema output, requiring model support |

Recheck parameters when switching models. For unsupported parameters, remove optional fields and verify the minimal request before restoring them individually.

## Read the response

A text response has the following shape. Values are illustrative:

```json theme={null}
{
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "message": {"role": "assistant", "content": "Getting started, API reference, and integrations."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 20, "completion_tokens": 10, "total_tokens": 30}
}
```

| Field | How to read |
| - | - |
| `choices[].message.content` | Reply text; may be empty for tool calls |
| `choices[].message.tool_calls` | Tool calls the model asks the application to execute |
| `choices[].finish_reason` | Examples include `stop`, `length`, `tool_calls`, and `content_filter` |
| `usage` | Input, output, and total tokens; cache and other additional fields vary by model |
| `model` | Model information in the response |

When `finish_reason` is `length`, check output limits and whether the content is complete; truncated JSON cannot be used directly for downstream business. Tool calls and JSON validation: see [structured output and tools](https://apione.ai/docs/en/models/advanced.md); continuous incremental reception: see [streaming](https://apione.ai/docs/en/models/streaming.md).

See the [APIONE Chat reference](https://apione.ai/en/api-docs/reference/ref-chat) for complete fields and [troubleshooting](https://apione.ai/docs/en/support/errors.md) for failed calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.