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

# 聊天补全

> 使用 OpenAI 兼容接口创建聊天补全。

使用这个接口发起聊天补全请求。

所有请求都使用 Bearer Token 鉴权。基础地址为 `https://api.kie.ai`。


## OpenAPI

````yaml api-reference/openapi.json POST /v1/chat/completions
openapi: 3.0.1
info:
  title: OpenAI 兼容文字模型调用接口
  version: 1.0.0
  description: >-
    面向第三方开发者的 OpenAI 兼容文字模型调用文档，仅覆盖本网关当前公开支持的文本接口 `/v1/chat/completions`。


    所有接口默认使用 `Authorization: Bearer <token>` 鉴权。启用流式返回时，响应内容类型为
    `text/event-stream`，事件数据格式与 OpenAI Chat Completions 兼容。


    说明：网关会对接多家上游模型服务，因此某些模型可能支持额外透传字段。本文档仅描述跨模型最常用、最稳定的公共字段，适合作为开发者集成入口文档。
  license:
    name: Project License
    url: https://github.com/QuantumNous/new-api/blob/main/LICENSE
servers:
  - url: https://api.kie.ai
    description: 正式环境
security: []
tags:
  - name: Text Model
    description: OpenAI 兼容的文字模型调用接口
paths:
  /v1/chat/completions:
    post:
      tags:
        - Text Model
      summary: 创建聊天补全
      description: >-
        使用消息数组创建一次聊天补全响应，兼容 OpenAI Chat Completions API。


        适用场景：多轮对话、系统提示词控制、函数/工具调用、结构化输出。若将 `stream` 设为 `true`，服务会返回 Server-Sent
        Events (`text/event-stream`)。
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basicChat:
                summary: 基础对话请求
                value:
                  model: gpt-4.1
                  messages:
                    - role: system
                      content: You are a concise assistant.
                    - role: user
                      content: 用一句话解释什么是向量数据库。
                  temperature: 0.3
                  max_completion_tokens: 256
              toolCalling:
                summary: 带工具定义的请求
                value:
                  model: gpt-4.1
                  messages:
                    - role: user
                      content: 帮我查询北京今天的天气。
                  tools:
                    - type: function
                      function:
                        name: get_weather
                        description: 根据城市名查询实时天气
                        parameters:
                          type: object
                          properties:
                            city:
                              type: string
                              description: 城市名称
                          required:
                            - city
                  tool_choice: auto
                  stream: false
      responses:
        '200':
          description: 请求成功。非流式时返回标准 JSON；流式时返回 SSE 事件流。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              examples:
                success:
                  summary: 非流式成功响应
                  value:
                    id: chatcmpl_123
                    object: chat.completion
                    created: 1742342400
                    model: gpt-4.1
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: 向量数据库是一种专门存储和检索向量表示的数据系统，常用于语义搜索和 RAG。
                        finish_reason: stop
                    usage:
                      prompt_tokens: 24
                      completion_tokens: 26
                      total_tokens: 50
                      prompt_tokens_details:
                        cached_tokens: 0
                        text_tokens: 24
                        audio_tokens: 0
                        image_tokens: 0
                      completion_tokens_details:
                        text_tokens: 26
                        audio_tokens: 0
                        reasoning_tokens: 0
            text/event-stream:
              schema:
                type: string
                description: >-
                  SSE 数据流。每个事件的 `data:` 部分可反序列化为 `ChatCompletionChunk`；结束时通常返回
                  `data: [DONE]`。
              examples:
                stream:
                  summary: 流式响应片段
                  value: >
                    data:
                    {"id":"chatcmpl_123","object":"chat.completion.chunk","created":1742342400,"model":"gpt-4.1","choices":[{"index":0,"delta":{"role":"assistant","content":"向量数据库"},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_123","object":"chat.completion.chunk","created":1742342400,"model":"gpt-4.1","choices":[{"index":0,"delta":{"content":"用于语义检索。"},"finish_reason":"stop"}]}


                    data: [DONE]
        '400':
          description: 请求参数不合法，例如缺少必填字段、JSON 格式错误或字段类型不匹配。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  summary: 请求参数错误
                  value:
                    error:
                      message: messages is required
                      type: invalid_request_error
                      param: messages
                      code: bad_request_body
        '401':
          description: 鉴权失败，例如未提供令牌或令牌无效。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: 未授权
                  value:
                    error:
                      message: 无效的令牌
                      type: new_api_error
                      param: ''
                      code: access_denied
        '429':
          description: 触发速率限制或账户额度不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rateLimited:
                  summary: 速率限制
                  value:
                    error:
                      message: 请求过于频繁，请稍后再试
                      type: new_api_error
                      param: ''
                      code: insufficient_user_quota
      security:
        - BearerAuth: []
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      description: Chat Completions 请求体。
      properties:
        model:
          type: string
          description: 要调用的模型 ID，例如 `gpt-4.1`。
        messages:
          type: array
          description: 对话历史消息数组，按时间顺序排列。
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          description: 采样温度。越低越稳定，越高越发散。
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 0.95
          description: 核采样参数。通常与 `temperature` 二选一调优。
        top_k:
          type: integer
          description: 部分兼容模型支持的 Top-K 采样参数。
        'n':
          type: integer
          description: 要生成的候选响应数量。
        stream:
          type: boolean
          description: 是否启用流式输出。为 `true` 时响应内容类型为 `text/event-stream`。
          default: true
        stream_options:
          $ref: '#/components/schemas/StreamOptions'
        stop:
          description: 停止序列。可以是单个字符串，也可以是字符串数组。
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        max_tokens:
          type: integer
          description: 兼容旧接口的最大输出 token 数。
        max_completion_tokens:
          type: integer
          description: 推荐使用的最大生成 token 数。显式传 `0` 也会按请求透传。
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: 存在惩罚。值越高，越鼓励模型引入新话题。
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: 频率惩罚。值越高，越抑制重复表达。
        tools:
          type: array
          description: 可供模型调用的工具定义列表。
          items:
            $ref: '#/components/schemas/ToolDefinition'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        response_format:
          $ref: '#/components/schemas/ResponseFormat'
        seed:
          type: number
          description: 部分模型支持的随机种子，用于提升结果可复现性。
        reasoning_effort:
          type: string
          enum:
            - low
            - medium
            - high
          description: 推理强度，仅支持推理控制的模型生效。
        parallel_tool_calls:
          type: boolean
          description: 是否允许模型并行发起多个工具调用。
        user:
          description: 调用方用户标识。不同上游可能要求字符串或对象，本网关按原值透传。
          oneOf:
            - type: string
            - type: object
        metadata:
          type: object
          description: 与本次请求关联的自定义元数据。
        store:
          description: 是否允许上游存储该请求/响应数据。不同兼容目标可能返回布尔值或对象语义。
          oneOf:
            - type: boolean
            - type: object
    ChatCompletionResponse:
      type: object
      description: 非流式 Chat Completions 响应。
      properties:
        id:
          type: string
          description: 响应 ID。
        object:
          type: string
          example: chat.completion
          description: 对象类型，固定为 `chat.completion`。
        created:
          type: integer
          description: Unix 时间戳（秒）。
        model:
          type: string
          description: 实际使用的模型 ID。
        choices:
          type: array
          description: 模型生成的候选结果列表。
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
        system_fingerprint:
          type: string
          nullable: true
          description: 系统指纹。若上游未返回，该字段可能缺失或为 `null`。
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      description: 统一错误响应格式。
    ChatMessage:
      type: object
      required:
        - role
        - content
      description: 聊天消息对象。
      properties:
        role:
          type: string
          enum:
            - system
            - developer
            - user
            - assistant
            - tool
          description: 消息角色。`developer` 通常用于 GPT-5 等支持开发者消息的模型。
        content:
          description: 消息内容。可以直接是字符串，也可以是多模态分片数组。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ChatMessageContentPart'
        name:
          type: string
          description: 发送者名称。通常用于区分同角色的不同消息源。
        tool_calls:
          type: array
          description: 助手消息中声明的工具调用列表。
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
          description: 工具响应消息对应的工具调用 ID，仅 `tool` 角色消息使用。
        reasoning_content:
          type: string
          description: 部分兼容模型返回的推理内容。普通调用方通常无需依赖此字段。
    StreamOptions:
      type: object
      description: 流式响应附加选项。
      properties:
        include_usage:
          type: boolean
          description: 若为 `true`，流结束前会额外返回一次带 `usage` 的事件。
    ToolDefinition:
      type: object
      required:
        - type
        - function
      description: 请求中可供模型调用的工具定义。
      properties:
        type:
          type: string
          example: function
          description: 工具类型。当前最常见的是 `function`。
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    ToolChoice:
      description: 控制模型如何选择工具。
      oneOf:
        - type: string
          enum:
            - none
            - auto
            - required
        - type: object
          description: 指定某个工具必须被调用。
          properties:
            type:
              type: string
              example: function
            function:
              type: object
              properties:
                name:
                  type: string
                  description: 指定要调用的函数名。
    ResponseFormat:
      type: object
      description: 控制响应格式，例如纯文本、JSON 对象或 JSON Schema 约束输出。
      properties:
        type:
          type: string
          enum:
            - text
            - json_object
            - json_schema
          description: 目标输出格式。
        json_schema:
          type: object
          description: 当 `type` 为 `json_schema` 时使用的 JSON Schema 定义。
    ChatCompletionChoice:
      type: object
      description: 单个聊天补全候选结果。
      properties:
        index:
          type: integer
          description: 候选结果下标。
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          description: 结束原因，例如 `stop`、`length`、`tool_calls` 或 `content_filter`。
    Usage:
      type: object
      description: Token 用量统计。不同兼容格式返回的字段可能略有差异。
      properties:
        prompt_tokens:
          type: integer
          description: Chat Completions 等接口中的输入 token 数。
        completion_tokens:
          type: integer
          description: Chat Completions 等接口中的输出 token 数。
        total_tokens:
          type: integer
          description: 总 token 数。
        prompt_cache_hit_tokens:
          type: integer
          description: 命中缓存的输入 token 数，仅部分模型返回。
        prompt_tokens_details:
          $ref: '#/components/schemas/InputTokenDetails'
        completion_tokens_details:
          $ref: '#/components/schemas/OutputTokenDetails'
        input_tokens:
          type: integer
          description: Responses API 风格中的输入 token 数。
        output_tokens:
          type: integer
          description: Responses API 风格中的输出 token 数。
        input_tokens_details:
          $ref: '#/components/schemas/InputTokenDetails'
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
          description: 面向调用方的错误描述。
        type:
          type: string
          description: 错误类型，例如 `invalid_request_error`、`new_api_error` 或上游兼容错误类型。
        param:
          type: string
          nullable: true
          description: 与错误直接相关的参数名；若没有明确参数，可为空字符串或 `null`。
        code:
          type: string
          nullable: true
          description: 错误码。为兼容不同上游，文档中按字符串描述；若没有错误码则可能为 `null`。
    ChatMessageContentPart:
      type: object
      required:
        - type
      description: 聊天消息内容分片。
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - input_audio
            - file
            - video_url
          description: 分片类型。文字模型场景最常用的是 `text`。
        text:
          type: string
          description: 文本内容。当 `type` 为 `text` 时使用。
        image_url:
          $ref: '#/components/schemas/ImageURLPart'
        input_audio:
          $ref: '#/components/schemas/InputAudioPart'
        file:
          $ref: '#/components/schemas/FilePart'
        video_url:
          $ref: '#/components/schemas/VideoURLPart'
    ToolCall:
      type: object
      description: 模型返回的工具调用信息。
      properties:
        id:
          type: string
          description: 工具调用唯一 ID。
        type:
          type: string
          description: 工具调用类型，通常为 `function`。
        function:
          $ref: '#/components/schemas/FunctionCall'
    FunctionDefinition:
      type: object
      required:
        - name
      description: 函数工具定义。
      properties:
        name:
          type: string
          description: 函数名称。模型调用时会引用该名称。
        description:
          type: string
          description: 函数用途描述，帮助模型选择与构造调用。
        parameters:
          type: object
          description: JSON Schema 格式的参数定义。
    InputTokenDetails:
      type: object
      description: 输入 token 明细。
      properties:
        cached_tokens:
          type: integer
          description: 命中缓存的输入 token 数。
        text_tokens:
          type: integer
          description: 文本输入 token 数。
        audio_tokens:
          type: integer
          description: 音频输入 token 数。
        image_tokens:
          type: integer
          description: 图像输入 token 数。
    OutputTokenDetails:
      type: object
      description: 输出 token 明细。
      properties:
        text_tokens:
          type: integer
          description: 文本输出 token 数。
        audio_tokens:
          type: integer
          description: 音频输出 token 数。
        reasoning_tokens:
          type: integer
          description: 推理型模型内部消耗的 reasoning token 数。
    ImageURLPart:
      type: object
      description: 图像输入分片，可用于支持多模态输入的文字模型。
      properties:
        url:
          type: string
          description: 图像 URL 或 base64 数据。
        detail:
          type: string
          enum:
            - low
            - high
            - auto
          description: 图像解析粒度。
    InputAudioPart:
      type: object
      description: 音频输入分片。
      properties:
        data:
          type: string
          description: Base64 编码的音频数据。
        format:
          type: string
          enum:
            - wav
            - mp3
          description: 音频格式。
    FilePart:
      type: object
      description: 文件输入分片。
      properties:
        filename:
          type: string
          description: 文件名。
        file_data:
          type: string
          description: 文件内容，通常是 base64 或文本。
        file_id:
          type: string
          description: 已上传文件的标识符。
    VideoURLPart:
      type: object
      description: 视频输入分片。
      properties:
        url:
          type: string
          description: 视频 URL。
    FunctionCall:
      type: object
      description: 模型发起的函数调用。
      properties:
        name:
          type: string
          description: 函数名称。
        arguments:
          type: string
          description: 以 JSON 字符串形式编码的函数参数。
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: '在请求头中传入 `Authorization: Bearer <token>`。'

````