> ## 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 a text completion

> Prompt requests, text output, and SSE completion fields.

`POST /v1/completions`

Send an explicit model and text `prompt`; `stream` selects SSE. This contract limits the example to one text prompt and one output.

Read `choices[].text` for both JSON and streaming increments. The example accepts `finish_reason=stop`; length limits or filtering are not complete answers. Model capabilities and optional field preservation depend on the channel. See the [guide and example](/en/guides/legacy-completions).

[阅读中文版](/zh/api-reference/completions)


## OpenAPI

````yaml openapi/relay.json POST /v1/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/completions:
    post:
      summary: 创建文本补全 / Create a text completion
      description: >-
        发送明确模型和文本 `prompt`，可用 `stream` 选择 SSE。本规范限定单条文本、单个输出。 / Send an explicit
        model and text `prompt`; `stream` selects SSE. This contract limits the
        example to one text prompt and one output.
      operationId: completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                prompt:
                  type: string
                stream:
                  type: boolean
              additionalProperties: true
              required:
                - model
                - prompt
      responses:
        '200':
          description: >-
            读取业务字段，不只检查 HTTP 状态 / Validate business fields, not only HTTP
            status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  choices:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        text:
                          type: string
                        finish_reason:
                          type: string
                      additionalProperties: true
                      required:
                        - index
                        - text
                        - finish_reason
                additionalProperties: true
                required:
                  - choices
              example:
                id: cmpl_example
                object: text_completion
                created: 1700000000
                model: YOUR_MODEL_ID
                choices:
                  - index: 0
                    text: ' explain completion states.'
                    finish_reason: stop
            text/event-stream:
              schema:
                type: string
              example: >+
                data:
                {"choices":[{"index":0,"text":"Hello","finish_reason":null}]}


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


                data: [DONE]

        default:
          description: 错误格式与状态取决于入口 / Error status and shape depend on the entry.
components:
  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.