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

# Chat Completions

> Create chat completion responses.

## Create Chat Completion

Creates a model response for the given chat conversation. Requests are served through the attested TEE gateway, which does not retain request bodies. A confidential response additionally runs on a verified upstream enclave, confirmed per response from the receipt's `upstream.verified` event. The response includes an `x-receipt-id` header for [verification](/guides/verify-a-response).

```bash theme={null}
POST https://api.redpill.ai/v1/chat/completions
```

<Note>
  **Try it now!** Click the "Try it" button above to test the API in the playground. You'll need:

  1. Your API key (add it when prompted)
  2. Fill in `messages` like: `[{"role":"user","content":"Hello"}]`
</Note>

## Request Body

<ParamField body="model" type="string" required default="z-ai/glm-5.1">
  Model ID to use for completion

  **Examples**: `z-ai/glm-5.1`, `z-ai/glm-5`, `qwen/qwen3.5-27b`, `openai/gpt-5`, `anthropic/claude-sonnet-4.5`
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects. Each message needs `role` and `content`.

  **Example**:

  ```json theme={null}
  [
    {"role": "user", "content": "What is confidential AI?"}
  ]
  ```

  **With system message**:

  ```json theme={null}
  [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello!"}
  ]
  ```
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature (0-2), default 1
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens to generate

  **Note:** Newer models (GPT-5, O3, O4) use `max_completion_tokens` instead. See note below.
</ParamField>

<ParamField body="max_completion_tokens" type="integer">
  Maximum completion tokens (for GPT-5, O3, O4 models)

  Use this parameter instead of `max_tokens` for newer OpenAI models:

  * `openai/gpt-5`, `openai/gpt-5-mini`, `openai/gpt-5-nano`
  * `openai/o3`, `openai/o4-mini`
</ParamField>

<ParamField body="stream" type="boolean">
  Stream responses, default false
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling (0-1)
</ParamField>

<ParamField body="n" type="integer">
  Number of completions, default 1
</ParamField>

<ParamField body="presence_penalty" type="number">
  Presence penalty (-2 to 2)
</ParamField>

<ParamField body="frequency_penalty" type="number">
  Frequency penalty (-2 to 2)
</ParamField>

### Message Object

```json theme={null}
{
  "role": "user" | "assistant" | "system",
  "content": "string" | array
}
```

## Example Requests

<CodeGroup>
  ```bash Confidential theme={null}
  curl https://api.redpill.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "z-ai/glm-5.1",
      "messages": [
        {"role": "user", "content": "What is confidential AI?"}
      ]
    }'
  ```

  ```bash OpenAI theme={null}
  curl https://api.redpill.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "openai/gpt-5",
      "messages": [
        {"role": "user", "content": "What is confidential AI?"}
      ]
    }"
  ```

  ```bash With Parameters theme={null}
  curl https://api.redpill.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "anthropic/claude-sonnet-4.5",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain TEE"}
      ],
      "temperature": 0.7,
      "max_tokens": 500
    }"
  ```

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

  client = OpenAI(
      api_key="YOUR_API_KEY",
      base_url="https://api.redpill.ai/v1"
  )

  response = client.chat.completions.create(
      model="openai/gpt-5",
      messages=[
          {"role": "system", "content": "You are helpful."},
          {"role": "user", "content": "Hello!"}
      ],
      temperature=0.7,
      max_tokens=100
  )

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

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.redpill.ai/v1',
    apiKey: 'YOUR_API_KEY'
  });

  const response = await client.chat.completions.create({
    model: 'openai/gpt-5',
    messages: [
      { role: 'system', content: 'You are helpful.' },
      { role: 'user', content: 'Hello!' }
    ],
    temperature: 0.7,
    max_tokens: 100
  });

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

## Response

```json theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Confidential AI is a privacy-first approach to inference..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 25,
    "total_tokens": 38
  }
}
```

<Warning>
  **Important: Parameter Difference for Newer Models**

  GPT-5, O3, and O4 models require `max_completion_tokens` instead of `max_tokens`:

  ```python theme={null}
  # ❌ Doesn't work for GPT-5/O3/O4
  client.chat.completions.create(
      model="openai/gpt-5",
      max_tokens=100  # Error: unsupported parameter
  )

  # ✅ Works for GPT-5/O3/O4
  client.chat.completions.create(
      model="openai/gpt-5",
      max_completion_tokens=100  # Correct parameter
  )

  # ℹ️ Older models (GPT-4.1, Claude, etc.) still use max_tokens
  ```

  **Affected models:**

  * `openai/gpt-5`, `openai/gpt-5-mini`, `openai/gpt-5-nano`
  * `openai/o3`, `openai/o4-mini`

  **Other models (use `max_tokens`):**

  * All GPT-4.1 models, Claude models, Gemini, DeepSeek, and GPU TEE models
</Warning>

## Streaming

Enable `stream: true` for real-time responses:

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

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

  ```javascript JavaScript theme={null}
  const stream = await client.chat.completions.create({
    model: 'openai/gpt-5',
    messages: [{ role: 'user', content: 'Write a story' }],
    stream: true
  });

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

## Vision (Multimodal)

Use vision models with images:

```python theme={null}
response = client.chat.completions.create(
    model="qwen/qwen3-vl-30b-a3b-instruct",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://..."}}
        ]
    }]
)
```

## Function Calling

Define tools/functions for the model to call:

```python theme={null}
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="openai/gpt-5",
    messages=[{"role": "user", "content": "What's the weather in SF?"}],
    tools=tools
)
```

<Card title="Function Calling Guide" icon="function" href="/guides/function-calling">
  Learn more about function calling →
</Card>

## Error Handling

<CodeGroup>
  ```python Python theme={null}
  try:
      response = client.chat.completions.create(...)
  except openai.AuthenticationError:
      print("Invalid API key")
  except openai.RateLimitError:
      print("Rate limit exceeded")
  except openai.BadRequestError as e:
      print(f"Bad request: {e}")
  ```

  ```javascript JavaScript theme={null}
  try {
    const response = await client.chat.completions.create(...);
  } catch (error) {
    if (error.status === 401) {
      console.error('Invalid API key');
    } else if (error.status === 429) {
      console.error('Rate limit exceeded');
    }
  }
  ```
</CodeGroup>

## Supported Models

* **GPU TEE**: `z-ai/glm-5.1`, `z-ai/glm-5`, `qwen/qwen3.5-27b`
* **OpenAI**: `openai/gpt-5`, `openai/gpt-5-mini`, `openai/o4-mini`
* **Anthropic**: `anthropic/claude-sonnet-4.5`, `anthropic/claude-opus-4.1`
* **Google**: `google/gemini-2.5-pro`
* **Meta**: `meta-llama/llama-3.3-70b-instruct`
* **A broad range of models**

<Card title="All Models" icon="list" href="/api-reference/models">
  View all supported models →
</Card>