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

# 创建对话

> 发送消息历史，获取完整回复或流式增量。

`POST /v1/chat/completions`

至少提供 `model` 和非空 `messages`。多轮对话时，把需要保留的历史消息按顺序一并发送；此接口不会自动为客户端保存会话历史。

## 读取结果

文本一般在 `choices[0].message.content`。同时检查 `finish_reason`：`stop` 是正常停止，`length` 表示达到上限，`tool_calls` 需要执行工具并回传结果。内容可能为 `null` 或为空。

设置 `stream: true` 后读取 `choices[].delta`，不要按完整 `message` 结构读取。工具调用、JSON 格式及生成上限参数由目标模型决定；不要默认同时设置 `max_tokens` 和 `max_completion_tokens`。

[HTTP 示例](/zh/guides/http) · [Python](/zh/guides/python) · [TypeScript](/zh/guides/typescript) · [流式输出](/zh/guides/streaming)

[Read in English](/en/api-reference/chat-completions)

## 缓存与推理字段

`prompt_cache_key`、`prompt_cache_retention` 是条件支持的上游提示，不是缓存命中或渠道固定承诺。当前普通 Chat DTO 未声明顶层 `prompt_cache_options`。`reasoning_effort` 使用模型支持的值；嵌套 `reasoning` 是按渠道方言转换的另一种输入，不要发送矛盾设置。

部分渠道返回 `message.reasoning_content` 或 `message.reasoning`，应与最终 `content` 区分。缓存与推理用量可出现在 `usage.prompt_tokens_details` 和 `completion_tokens_details` 中；这些字段可缺失，不能据此计算最终账单。

新增字段核对版本：`30a6d88a4`。

[提示词缓存](/zh/guides/prompt-caching) · [推理模型](/zh/guides/reasoning-models) · [上下文管理](/zh/guides/context-management)

## 采样、概率与条件字段

`seed`、`frequency_penalty`、`presence_penalty`、`logit_bias`、`logprobs` 和 `top_logprobs` 已在请求 DTO 中表达，仍需模型支持。适配器会移除部分不支持的采样字段。非流式 token 概率在 `choices[].logprobs.content`；流式位于每个 choice 的 `logprobs`。渠道强制格式化或协议转换不保证保留这些额外字段。

`web_search_options` 用于支持原生搜索的 Chat 模型，不能替代 Responses 的 `tools`。PDF 内容可使用 `type: file` 与嵌套 `file` 字段，但没有通用上传 API 或 OCR 回退。

[生成参数与示例](/zh/guides/generation-parameters) · [PDF 输入](/zh/guides/file-inputs) · [数据控制](/zh/guides/data-controls)

## 音频输入与预测输出

`messages[].content` 可包含 `type: input_audio` 与 `input_audio: {data, format}`；data 为纯 Base64，模型必须支持音频输入。不要使用音频转写的 multipart 结构。`modalities` / `audio` 请求字段依模型而定，不能保证所有转换路径或助手音频 ID 续聊。

`prediction` 是普通原生 Chat 可以转发的 JSON 字段，常用 `{type: content, content: 原文}`。它需要模型支持，当前 Chat → Responses 不映射该字段。非空文本仍需检查完成状态，并在使用生成的代码前审阅。

[音频输入示例](/zh/guides/audio-input) · [预测输出示例](/zh/guides/predicted-outputs) · [视频协议边界](/zh/guides/video-understanding)

## 工具策略与 JSON 模式

`tool_choice` 可请求 auto、required、none 或指定函数，`parallel_tool_calls: false` 请求单轮最多一个函数调用。字段形状、strict 转换限制与完整示例见 [工具控制](/zh/guides/tool-controls)。

JSON 模式只请求 JSON，不提供业务 Schema 保证；两个协议的字段形状和可运行示例见 [JSON 模式](/zh/guides/json-mode)。


## OpenAPI

````yaml openapi/relay.json POST /v1/chat/completions
openapi: 3.0.3
info:
  title: API — Core inference API
  version: 0.5.0
  description: >-
    面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire
    management or provider API.
  license:
    name: AGPL-3.0-or-later
servers:
  - url: https://gateway.example.com
    description: >-
      Example only; replace with your gateway origin and optional path prefix,
      without /v1.
security:
  - BearerAuth: []
paths:
  /v1/chat/completions:
    post:
      summary: 创建对话 / Create chat completion
      description: >-
        仅记录常用接入字段；可选参数和行为取决于模型、渠道与部署配置。 / Documents common integration fields;
        optional parameters and behavior depend on the model, channel, and
        deployment.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            example:
              model: YOUR_MODEL_ID
              messages:
                - role: user
                  content: Say hello in one short sentence.
      responses:
        '200':
          description: >-
            成功响应；stream=true 时返回 SSE，仍需检查终止事件。 / Successful response;
            stream=true returns SSE; still check terminal events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
              example:
                id: chatcmpl_example
                object: chat.completion
                created: 1700000000
                model: YOUR_MODEL_ID
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: Hello!
                    finish_reason: stop
                usage:
                  prompt_tokens: 12
                  completion_tokens: 3
                  total_tokens: 15
            text/event-stream:
              schema:
                type: string
              example: >+
                data:
                {"choices":[{"index":0,"delta":{"content":"Hello!"},"finish_reason":null}]}


                data:
                {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}


                data: [DONE]

        '400':
          description: 请求参数错误 / Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 身份校验失败 / Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 访问被拒绝 / Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 接口或资源不存在 / Endpoint or resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 请求被限流或受配额限制 / Rate or quota restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 网关或上游错误 / Gateway or upstream error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 服务暂不可用 / Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: 其他网关或上游错误；格式可能不同 / Other gateway or upstream error; shape may vary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ChatRequest:
      type: object
      properties:
        model:
          type: string
          description: >-
            模型列表返回的原始 ID；需要支持当前接口 / Exact ID from the model list; must support
            this endpoint
          example: YOUR_MODEL_ID
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Message'
        stream:
          type: boolean
          description: >-
            是否返回 SSE 事件；取决于模型和渠道支持 / Return SSE events when supported by the
            model and channel
          default: false
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
              description: >-
                请求流末尾的用量；部分渠道不支持 / Request final stream usage; not supported by
                every channel
            include_obfuscation:
              type: boolean
              description: 默认过滤；需渠道允许 / Filtered by default; channel permission required
          description: 仅在 stream=true 时使用 / Use with stream=true
        temperature:
          type: number
          description: >-
            采样温度；范围、默认值和是否可用由模型决定 / Sampling temperature; range, default, and
            support depend on the model
        top_p:
          type: number
          description: >-
            核采样；范围、默认值和是否可用由模型决定 / Nucleus sampling; range, default, and support
            depend on the model
        max_tokens:
          type: integer
          description: >-
            生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a
            smaller limit or parameter restrictions
          minimum: 0
          maximum: 1073741823
        max_completion_tokens:
          type: integer
          description: >-
            生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a
            smaller limit or parameter restrictions
          minimum: 0
          maximum: 1073741823
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: 停止序列；支持情况取决于模型 / Stop sequences; model dependent
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            auto / required / none 或指定函数；Chat 为嵌套 function.name，Responses 为同层
            name，需模型支持 / auto / required / none or a selected function; nested
            function.name in Chat, sibling name in Responses; requires model
            support
        response_format:
          type: object
          properties:
            type:
              type: string
              example: text
            json_schema:
              type: object
              additionalProperties: true
          description: >-
            输出格式；json_object / json_schema 需模型支持 / Output format; json_object /
            json_schema require model support；json_object 只请求 JSON，仍需校验业务字段 /
            json_object requests JSON only; validate business fields
        prompt_cache_key:
          type: string
          description: >-
            缓存分组提示；不保证命中、亲和或权限隔离 / Cache grouping hint; no guarantee of hits,
            affinity, or authorization isolation
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
        prompt_cache_retention:
          type: string
          description: >-
            缓存保留提示，值依赖上游模型；跨协议转换不保证保留 / Retention hint with model-dependent
            values; not guaranteed across conversion
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
        reasoning_effort:
          type: string
          description: >-
            原生 Chat 推理强度；模型名修饰符和转换可影响最终值，需模型支持 / Native Chat reasoning effort;
            modifiers and conversion can affect the effective value; model
            support required
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          example: medium
        reasoning:
          type: object
          description: >-
            OpenRouter 风格推理输入，按渠道方言转换；不是 Responses reasoning 结构 /
            OpenRouter-style reasoning input converted by channel dialect; not
            the Responses reasoning schema
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          properties:
            enabled:
              type: boolean
            effort:
              type: string
            max_tokens:
              type: integer
              description: >-
                推理预算，限制与归一化依赖模型和转换路径 / Reasoning budget; limits and
                normalization depend on model and conversion
            exclude:
              type: boolean
              description: >-
                控制推理内容可见性，不等于关闭推理 / Controls reasoning visibility, not disabling
                computation
          additionalProperties: true
        seed:
          type: number
          description: >-
            尽力复现的种子；建议整数，不能保证确定性 / Best-effort seed; use integers, not a
            determinism guarantee
        frequency_penalty:
          type: number
          description: >-
            频率惩罚；范围与支持依模型，显式零保留 / Frequency penalty; model-specific range and
            support; explicit zero retained
        presence_penalty:
          type: number
          description: >-
            出现惩罚；范围与支持依模型，显式零保留 / Presence penalty; model-specific range and
            support; explicit zero retained
        logprobs:
          type: boolean
          description: >-
            请求 token 对数概率；模型适配器可能移除 / Request token log probabilities; model
            adapter may remove it
        top_logprobs:
          type: integer
          description: >-
            候选数；需要 logprobs，范围与实际返回数依模型 / Alternative count; requires logprobs,
            limits and returned count depend on model
        service_tier:
          type: string
          description: >-
            默认过滤，需渠道允许和上游支持 / Filtered by default; requires channel permission
            and upstream support
        safety_identifier:
          type: string
          description: 默认过滤，需渠道允许 / Filtered by default; requires channel permission
        store:
          type: boolean
          description: >-
            默认允许；DisableStore 删除字段而非强制 false，不是保留策略保证 / Allowed by default;
            DisableStore removes rather than forces false; not a retention
            guarantee
        logit_bias:
          type: object
          additionalProperties:
            type: number
          description: >-
            以目标 tokenizer 的 token ID 为键，范围依模型 / Target-tokenizer token IDs as
            keys; model-specific ranges
        web_search_options:
          type: object
          properties:
            search_context_size:
              type: string
            user_location:
              type: object
              additionalProperties: true
          description: >-
            条件支持的 Chat 原生搜索结构，不是 Responses tools / Conditional native Chat
            search options, not Responses tools
        prediction:
          type: object
          description: >-
            原生 Chat 条件支持；转 Responses 当前无映射，不保证加速 / Conditional native Chat
            support; currently unmapped to Responses; no speedup guarantee
          properties:
            type:
              type: string
              example: content
            content:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: object
                    additionalProperties: true
          additionalProperties: true
          x-source-files:
            - relaykit/dto/openai_request.go
            - relay/channel/openai/adaptor.go
            - relaykit/relayconvert/internal/oai_chat/to_oai_responses_req.go
        modalities:
          type: array
          items:
            type: string
          description: >-
            目标输出模态，需模型与路径支持；本例仅文本 / Target output modalities; model/path
            dependent; example covers text only
        audio:
          type: object
          properties:
            voice:
              type: string
            format:
              type: string
          additionalProperties: true
          description: >-
            条件支持的音频输出选项，不是 input_audio 输入内容 / Conditional audio output options,
            not input_audio content
        parallel_tool_calls:
          type: boolean
          description: >-
            显式 false 请求单轮最多一个函数调用；模型/渠道条件支持，不调度应用并发 / Explicit false requests at
            most one function call per turn; model/channel dependent, not
            application concurrency control
      required:
        - model
        - messages
      x-source-files:
        - relaykit/dto/openai_request.go
        - relay/channel/openai/adaptor.go
        - relaykit/relayconvert/reasoning/intent.go
        - relaykit/relayconvert/internal/oai_responses/to_oai_chat_req.go
        - relaykit/relayconvert/internal/oai_chat/to_oai_responses_req.go
        - relay/channel/openai/relay-openai.go
        - relay/common/relay_info.go
    ChatResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/Message'
              finish_reason:
                type: string
                nullable: true
                description: >-
                  如 stop、length、tool_calls、content_filter / For example stop,
                  length, tool_calls, or content_filter
              logprobs:
                type: object
                nullable: true
                description: >-
                  可选 token 元数据；强制格式化和转换可能丢失 / Optional token metadata; may be
                  lost under forced formatting or conversion
                properties:
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        token:
                          type: string
                        logprob:
                          type: number
                        bytes:
                          type: array
                          nullable: true
                          items:
                            type: integer
                            minimum: 0
                            maximum: 255
                        top_logprobs:
                          type: array
                          items:
                            type: object
                            properties:
                              token:
                                type: string
                              logprob:
                                type: number
                              bytes:
                                type: array
                                nullable: true
                                items:
                                  type: integer
                                  minimum: 0
                                  maximum: 255
        usage:
          $ref: '#/components/schemas/ChatUsage'
      x-source-files:
        - relaykit/dto/openai_request.go
        - relay/channel/openai/relay-openai.go
        - relay/common/relay_info.go
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              nullable: true
              description: 错误标识；类型随上游变化 / Error identifier; type varies by upstream
    Message:
      type: object
      properties:
        role:
          type: string
          description: 消息角色，支持范围由模型决定 / Message role; support depends on the model
          example: user
        content:
          description: >-
            文本、模型支持的多模态内容块，或工具调用时的 null / Text, supported multimodal content
            blocks, or null for tool calls
          oneOf:
            - type: string
              nullable: true
            - type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  type:
                    type: string
                  input_audio:
                    type: object
                    required:
                      - data
                      - format
                    properties:
                      data:
                        type: string
                        description: >-
                          纯 Base64 音频，不带 Data URL 前缀 / Plain Base64 audio
                          without a Data URL prefix
                      format:
                        type: string
                        example: wav
                        description: >-
                          真实编码格式；需模型支持 / Actual encoding format; model support
                          required
        name:
          type: string
        tool_call_id:
          type: string
          description: tool 消息对应的工具调用 ID / Tool call ID for a tool message
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        reasoning_content:
          type: string
          description: >-
            部分渠道的推理文本扩展；不是最终回答，续聊语义由渠道决定 / Channel-specific reasoning text; not
            a final answer; replay semantics are channel dependent
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          nullable: true
        reasoning:
          type: string
          description: 部分渠道使用的推理文本别名 / Reasoning-text alias used by some channels
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          nullable: true
      required:
        - role
    Tool:
      type: object
      properties:
        type:
          type: string
          example: function
        function:
          type: object
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object
              description: 描述工具参数的 JSON Schema / JSON Schema describing tool arguments
              additionalProperties: true
            strict:
              type: boolean
              description: >-
                原生支持依模型；当前 Chat ↔ Responses 函数工具转换不复制此字段 / Native support
                depends on model; current Chat ↔ Responses function-tool
                conversion does not copy this field
          required:
            - name
      required:
        - type
        - function
    ChatUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type: object
          nullable: true
          properties:
            cached_tokens:
              type: integer
              description: >-
                报告的缓存读取 token；缺失不等于零，不代表最终账单 / Reported cache-read tokens;
                absence is not zero and this is not an invoice
              x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
              minimum: 0
            cache_write_tokens:
              type: integer
              description: >-
                支持渠道报告的缓存写入 token；不要跨协议机械相加 / Cache-write tokens reported by
                supporting channels; do not mechanically sum across protocols
              x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
              minimum: 0
          additionalProperties: true
        completion_tokens_details:
          type: object
          nullable: true
          properties:
            reasoning_tokens:
              type: integer
              description: >-
                报告的推理 token；可能缺失，不等同于可见文本长度 / Reported reasoning tokens; may be
                absent, not visible text length
              x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
              minimum: 0
          additionalProperties: true
      description: 用量字段随上游变化，不是最终账单 / Usage varies by upstream and is not an invoice
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          example: function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
              description: JSON 编码的参数字符串 / JSON-encoded argument string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

````

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