# Chat Completions

### Create a chat completion

`POST /v1/chat/completions`

#### Request body

**Required**

* `model` (string). The model ID to use.
* `messages` (array). A list of messages that make up the conversation so far.

**Messages**

Each message has a `role` plus `content`. Supported roles include `system`, `developer`, `user`, `assistant`, `tool`, and `function`. 

`content` can be either a simple string or a structured array for multimodal inputs. For example, `user` content can include typed blocks like `text`, `image_url`, `input_audio`, `document`, `video_url`, or `file`. 

#### Basic example

```bash
curl https://proxy.alfnrl.io/v1/chat/completions \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [
      { "role": "user", "content": "Write a haiku about routers." }
    ]
  }'
```

#### Multimodal example (text + image)

```bash
curl https://proxy.alfnrl.io/v1/chat/completions \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/cat.png" } }
        ]
      }
    ]
  }'
```

Multimodal content blocks are part of the message schema supported by the proxy.

### Common parameters

These follow the OpenAI Chat Completions shape.

* Sampling and length: `temperature`, `top_p`, `max_tokens`, `stop`, `n`, `seed`
* Penalties and biasing: `presence_penalty`, `frequency_penalty`, `logit_bias` 
* Structured outputs: `response_format`
* Logging: `logprobs`, `top_logprobs`
* Streaming: `stream`, `stream_options` 
* Tool calling: `tools`, `tool_choice`, `parallel_tool_calls`
* Legacy function calling: `functions`, `function_call`
* Metadata: `metadata`, `user`

### Tool calling

Provide tool definitions in `tools`. When the model decides to call a tool, it will return `tool_calls` on the assistant message, and you should respond by sending a `tool` role message referencing the matching `tool_call_id`.

#### Tool calling example

```bash
curl https://proxy.alfnrl.io/v1/chat/completions \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [
      { "role": "user", "content": "What is the weather in Paris right now?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city",
          "parameters": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

### Streaming

Set `stream: true` to receive server-sent events (SSE). Each event contains a delta. The stream ends with a final event.

```bash
curl https://proxy.alfnrl.io/v1/chat/completions \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "stream": true,
    "messages": [{ "role": "user", "content": "Explain TCP slow start in one paragraph." }]
  }'
```

### Response

The response follows the OpenAI Chat Completions format (for example, `choices` with an assistant message, plus token `usage`).

### AlphaNeural proxy extensions

The proxy accepts a few optional routing and reliability fields that do not exist in the upstream OpenAI API, such as `guardrails`, `caching`, `num_retries`, `fallbacks`, and `context_window_fallback_dict`. Use these only if you need proxy-level behaviour controls.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alphaneural.io/chat-completions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.