> ## 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.

# Create chat completion

> Send message history and receive a response or streamed deltas.

`POST /v1/chat/completions`

Provide `model` and a nonempty `messages` array. For multi-turn conversations, include the relevant history in order; this endpoint does not automatically retain conversation history for the client.

## Read the result

Text normally appears in `choices[0].message.content`. Also check `finish_reason`: `stop` is a normal stop, `length` indicates a limit, and `tool_calls` requires executing tools and sending results back. Content may be null or empty.

With `stream: true`, read `choices[].delta` instead of complete messages. Tool calling, JSON output, and generation-limit parameters depend on the model. Do not assume `max_tokens` and `max_completion_tokens` can be set together.

[HTTP examples](/en/guides/http) · [Python](/en/guides/python) · [TypeScript](/en/guides/typescript) · [Streaming](/en/guides/streaming)

[简体中文](/zh/api-reference/chat-completions)

## Cache and reasoning fields

`prompt_cache_key` and `prompt_cache_retention` are conditional upstream hints, not guarantees of cache hits or pinned channels. The current ordinary Chat DTO does not declare top-level `prompt_cache_options`. Use model-supported `reasoning_effort` values. Nested `reasoning` is an alternative input converted by channel dialect; avoid conflicting settings.

Some channels return `message.reasoning_content` or `message.reasoning`; distinguish these from final `content`. Cache and reasoning usage may appear in `usage.prompt_tokens_details` and `completion_tokens_details`. These fields can be absent and cannot determine a final invoice.

Added fields verified against revision `30a6d88a4`.

[Prompt caching](/en/guides/prompt-caching) · [Reasoning](/en/guides/reasoning-models) · [Context management](/en/guides/context-management)

## Sampling, probabilities, and conditional fields

The request DTO represents `seed`, `frequency_penalty`, `presence_penalty`, `logit_bias`, `logprobs`, and `top_logprobs`; model support is still required. Adapters remove some unsupported sampling fields. Non-streaming probabilities appear in `choices[].logprobs.content`; streaming uses each choice's `logprobs`. Forced formatting or protocol conversion does not guarantee preservation of these extra fields.

`web_search_options` is for Chat models with native search support, not a replacement for Responses `tools`. PDF content can use `type: file` with nested `file` fields, without a general upload API or OCR fallback.

[Generation parameters and example](/en/guides/generation-parameters) · [PDF input](/en/guides/file-inputs) · [Data controls](/en/guides/data-controls)

## Audio input and predicted output

`messages[].content` can include `type: input_audio` and `input_audio: {data, format}`, with plain Base64 data and a model supporting audio input. Do not use transcription's multipart structure. Request-level `modalities` / `audio` are model dependent and do not guarantee every conversion path or assistant audio-ID continuation.

`prediction` is a JSON field ordinary native Chat can forward, commonly `{type: content, content: originalText}`. It requires model support and currently has no Chat-to-Responses mapping. Still check completion and review generated code before using it.

[Audio input example](/en/guides/audio-input) · [Prediction example](/en/guides/predicted-outputs) · [Video protocol boundaries](/en/guides/video-understanding)

## Tool policies and JSON mode

`tool_choice` can request auto, required, none, or a selected function. `parallel_tool_calls: false` requests at most one function call per turn. See [tool controls](/en/guides/tool-controls) for protocol shapes, strict conversion limits, and a complete example.

JSON mode requests JSON without a business Schema guarantee. See [JSON mode](/en/guides/json-mode) for both protocol shapes and runnable examples.


## 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.