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

# Chat Completions 对话

> Omniall AI 转发的 OpenAI Chat Completions 接口。支持多模态、流式、工具调用与结构化输出。



## OpenAPI

````yaml zh-CN/openapi/xgapi-public.yaml POST /v1/chat/completions
openapi: 3.0.3
info:
  title: Omniall AI 公开 API
  description: >-
    Omniall AI 公开 API。网站：https://omniall.ai — API 主机：https://api.omniall.ai —
    模型广场：https://omniall.ai/pricing
  version: 1.1.0
servers:
  - url: https://api.omniall.ai
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: Models
    description: 列出当前 API Key 可用的模型。
  - name: ChatGPT Chat Completions
    x-group: ChatGPT
    description: OpenAI Chat Completions 对话接口（`POST /v1/chat/completions`）。
  - name: Responses
    description: OpenAI Responses 接口（`POST /v1/responses`）。
  - name: Claude
    description: Anthropic Messages 消息接口（`POST /v1/messages`）。
  - name: Gemini
    description: Google Gemini 原生 generateContent / streamGenerateContent。
  - name: Images
    description: 图像生成（OpenAI Images）、各厂商说明与 Midjourney 代理接口。
  - name: Video
    description: 异步视频任务。
  - name: Audio
    description: 语音合成及相关音频接口。
  - name: Rerank
    description: 文档重排序。
paths:
  /v1/chat/completions:
    post:
      tags:
        - ChatGPT Chat Completions
      summary: Chat Completions 对话
      description: >
        Omniall AI 转发的 OpenAI Chat Completions API。


        **路径：** `POST https://api.omniall.ai/v1/chat/completions`


        兼容官方 OpenAI Chat Completions 协议。模型 ID
        请从[模型广场](https://omniall.ai/pricing)选取。


        ### 常见场景

        - **视觉理解**：在 `messages[].content` 中使用多模态 `image_url`

        - **文件分析**：`type: file` 内容块（上游模型支持时）

        - **联网搜索**：模型支持时使用 `web_search_options` / 厂商搜索字段

        - **Agent**：`tools` + `tool_choice` 函数调用循环

        - **流式输出**：`stream: true`（SSE）


        官方参考：https://platform.openai.com/docs/api-reference/chat
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              基础对话:
                summary: 基础对话
                value:
                  model: gpt-4o-mini
                  messages:
                    - role: user
                      content: 你好
              流式输出:
                summary: 流式输出
                value:
                  model: gpt-4o-mini
                  stream: true
                  stream_options:
                    include_usage: true
                  messages:
                    - role: user
                      content: 写一首短诗
              图像理解（Vision）:
                summary: 图像理解（Vision）
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: 这张图片里有什么？
                        - type: image_url
                          image_url:
                            url: https://example.com/photo.jpg
                            detail: auto
              文件 / PDF 分析:
                summary: 文件 / PDF 分析
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: 请总结这份 PDF
                        - type: file
                          file:
                            filename: report.pdf
                            file_data: data:application/pdf;base64,JVBERi0xLjQ...
              香蕉2.1_PDF_URL参考生图:
                summary: 香蕉 2.1 · PDF URL 参考生图
                value:
                  model: gemini-nano-banana-2.1
                  stream: true
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: 读取该 PDF，按页列出编号、颜色和形状，再生成一张白底参考图。
                        - type: file
                          file:
                            filename: reference.pdf
                            file_data: https://example.com/reference.pdf
                  extra_body:
                    google:
                      image_config:
                        aspect_ratio: '3:2'
                        image_size: 1K
              香蕉2.1_视频URL参考生图:
                summary: 香蕉 2.1 · 视频 URL 参考生图
                value:
                  model: gemini-nano-banana-2.1
                  stream: true
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: 观看视频，按场景顺序列出元素，再生成一张参考图。
                        - type: video_url
                          video_url: https://example.com/clip.mp4
                  extra_body:
                    google:
                      image_config:
                        aspect_ratio: '3:2'
                        image_size: 1K
              联网搜索（模型支持时）:
                summary: 联网搜索（模型支持时）
                value:
                  model: gpt-4o-search-preview
                  web_search_options:
                    search_context_size: medium
                  messages:
                    - role: user
                      content: 今天有哪些重要的 AI 产品发布？
              Agent / 函数调用:
                summary: Agent / 函数调用
                value:
                  model: gpt-4o
                  tools:
                    - type: function
                      function:
                        name: get_weather
                        description: 按城市查询天气
                        parameters:
                          type: object
                          properties:
                            city:
                              type: string
                          required:
                            - city
                  tool_choice: auto
                  messages:
                    - role: user
                      content: 东京天气怎么样？
              结构化 JSON 输出:
                summary: 结构化 JSON 输出
                value:
                  model: gpt-4o
                  response_format:
                    type: json_schema
                    json_schema:
                      name: movie
                      strict: true
                      schema:
                        type: object
                        properties:
                          title:
                            type: string
                          year:
                            type: integer
                        required:
                          - title
                          - year
                        additionalProperties: false
                  messages:
                    - role: user
                      content: 以 JSON 返回电影《盗梦空间》的信息
      responses:
        '200':
          description: Chat Completions JSON；当 `stream=true` 时为 SSE 流。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              example:
                id: chatcmpl-...
                object: chat.completion
                created: 1710000000
                model: gpt-4o-mini
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: Hello!
                    finish_reason: stop
                usage:
                  prompt_tokens: 10
                  completion_tokens: 4
                  total_tokens: 14
        '400':
          description: 请求体无效，或该模型不支持的参数。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '401':
          description: 缺少或无效的 API Key。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: '无效的令牌 (request id: ...)'
                  type: new_api_error
                  code: ''
        '403':
          description: 无权限（用户封禁、IP 白名单或分组访问限制）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '429':
          description: 触发速率限制。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '500':
          description: 上游或网关内部错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      description: >-
        OpenAI Chat Completions 请求体（POST /v1/chat/completions）。字段映射到网关
        GeneralOpenAIRequest。
      properties:
        model:
          type: string
          description: 模型广场 / `GET /v1/models` 中的模型 ID，须为当前 Key 可访问的模型。
          example: gpt-4o
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
          description: 完整对话历史，按时间从早到晚。按需包含 system/user/assistant/tool 轮次。
        stream:
          type: boolean
          description: 为 `true` 时返回 SSE（`chat.completion.chunk`），而非单个 JSON 对象。
          default: false
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
              description: 为 `true` 时在最终流式 chunk 中包含 token `usage`。
          description: 流式输出
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: 采样温度（约 0–2）。越高越随机；0 更稳定。
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: 核采样概率质量（0–1）。建议主要调 temperature 或 top_p 之一，勿同时大幅调整。
        top_k:
          type: integer
          description: 上游模型支持时的 Top-K 采样（部分 OpenAI 模型会忽略）。
        'n':
          type: integer
          minimum: 1
          description: 为该提示生成多少条补全（费用随 n 增加）。
        max_tokens:
          type: integer
          description: 旧版补全最大 token。新版 OpenAI 模型请优先用 `max_completion_tokens`。
        max_completion_tokens:
          type: integer
          description: 模型最多可生成的 token 数（新版 OpenAI 聊天模型推荐）。
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: 停止序列。生成到任一序列即结束。
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: 根据是否已出现过惩罚新 token（−2 到 2）。正值更鼓励新话题。
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: 按词频惩罚 token（−2 到 2）。正值减少重复。
        seed:
          type: number
          description: 厂商支持时的尽力确定性种子。
        user:
          type: string
          description: 用于滥用监控的稳定终端用户 id（不透明字符串）。请勿放入密钥。
        logit_bias:
          type: object
          additionalProperties:
            type: number
          description: token-id → 偏置映射，用于封禁/增强特定 token（厂商相关）。
        logprobs:
          type: boolean
          description: 是否返回输出 token 的对数概率。
        top_logprobs:
          type: integer
          description: 启用 logprobs 时每个位置返回的最可能 token 数。
        response_format:
          type: object
          description: 强制输出形态。json_object 要求合法 JSON；json_schema 要求符合你的 schema
          properties:
            type:
              type: string
              enum:
                - text
                - json_object
                - json_schema
            json_schema:
              type: object
              additionalProperties: true
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ChatTool'
          description: 可供模型在 Agent 流程中使用的函数工具。
        tool_choice:
          description: 控制工具使用：none / auto / required，或强制某个函数。
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
              additionalProperties: true
        parallel_tool_calls:
          type: boolean
          description: 模型是否可在一轮内调用多个工具。
        reasoning_effort:
          type: string
          enum:
            - low
            - medium
            - high
          description: o 系列 / 兼容模型的推理强度（low / medium / high）。
        modalities:
          type: array
          items:
            type: string
            enum:
              - text
              - audio
          description: 请求的输出模态，如 text、audio。
        audio:
          type: object
          additionalProperties: true
          description: 使用音频模态时的音频输出设置。
        web_search_options:
          type: object
          description: 模型支持搜索时的 OpenAI 风格联网选项。
          properties:
            search_context_size:
              type: string
              enum:
                - low
                - medium
                - high
              description: 检索多少搜索上下文：low / medium / high（成本/延迟权衡）。
            user_location:
              type: object
              additionalProperties: true
              description: 可选用户位置提示，用于本地化搜索结果。
        enable_search:
          description: 通义风格联网开关（视渠道/模型而定）。
          oneOf:
            - type: boolean
            - type: object
        web_search:
          description: 厂商特定联网对象（如百度）。
          type: object
          additionalProperties: true
        search_parameters:
          description: xAI 搜索参数对象。
          type: object
          additionalProperties: true
        thinking:
          description: 豆包 / 智谱思考控制。
          type: object
          additionalProperties: true
        enable_thinking:
          description: 通义思考开关。
          oneOf:
            - type: boolean
            - type: object
        extra_body:
          description: 额外厂商字段（OpenAI 兼容路径上有时用于 Gemini 相关选项）。
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
          description: 支持时任意元数据透传。
        prediction:
          type: object
          additionalProperties: true
          description: 可预知部分答案时的预测输出提示，用于降低延迟。
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: 唯一补全 id。
        object:
          type: string
          example: chat.completion
          description: 非流式时固定为 `chat.completion`。
        created:
          type: integer
          description: 补全创建时的 Unix 时间戳（秒）。
        model:
          type: string
          description: 产出回答的模型（可能反映路由结果）。
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: 候选索引，从 0 开始。
              message:
                $ref: '#/components/schemas/ChatMessage'
                description: 助手消息（`role`、`content`，可选 `tool_calls`）。
              finish_reason:
                type: string
                enum:
                  - stop
                  - length
                  - tool_calls
                  - content_filter
                description: 生成停止原因：stop、length、tool_calls、content_filter 等。
            description: 单个候选。
          description: 生成的候选（通常一条）。
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              description: 输入消息/工具消耗的 token。
            completion_tokens:
              type: integer
              description: 生成回答消耗的 token。
            total_tokens:
              type: integer
              description: prompt_tokens 与 completion_tokens 之和。
          description: 上游提供时的 token 用量。
        system_fingerprint:
          type: string
          description: 上游提供时的系统指纹（可复现性信号）。
      description: 非流式 Chat Completions 响应。
    OpenAIErrorResponse:
      type: object
      description: 鉴权或请求失败时返回的 OpenAI 风格错误包络。
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: 人类可读错误信息。网关可能附加 request id 便于排查。
            type:
              type: string
              description: 错误类型，常见为 `new_api_error`。
              example: new_api_error
            code:
              type: string
              description: 可选机器可读错误码（如 `access_denied`），可能为空字符串。
          description: 错误对象。
    ChatMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
            - developer
          description: 发言角色。system=全局指令；user=用户/应用输入；assistant=历史模型
        content:
          description: 消息正文。纯文本用字符串；多模态输入用 MessageContent 数组
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/MessageContent'
        name:
          type: string
          description: 可选发言者名称（部分厂商会为非 OpenAI 模型拼接该字段）。
        tool_calls:
          type: array
          items:
            type: object
          description: 当模型需要调用工具/函数时出现在助手消息上。
        tool_call_id:
          type: string
          description: 当 role 为 tool 时必填：本消息所应答的 tool_call id。
        reasoning_content:
          type: string
          description: 模型在最终答案之外单独返回的推理/思考文本。
      description: Chat Completions `messages` 数组中的一条消息。
    ChatTool:
      type: object
      properties:
        type:
          type: string
          example: function
          description: 通常为 function。
        function:
          type: object
          properties:
            name:
              type: string
              description: 模型将调用的函数名（稳定标识，勿含空格）。
            description:
              type: string
              description: 说明何时/为何调用该函数的自然语言描述。描述越清晰，工具选择越准。
            parameters:
              type: object
              additionalProperties: true
              description: 描述函数参数的 JSON Schema 对象。
          required:
            - name
          description: 函数定义。
      description: 模型可调用的函数工具（Agent / tool-calling）。
    MessageContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - input_audio
            - file
            - video_url
          description: 内容块类型。text=纯文本；image_url=视觉图像；file=文档（PDF 等）；
        text:
          type: string
          description: type 为 `text` 时的文本内容。
        image_url:
          type: object
          properties:
            url:
              type: string
              description: HTTPS 图片 URL 或 data URL（data:image/png;base64,...）。公开 URL 须可无鉴权
            detail:
              type: string
              enum:
                - auto
                - low
                - high
              description: 视觉细节等级：low（更快/更便宜）、high（更清晰）、auto（模型默认）。
          required:
            - url
          description: type 为 `image_url` 时的图像载荷。
        input_audio:
          type: object
          properties:
            data:
              type: string
              description: Base64 编码的音频字节。
            format:
              type: string
              example: wav
              description: 音频格式提示，如 `wav` 或 `mp3`。
          description: type 为 `input_audio` 时的音频载荷。
        file:
          type: object
          description: type 为 `file` 时的文件/文档载荷（模型支持时用于文档问答）。
          properties:
            filename:
              type: string
              description: 原始文件名，如 `report.pdf`（便于模型与日志）。
            file_data:
              type: string
              description: 文件内容（Base64 或 `data:` URL）。
            file_id:
              type: string
              description: 先前上传的文件 id（若走上传而非内联字节）。
        video_url:
          oneOf:
            - type: string
            - type: object
              properties:
                url:
                  type: string
          description: 当 type 为 video_url 且模型支持视频输入时的视频 URL（字符串或含 url 的对象）。
      description: 聊天消息中的一个多模态内容块。设置 type 并填写对应字段（text、image_url、
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '使用来自 https://omniall.ai/dashboard 的 Authorization: Bearer sk-...'

````

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