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

# Chat Completions

> 通用 Chat API 是与模型无关的接口，兼容 OpenAI Chat Completions 请求结构。传入 model id 和 messages，并可选择以服务器发送事件（SSE）流的方式返回。

* 适用于大多数 LLM 的统一聊天 API 接口；哪些模型支持见 [LLM 模型](https://docs.poyo.ai/zh/api-manual/chat-series/overview.md)
* 通过 model 参数选择不同的 AI 模型
* 兼容 OpenAI Chat Completions API 格式

## 使用示例

### 基础对话

```json theme={null} theme={"dark"}
{
  "model": "gpt-5.2",
  "messages": [
    {"role": "user", "content": "Explain vector databases in one sentence."}
  ]
}
```

### 系统提示词

```json theme={null} theme={"dark"}
{
  "model": "claude-sonnet-4-5-20250929",
  "messages": [
    {"role": "system", "content": "You are a technical editor. Improve clarity of product copy."},
    {"role": "user", "content": "Rewrite the button text 'Submission failed' to be friendly and actionable."}
  ]
}
```

### 多轮对话

```json theme={null} theme={"dark"}
{
  "model": "gemini-3-flash-preview",
  "messages": [
    {"role": "user", "content": "Give me 3 customer support bot names."},
    {"role": "assistant", "content": "1) HelpWave 2) CarePilot 3) SwiftSupport"},
    {"role": "user", "content": "Add one style tag for each name."}
  ]
}
```

### 流式输出

```json theme={null} theme={"dark"}
{
  "model": "gpt-5.2",
  "messages": [
    {"role": "user", "content": "Generate 5 short titles (max 6 words) about AI video generation."}
  ],
  "stream": true
}
```

## 注意事项

* 使用 `stream: true` 获取 SSE 流式响应。
* 不同模型支持的上下文长度、输出上限和可选参数可能不同。
* 对于需要工具或多模态结构化输入的新 OpenAI 兼容工作流，请使用 Responses API。

## 响应

非流式请求直接返回 Chat Completions 对象，不带 `code` / `data` 包装。DeepSeek 等推理模型还会在 `choices[].message.reasoning_content` 中返回推理文本，并计入 `usage.completion_tokens_details.reasoning_tokens`。

## 流式输出

设置 `"stream": true` 时，响应为 `text/event-stream`。每个事件是一行包含 `chat.completion.chunk` 对象的 `data:`，流以 `data: [DONE]` 结束：

```text theme={"dark"}
data: {"id":"...","object":"chat.completion.chunk","model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant"}}]}
data: {"id":"...","object":"chat.completion.chunk","model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"OK"}}]}
data: {"id":"...","object":"chat.completion.chunk","model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":"stop"}],"usage":{"prompt_tokens":36,"completion_tokens":16,"total_tokens":52}}
data: [DONE]
```

* 文本在 `choices[0].delta.content` 中返回。推理模型会先流式返回 `choices[0].delta.reasoning_content`。
* 最后一个 chunk 携带 `finish_reason` 和 `usage`。

## 错误

* `401`：缺少 API Key 或 API Key 无效。
* `400`：参数无效，或模型不支持 Chat Completions（例如 `gpt-5-6-sol` 只支持 Responses）。错误信息会列出支持的 URI。
* `404`：未知的 model id。

响应体示例见[错误码](https://docs.poyo.ai/zh/api-manual/error-codes.md#llm-接口错误)，哪些模型支持此格式见 [LLM 模型](https://docs.poyo.ai/zh/api-manual/chat-series/overview.md)。


## OpenAPI

````yaml zh/api-manual/chat-series/chat-completions.json POST /v1/chat/completions
openapi: 3.0.0
info:
  title: 通用对话 API
  description: >-
    通用对话 API 是一个与模型无关的接口，兼容 OpenAI Chat Completions 的请求格式。传入 model id 和
    messages，并可选择以 server-sent events 流式返回。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /v1/chat/completions:
    post:
      tags:
        - Text Series
      summary: 通用对话 API
      description: 兼容 OpenAI 的 Chat Completions 接口。
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: 基础对话补全
                value:
                  model: gpt-5.2
                  messages:
                    - role: system
                      content: >-
                        You are a structured output assistant. Reply with JSON
                        only.
                    - role: user
                      content: >-
                        Generate a paginated list response example with fields
                        items, page, page_size, total and sample values.
      responses:
        '200':
          description: 补全已创建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
              examples:
                success:
                  summary: 成功响应
                  value:
                    id: chatcmpl-9876543210
                    object: chat.completion
                    created: 1677652288
                    model: gpt-5.2
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: >-
                            The history of artificial intelligence (AI) dates
                            back to the 1950s...
                        finish_reason: stop
                    usage:
                      prompt_tokens: 28
                      completion_tokens: 320
                      total_tokens: 348
        '400':
          description: 请求参数无效，或模型不支持此 API 格式
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoyoValidationError'
        '401':
          description: API Key 缺失或无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoyoAuthError'
        '404':
          description: 未知的 model id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFormatError'
              example:
                error:
                  message: 'Model not found: no-such-model'
                  type: invalid_request_error
                  code: model_not_found
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: >-
            模型名称。示例：`gpt-5.2`、`claude-sonnet-4-5-20250929`、`gemini-3-flash-preview`。
          example: gpt-5.2
        messages:
          type: array
          description: >-
            对话消息列表。每条消息包含 `role` 和 `content`。`system` 用于定义模型行为，`user`
            用于用户输入，`assistant` 用于多轮对话中模型之前的回复。示例：[{"role": "user", "content":
            "Explain vector databases in one sentence."}]。
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: 控制输出的随机性，范围 0-2。较低的值（如 0.2）使输出更确定，较高的值（如 1.8）使输出更随机。默认值：1.0。
          example: 1
        max_tokens:
          type: integer
          minimum: 1
          description: 生成的最大 token 数。不同模型的上限不同。
          example: 256
        stream:
          type: boolean
          description: 是否使用流式输出。`true` 以 SSE 格式返回流式响应，`false` 一次性返回完整响应。默认值：false。
          example: false
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            核采样参数，范围 0-1。控制生成文本的多样性。建议只使用 `top_p` 或 `temperature`
            其中之一，不要同时使用。默认值：1.0。
          example: 1
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: 频率惩罚，范围 -2.0 到 2.0。正值会降低重复相同词语的可能性。默认值：0。
          example: 0
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: 存在惩罚，范围 -2.0 到 2.0。正值会提高谈论新话题的可能性。默认值：0。
          example: 0
        stop:
          description: 停止序列。最多 4 个，遇到其中任一序列时停止生成。
          oneOf:
            - type: string
              example: |-


                Human:
            - type: array
              items:
                type: string
        'n':
          type: integer
          minimum: 1
          description: 生成的补全数量。默认值：1。必须是普通数字，如 `1`，不要加引号。
          example: 1
    ChatCompletion:
      type: object
      properties:
        id:
          type: string
          description: 响应的唯一标识符。
          example: chatcmpl-9876543210
        object:
          type: string
          description: 对象类型。
          example: chat.completion
        created:
          type: integer
          description: 创建时间戳。
          example: 1677652288
        model:
          type: string
          description: 实际使用的模型名称。
          example: gpt-5.2
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    PoyoValidationError:
      type: object
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        error:
          type: object
          properties:
            message:
              type: string
              example: 'Invalid request parameters: messages: Field required'
            type:
              type: string
              example: validation_error
            details:
              type: object
              description: 字段级校验错误（如有）。
    PoyoAuthError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        error:
          type: object
          properties:
            message:
              type: string
              example: Invalid API key
            type:
              type: string
              example: authentication_error
    UpstreamFormatError:
      type: object
      description: 模型或请求在此 API 格式下被拒绝时返回的错误。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 'Model not found: no-such-model'
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_not_found
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
          description: >-
            消息角色。`user` 为用户输入，`assistant` 为多轮对话中模型之前的输出，`system` 为系统提示词。默认为
            `user`。
          default: user
          example: user
        content:
          type: string
          description: 消息内容、问题或指令。
          example: Explain vector databases in one sentence.
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
          example: 0
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          description: 结束原因。
          enum:
            - stop
            - length
            - content_filter
            - function_call
          example: stop
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: 输入消息的 token 数。
          example: 28
        completion_tokens:
          type: integer
          description: 生成内容的 token 数。
          example: 320
        total_tokens:
          type: integer
          description: token 总数。
          example: 348
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.