---
url: /docs/api/openai-chat-completions.md
---
# OpenAI Chat Completions

`POST /v1/chat/completions`

OpenAI-compatible chat completions. All standard parameters are accepted
(`temperature`, `max_tokens`, `tools`, `top_p`, `stop`, etc.).

See [OpenAI's documentation](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
for the full request and response specification.

## Request

```bash
curl https://hyper.charm.land/v1/chat/completions \
  -H "Authorization: Bearer sk-hyper-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | yes | Model ID from [`/v1/models`](/api/list-models) |
| `messages` | array | yes | Array of message objects |
| `stream` | boolean | no | Set `true` for SSE streaming (default `false`) |
| `temperature` | number | no | 0–2 |
| `max_tokens` | integer | no | Max output tokens |
| `tools` | array | no | Tool/function definitions |

## Response

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hey there!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15,
    "cost": {
      "usd": 0.000012,
      "hypercredits": 12
    },
    "remaining": {
      "hypercredits": 88
    }
  }
}
```

### Custom Usage Fields

Hyper extends the standard `usage` object with cost and balance information:

| Field | Description |
|-------|-------------|
| `usage.cost.usd` | Cost of this request in USD |
| `usage.cost.hypercredits` | Cost in Hypercredits |
| `usage.remaining.hypercredits` | Team's remaining Hypercredit balance after this request |

These fields are included in both regular and streaming responses. For
streaming, they appear in the final chunk when `include_usage` is enabled
via `stream_options`.

## Streaming

Set `"stream": true` to receive server-sent events:

```bash
curl https://hyper.charm.land/v1/chat/completions \
  -H "Authorization: Bearer sk-hyper-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

Each chunk is a `data:` line containing a `chat.completion.chunk` object.
The stream ends with `data: [DONE]`.

## Errors

All errors use the standard OpenAI error format:

```json
{
  "error": {
    "message": "...",
    "type": "...",
    "code": null
  }
}
```

| Status | `error.type` | Cause |
|--------|-------------|-------|
| 400 | `invalid_request_error` | Invalid JSON, missing `model` or `messages`, context window exceeded |
| 401 | `authentication_error` | Missing or invalid API key |
| 402 | `billing_error` | Insufficient Hypercredits |
| 403 | `permission_error` | Forbidden |
| 404 | `invalid_request_error` | Model not found |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 5xx | `server_error` | Upstream provider failure |