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

# Create Chat Completion

> Generate text completions using chat models

```
POST /v1/chat/completions
```

Creates a model response for the given chat conversation. Supports streaming, function calling, and multiple AI providers through a unified interface.

## Request Body

<ParamField body="model" type="string" required>
  ID of the model to use (e.g., `gpt-4`, `claude-3-5-sonnet`, `gemini-2.0-flash`)
</ParamField>

<ParamField body="messages" type="array" required>
  A list of messages comprising the conversation so far.

  <Expandable title="Message object">
    <ParamField body="role" type="string" required>
      The role of the message author. One of `system`, `user`, `assistant`, `tool`, or `function`.
    </ParamField>

    <ParamField body="content" type="string | array">
      The contents of the message. Can be a string or array of content parts for multimodal input.
    </ParamField>

    <ParamField body="name" type="string">
      An optional name for the participant.
    </ParamField>

    <ParamField body="tool_calls" type="array">
      Tool calls generated by the model (for assistant messages).
    </ParamField>

    <ParamField body="tool_call_id" type="string">
      The ID of the tool call this message is responding to (for tool messages).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  If set to `true`, partial message deltas will be sent as server-sent events.
</ParamField>

<ParamField body="stream_options" type="object">
  Options for streaming responses.

  <Expandable title="properties">
    <ParamField body="include_usage" type="boolean">
      If set, includes usage statistics in the final streamed chunk.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="temperature" type="number" default="1">
  Sampling temperature between 0 and 2. Higher values make output more random.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens to generate in the completion.
</ParamField>

<ParamField body="max_completion_tokens" type="integer">
  An upper bound for the number of tokens that can be generated.
</ParamField>

<ParamField body="stop" type="string | array">
  Up to 4 sequences where the API will stop generating tokens.
</ParamField>

<ParamField body="presence_penalty" type="number" default="0">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on presence in text.
</ParamField>

<ParamField body="frequency_penalty" type="number" default="0">
  Number between -2.0 and 2.0. Positive values penalize new tokens based on frequency in text.
</ParamField>

<ParamField body="tools" type="array">
  A list of tools the model may call.

  <Expandable title="Tool object">
    <ParamField body="type" type="string" required>
      The type of tool. Currently only `function` is supported.
    </ParamField>

    <ParamField body="function" type="object" required>
      The function definition including name, description, and parameters schema.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls which tool is called. `auto` lets the model decide, `none` prevents tool calls, or specify a tool.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default="true">
  Whether to enable parallel function calling during tool use.
</ParamField>

<ParamField body="response_format" type="object">
  Specify the output format.

  <Expandable title="properties">
    <ParamField body="type" type="string">
      Either `text` (default) or `json_object` for JSON mode.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning_effort" type="string">
  For reasoning models, controls the effort level: `low`, `medium`, or `high`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the chat completion.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, always `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for completion.
</ResponseField>

<ResponseField name="choices" type="array">
  A list of chat completion choices.

  <Expandable title="Choice object">
    <ResponseField name="index" type="integer">
      The index of this choice.
    </ResponseField>

    <ResponseField name="message" type="object">
      The generated message.
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason the model stopped generating: `stop`, `length`, `tool_calls`, etc.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics.

  <Expandable title="properties">
    <ResponseField name="prompt_tokens" type="integer">
      Tokens in the prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Tokens in the completion.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens used.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Basic Completion

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-voidai-your_key_here",
      base_url="https://api.voidai.app/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What is the capital of France?"}
      ]
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-voidai-your_key_here',
    baseURL: 'https://api.voidai.app/v1'
  });

  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is the capital of France?' }
    ]
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/chat/completions \
    -H "Authorization: Bearer sk-voidai-your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
      ]
    }'
  ```
</CodeGroup>

### Streaming

<CodeGroup>
  ```python Python theme={null}
  stream = client.chat.completions.create(
      model="gpt-4",
      messages=[{"role": "user", "content": "Tell me a short story"}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="")
  ```

  ```typescript TypeScript theme={null}
  const stream = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Tell me a short story' }],
    stream: true
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
  ```

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/chat/completions \
    -H "Authorization: Bearer sk-voidai-your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4",
      "messages": [{"role": "user", "content": "Tell me a short story"}],
      "stream": true
    }'
  ```
</CodeGroup>

### Function Calling

<CodeGroup>
  ```python Python theme={null}
  tools = [
      {
          "type": "function",
          "function": {
              "name": "get_weather",
              "description": "Get the current weather in a location",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {
                          "type": "string",
                          "description": "The city name"
                      },
                      "unit": {
                          "type": "string",
                          "enum": ["celsius", "fahrenheit"]
                      }
                  },
                  "required": ["location"]
              }
          }
      }
  ]

  response = client.chat.completions.create(
      model="gpt-4",
      messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
      tools=tools,
      tool_choice="auto"
  )

  # Check if the model wants to call a function
  if response.choices[0].message.tool_calls:
      tool_call = response.choices[0].message.tool_calls[0]
      print(f"Function: {tool_call.function.name}")
      print(f"Arguments: {tool_call.function.arguments}")
  ```

  ```typescript TypeScript theme={null}
  const tools = [
    {
      type: 'function' as const,
      function: {
        name: 'get_weather',
        description: 'Get the current weather in a location',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string', description: 'The city name' },
            unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
          },
          required: ['location']
        }
      }
    }
  ];

  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: "What's the weather in Tokyo?" }],
    tools,
    tool_choice: 'auto'
  });

  if (response.choices[0].message.tool_calls) {
    const toolCall = response.choices[0].message.tool_calls[0];
    console.log(`Function: ${toolCall.function.name}`);
    console.log(`Arguments: ${toolCall.function.arguments}`);
  }
  ```
</CodeGroup>

### Vision (Multimodal)

<CodeGroup>
  ```python Python theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "What's in this image?"},
                  {
                      "type": "image_url",
                      "image_url": {
                          "url": "https://example.com/image.jpg",
                          "detail": "high"
                      }
                  }
              ]
          }
      ]
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: "What's in this image?" },
          {
            type: 'image_url',
            image_url: {
              url: 'https://example.com/image.jpg',
              detail: 'high'
            }
          }
        ]
      }
    ]
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

### JSON Mode

<CodeGroup>
  ```python Python theme={null}
  response = client.chat.completions.create(
      model="gpt-4",
      messages=[
          {"role": "system", "content": "You are a helpful assistant that responds in JSON."},
          {"role": "user", "content": "List 3 programming languages with their year of creation"}
      ],
      response_format={"type": "json_object"}
  )

  import json
  data = json.loads(response.choices[0].message.content)
  print(data)
  ```

  ```typescript TypeScript theme={null}
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: 'You are a helpful assistant that responds in JSON.' },
      { role: 'user', content: 'List 3 programming languages with their year of creation' }
    ],
    response_format: { type: 'json_object' }
  });

  const data = JSON.parse(response.choices[0].message.content);
  console.log(data);
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1701691200,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}
```

## Streaming Response

When `stream: true`, responses are sent as server-sent events:

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" capital"},"finish_reason":null}]}

data: [DONE]
```