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

# 通用对话

> 使用 OpenAI 兼容格式请求当前可用的文字模型。

使用 `POST /v1/chat/completions` 发送消息。请求头为 `Authorization: Bearer <本项目 API 密钥>` 和 `Content-Type: application/json`。

## 请求参数

| 参数 | 类型 | 说明 |
| - | - | - |
| `model` | string | 必填；请求使用的模型 ID，支持的模型见下方请求体说明。 |
| `messages` | array | 必填；按顺序传入对话消息，常用角色为 `system`、`user`、`assistant`。消息至少包含 `role` 和 `content`。 |
| `stream` | boolean | 可选；设为 `true` 时返回 SSE 事件流，省略或设为 `false` 时返回一次性 JSON。 |
| `temperature`、`top_p` | number | 可选；采样参数，具体取值和支持情况取决于模型。 |
| `max_tokens`、`max_completion_tokens` | integer | 可选；输出长度上限。按所选模型的要求选用，不需要同时传入。 |

## 非流式请求

```bash theme={null}
curl -sS 'https://ai.xbrod.com/v1/chat/completions' \
  -H 'Authorization: Bearer <本项目 API 密钥>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      { "role": "system", "content": "你是一个专业的 AI 助手。" },
      { "role": "user", "content": "介绍一下人工智能的发展历史。" }
    ],
    "stream": false
  }'
```

非流式响应为 JSON，通常从 `choices[0].message.content` 读取回复，并可查看 `usage` 了解 token 用量。下面仅展示主要字段：

```json theme={null}
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "人工智能的发展经历了多个阶段……" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 25, "completion_tokens": 50, "total_tokens": 75 }
}
```

## 流式请求

将请求体中的 `stream` 改为 `true`，并在命令中加入 `-N`，可逐条接收 `data:` 事件。逐步读取 `choices[0].delta`，直到收到 `data: [DONE]`。流式响应并非一次性 JSON；用量字段是否随流返回取决于模型及渠道。

```bash theme={null}
curl -sS -N 'https://ai.xbrod.com/v1/chat/completions' \
  -H 'Authorization: Bearer <本项目 API 密钥>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"你好"}],"stream":true}'
```


## OpenAPI

````yaml openapi.yaml POST /v1/chat/completions
openapi: 3.0.3
info:
  title: new-api public API (documentation preview)
  version: 0.1.0
  description: >-
    Gateway-facing contracts for the first set of documented models. The enabled
    models and billing depend on each deployment's settings.
servers:
  - url: https://ai.xbrod.com
    description: 本项目线上 API 地址
security:
  - bearerAuth: []
paths:
  /v1/chat/completions:
    post:
      summary: 生成文字对话
      description: OpenAI 兼容聊天接口。模型 ID 应在当前实例配置和密钥权限内；模型支持的可选参数可能不同。
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  example: deepseek-v4-pro
                  description: >
                    支持的模型包括：


                    -
                    OpenAI：`gpt-6-luna`、`gpt-6.1-sol`、`gpt-6-astra`、`gpt-6-sol`

                    - DeepSeek：`deepseek-v4-pro`、`deepseek-v4.1-flash`

                    - GLM：`glm-5.3`、`glm-5.3-flash`

                    -
                    MiMo：`mimo-v2.5`、`mimo-v2.5-pro`、`mimo-v2.6-flash`、`mimo-v2.6-pro`

                    - Qwen：`qwen3.8-max`、`qwen3.7-plus`、`qwen3.7-max`

                    - Kimi：`kimi-k3`

                    - MiniMax：`minimax-m3`

                    - Google Gemini：`gemini-3.8-flash`


                    更多模型持续更新中…
                messages:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - developer
                          - user
                          - assistant
                          - tool
                      content:
                        type: string
                stream:
                  type: boolean
                  description: 是否通过 SSE 流式输出。省略时为非流式，具体支持取决于所选渠道。
                temperature:
                  type: number
                  description: 采样温度；可选，仅在所选模型支持时使用。
                top_p:
                  type: number
                  description: 核采样参数；可选，仅在所选模型支持时使用。
                max_tokens:
                  type: integer
                  description: 最大生成 token 数；可选，部分模型使用 max_completion_tokens。
                max_completion_tokens:
                  type: integer
                  description: 最大生成 token 数；可选，部分模型使用 max_tokens。
            example:
              model: deepseek-v4-pro
              messages:
                - role: user
                  content: 你好
      responses:
        '200':
          description: 非流式时返回 OpenAI 兼容对话结果；流式时为事件流。
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  choices:
                    type: array
                    items:
                      type: object
        '400':
          description: 请求参数或模型不可用
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key created in this gateway, not a provider key.

````

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