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

# Chat Completions

> OpenAI 兼容的聊天补全 API

认证和模型列表请参考 [概述](/api-reference/openai/overview)。

## 端点

```
POST https://api.pipellm.ai/v1/chat/completions
```

<Note>
  这条 free route 只接受 OpenAI 兼容格式请求，并只路由到 OpenAI 兼容平台。
  如果你想保留 OpenAI 格式去调用 Anthropic 或 Gemini 模型，请使用
  [OpenAI Format Converter](/converter/openai-format.zh)。
</Note>

## 代码示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.pipellm.ai/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $PIPELLM_API_KEY" \
      -d '{
        "model": "gpt-4o",
        "max_completion_tokens": 1024,
        "messages": [
          {
            "role": "user",
            "content": "Why is the sky blue?"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
      api_key=os.getenv('PIPELLM_API_KEY'),
      base_url='https://api.pipellm.ai/v1'
    )

    response = client.chat.completions.create(
      model='gpt-4o',
      messages=[
        {
          'role': 'user',
          'content': 'Why is the sky blue?'
        }
      ]
    )
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    import OpenAI from 'openai';

    const client = new OpenAI({
      apiKey: process.env.PIPELLM_API_KEY,
      baseURL: 'https://api.pipellm.ai/v1'
    });

    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [
        {
          role: 'user',
          content: 'Why is the sky blue?'
        }
      ]
    });
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
      "context"
      "os"
      openai "github.com/sashabaranov/go-openai"
    )

    func main() {
      config := openai.DefaultConfig(os.Getenv("PIPELLM_API_KEY"))
      config.BaseURL = "https://api.pipellm.ai/v1"
      client := openai.NewClientWithConfig(config)

      resp, _ := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
          Model: "gpt-4o",
          Messages: []openai.ChatCompletionMessage{
            {
              Role:    openai.ChatMessageRoleUser,
              Content: "Why is the sky blue?",
            },
          },
        },
      )
    }
    ```
  </Tab>
</Tabs>

## 请求参数

| 参数            | 类型      | 必需 | 描述                         |
| ------------- | ------- | -- | -------------------------- |
| `model`       | string  | 是  | 模型 ID（如 `gpt-4o`、`grok-2`） |
| `messages`    | array   | 是  | 消息对象数组                     |
| `max_tokens`  | integer | 否  | 最大生成 token 数               |
| `temperature` | number  | 否  | 采样温度（0-2）                  |
| `stream`      | boolean | 否  | 启用流式响应                     |

## 响应格式

```json theme={null}
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The sky appears blue because..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60
  }
}
```

## Function Calling

Function Calling 允许模型生成结构化的 JSON 来调用代码中的函数。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    tools = [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取指定地点的当前天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "城市名称"}
            },
            "required": ["location"]
          }
        }
      }
    ]

    response = client.chat.completions.create(
      model="gpt-4.1",
      messages=[{"role": "user", "content": "东京现在天气怎么样？"}],
      tools=tools,
      tool_choice="auto"
    )

    if response.choices[0].message.tool_calls:
      tool_call = response.choices[0].message.tool_calls[0]
      # 执行你的函数并返回结果
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const tools = [
      {
        type: "function",
        function: {
          name: "get_weather",
          description: "获取指定地点的当前天气",
          parameters: {
            type: "object",
            properties: {
              location: { type: "string", description: "城市名称" }
            },
            required: ["location"]
          }
        }
      }
    ];

    const response = await client.chat.completions.create({
      model: 'gpt-4.1',
      messages: [{ role: 'user', content: '东京现在天气怎么样？' }],
      tools: tools,
      tool_choice: 'auto'
    });

    if (response.choices[0].message.tool_calls) {
      const toolCall = response.choices[0].message.tool_calls[0];
      // 执行你的函数并返回结果
    }
    ```
  </Tab>
</Tabs>

<Card title="Function Calling 官方文档" icon="book" href="https://platform.openai.com/docs/guides/function-calling">
  完整的函数定义和响应处理指南
</Card>