# Create a chat completion

```http
POST /chat/completions
```

Base URL: `https://ai.aur.lu/v1`

Operation ID: `createInferenceChatCompletion`

Authentication: PortalToken (HTTP bearer)

Requires the execute:inference:requests permission and access to inference.
Prepaid accounts must have positive inference credit. Select a model from
GET /models; tool calling, structured output, and multimodal input support
depend on the selected model.

With stream=true, the response is an SSE stream of JSON chat completion
chunks with choices[].delta, followed by data: [DONE].
Clients must accept usage-only chunks with an empty choices array.
Errors before streaming use an HTTP error response;
an interrupted stream is not a complete response.

## Request body (required)

Content type: `application/json`

Supported options and defaults depend on the selected model.

- `model` (string, required) — Exact public ID or compatibility alias from GET /models.
- `stream` (boolean, default: `false`)
- `stream_options` (object)
  - `include_usage` (boolean) — Streaming responses include usage information. Clients must accept usage-only chunks with an empty choices array.
- `max_tokens` (integer) — Maximum generated tokens; model-dependent limits apply.
- `temperature` (number) — Sampling temperature; range and default depend on the selected model.
- `top_p` (number) — Nucleus sampling probability.
- `n` (integer) — Number of choices where supported.
- `stop` (one of string | array of string) — Stop sequence or sequences where supported.
  - `variant 1` (string, nullable)
  - `variant 2` (array of string)
- `presence_penalty` (number)
- `frequency_penalty` (number)
- `seed` (integer<int64>)
- `user` (string) — Optional end-user identifier.
- `messages` (array of object, required)
  - items (object)
    - `role` (string, required, one of: `system`, `developer`, `user`, `assistant`, `tool`)
    - `content` (one of string | array of object) — Text or model-supported content parts. May be null for assistant tool calls.
      - `variant 1` (string, nullable)
      - `variant 2` (array of object)
        - items (object)
          - `type` (string, required)
          - `text` (string)
          - `image_url` (object)
            - `url` (string)
            - `detail` (string)
    - `name` (string)
    - `tool_call_id` (string) — Required for a tool result; matches the assistant tool call ID.
    - `tool_calls` (array of object)
      - items (object)
        - `id` (string, required)
        - `type` (string, required, one of: `function`)
        - `function` (object, required)
          - `name` (string, required)
          - `arguments` (string, required) — JSON-encoded arguments. Validate before executing a tool.
- `max_completion_tokens` (integer) — Model-dependent alternative to max_tokens.
- `tools` (array of object)
  - items (object)
    - `type` (string, required, one of: `function`)
    - `function` (object, required)
      - `name` (string, required)
      - `description` (string)
      - `parameters` (object) — JSON Schema describing function arguments.
      - `strict` (boolean) — Model-dependent strict schema enforcement.
- `tool_choice` (one of string | object) — auto, none, required, or an object selecting a function; model-dependent.
  - `variant 1` (string, one of: `auto`, `none`, `required`)
  - `variant 2` (object)
    - `type` (string, one of: `function`)
    - `function` (object)
      - `name` (string)
- `parallel_tool_calls` (boolean)
- `response_format` (object) — Model-dependent format, such as text, json_object, or json_schema.
  - `type` (string)
  - `json_schema` (object)

Example:

```json
{
  "model": "deepseek/deepseek-v4-flash",
  "messages": [
    {
      "role": "user",
      "content": "Say hello in one sentence."
    }
  ],
  "max_tokens": 128
}
```

## Responses

### 200 — A JSON chat completion, or SSE chunks when stream=true. Streaming ends with data: [DONE].

- `X-Aurora-Resolved-Model` (string) — Canonical model selected for this request. The response body retains the requested model ID or alias.

Content type: `application/json`

- `id` (string, required)
- `object` (string, required, one of: `chat.completion`)
- `created` (integer<int64>, required) — Unix timestamp in seconds.
- `model` (string, required) — Public model ID.
- `usage` (object, nullable)
  - `prompt_tokens` (integer<int64>)
  - `completion_tokens` (integer<int64>)
  - `total_tokens` (integer<int64>)
  - `prompt_tokens_details` (object)
    - `cached_tokens` (integer<int64>)
  - `completion_tokens_details` (object)
- `choices` (array of object, required)
  - items (object)
    - `index` (integer)
    - `message` (object)
      - `role` (string, required, one of: `system`, `developer`, `user`, `assistant`, `tool`)
      - `content` (one of string | array of object) — Text or model-supported content parts. May be null for assistant tool calls.
        - `variant 1` (string, nullable)
        - `variant 2` (array of object)
          - items (object)
            - `type` (string, required)
            - `text` (string)
            - `image_url` (object)
              - `url` (string)
              - `detail` (string)
      - `name` (string)
      - `tool_call_id` (string) — Required for a tool result; matches the assistant tool call ID.
      - `tool_calls` (array of object)
        - items (object)
          - `id` (string, required)
          - `type` (string, required, one of: `function`)
          - `function` (object, required)
            - `name` (string, required)
            - `arguments` (string, required) — JSON-encoded arguments. Validate before executing a tool.
    - `finish_reason` (string, nullable) — For example stop, length, tool_calls, or content_filter.
    - `logprobs` (object, nullable)

Example:

```json
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1788998400,
  "model": "deepseek/deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 10,
    "total_tokens": 24
  }
}
```

Content type: `text/event-stream`

SSE data frames contain JSON chunks with id, object=chat.completion.chunk, created, model, choices (index, delta, finish_reason), and optional usage. Delta may contain content, role, reasoning extensions, or partial tool_calls (index, id, type, function name/arguments). Accumulate fragments before parsing tool arguments.

Type: `string`

Example:

```text
data: {"id":"chatcmpl-example","object":"chat.completion.chunk","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello!"},"finish_reason":null}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","created":1788998400,"model":"deepseek/deepseek-v4-flash","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":2,"total_tokens":16}}

data: [DONE]
```

### 400 — Invalid request. Send an application/json body with the required fields.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 401 — Missing, invalid, or expired bearer token.

Content type: `application/json`

- `message` (string, required)

### 402 — Insufficient prepaid inference credit. Add credits in the Portal before retrying.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "insufficient prepaid inference credit",
    "type": "billing_error"
  }
}
```

### 403 — Missing required permission or account access to inference.

Content type: `application/json`

- `variant 1` (object, example: `{"message":"Missing permission execute:inference:requests"}`)
  - `message` (string, required)
- `variant 2` (object, example: `{"error":{"message":"insufficient prepaid inference credit","type":"billing_error"}}`)
  - `error` (object, required)
    - `message` (string, required)
    - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 404 — Unknown or unavailable model, or unsupported endpoint. Refresh GET /models to discover available IDs.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "model not found",
    "type": "invalid_request_error"
  }
}
```

### 429 — Request rate limit exceeded. Retry after a delay.

Content type: `application/json`

Type: `any`

### 500 — The service could not process the request.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 502 — The service could not complete the inference request. Retry after a delay.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

### 503 — Service is temporarily unavailable. Retry after the indicated delay.

- `Retry-After` (integer) — Suggested delay in seconds before retrying.

Content type: `application/json`

- `error` (object, required)
  - `message` (string, required)
  - `type` (string, required) — Error types include invalid_request_error, billing_error, internal_error, server_error, and service_unavailable.

Example:

```json
{
  "error": {
    "message": "service temporarily unavailable",
    "type": "service_unavailable"
  }
}
```