# Chat Completions

> Send OpenAI-compatible chat completion requests to ScaleMax with messages, model IDs, output limits, authentication, and error handling.

POST `/v1/chat/completions` (API credit) or `/token/v1/chat/completions` (API token)

Generate a model response from a list of messages. This is the primary endpoint and the one OpenAI SDKs are designed for.

Set the OpenAI-compatible base URL to `https://api.scalemax.pro/v1` for API credit or `https://api.scalemax.pro/token/v1` for an API-token key. For native Claude clients, use the Anthropic Messages origin described in the [Claude Code](https://docs.scalemax.pro/docs/manual-configuration/claude-code) and [Claude Desktop](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop) guides instead.

## Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `model` | string | yes | Any model id from the [Models](https://docs.scalemax.pro/docs/models) page. |
| `messages` | Message\[\] | yes | OpenAI message format. Each message has `role` and `content`. |
| `stream` | boolean | no | Set to `true` for SSE. See [Streaming](https://docs.scalemax.pro/docs/streaming). |
| `temperature` | number (0–2) | no | Default `1`. |
| `max_tokens` | integer | no | Cap on output tokens. |
| `top_p` | number (0–1) | no | Nucleus sampling. |
| `tools` | Tool\[\] | no | OpenAI tool/function calling format. Routed to the provider's equivalent. |
| `stop` | string \| string\[\] | no | Stop sequences. Up to 4. |
| `user` | string | no | End-user identifier for abuse detection. |

## Example request

**macOS / Linux**

request.sh:

```bash
curl "$SCALEMAX_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user",   "content": "What is the capital of France?"}
    ],
    "temperature": 0.2,
    "max_tokens": 100
  }'
```

**Windows PowerShell**

request.ps1:

```powershell
@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "messages": [
    {"role": "system", "content": "You are a concise assistant."},
    {"role": "user",   "content": "What is the capital of France?"}
  ],
  "temperature": 0.2,
  "max_tokens": 100
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## Example response

response.json:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1719228000,
  "model": "fable-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 3,
    "total_tokens": 31
  }
}
```

## Tool use

Function calling follows OpenAI's tool/function format. When a model returns a `tool_calls` entry, append the result as a `role: "tool"` message and send again.

tool-call response:

```json
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_...",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"Paris\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```

## Notes

- Prompt caching is supported where the upstream provider supports it. Customer API-credit billing still charges cached input once at the published input rate; any provider cache discount is an internal cost and is not a customer discount.
- `finish_reason` values are normalized across providers: `stop`, `length`, `tool_calls`, `content_filter`.
- See [Error Codes](https://docs.scalemax.pro/docs/error-codes) for failure handling.