Create a model response for the given chat conversation.
openapi-spec
openapi: 3.1.0
info:
  title: Chat Completions API
  description: Create chat completions using GPT and other models
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  description: ID of the model to use
                  example: "gpt-4"
                messages:
                  type: array
                  description: A list of messages comprising the conversation
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum: [system, user, assistant]
                        description: The role of the message author
                      content:
                        type: string
                        description: The content of the message
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 1
                  description: Sampling temperature between 0 and 2
                max_tokens:
                  type: integer
                  minimum: 1
                  description: Maximum number of tokens to generate
                top_p:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 1
                  description: Nucleus sampling parameter
                frequency_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                  default: 0
                  description: Frequency penalty
                presence_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                  default: 0
                  description: Presence penalty
                stream:
                  type: boolean
                  default: false
                  description: Whether to stream responses
            example:
              model: "gpt-4"
              messages:
                - role: "system"
                  content: "You are a helpful assistant."
                - role: "user"
                  content: "Hello!"
              temperature: 0.7
              max_tokens: 1000
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Key
  schemas:
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the completion
        object:
          type: string
          description: Object type
        created:
          type: integer
          description: Unix timestamp
        model:
          type: string
          description: Model used
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/ChatUsage'
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          type: object
          properties:
            role:
              type: string
            content:
              type: string
        finish_reason:
          type: string
          enum: [stop, length, content_filter, tool_calls]
    ChatUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

​
Overview

The Chat Completions API allows you to generate text responses using various AI models. It supports multi-turn conversations with system, user, and assistant messages.

​
Authentication

All requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Example

curl -X POST https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7
  }'

​
Response Example

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 9,
    "total_tokens": 28
  }
}

​
Parameters

ParameterTypeRequiredDefaultDescription
modelstringYes-ID of the model to use
messagesarrayYes-List of messages in the conversation
temperaturenumberNo1Sampling temperature (0-2), higher values make output more random, lower values make it more focused
max_tokensintegerNoinfMaximum tokens to generate
top_pnumberNo1Nucleus sampling parameter, not recommended to modify both temperature and top_p
nintegerNo1Number of chat completion choices to generate for each input message
streambooleanNofalseEnable streaming responses
stopstring/arrayNonullUp to 4 sequences where the API will stop generating further tokens
frequency_penaltynumberNo0Frequency penalty (-2 to 2), positive values decrease likelihood of repeating the same line
presence_penaltynumberNo0Presence penalty (-2 to 2), positive values increase likelihood of talking about new topics
logit_biasobjectNonullModify the likelihood of specified tokens appearing in the completion
userstringNo-Unique identifier representing your end-user
response_formatobjectNo-Specify output format, set {"type": "json_object"} to enable JSON mode
toolsarrayNo-List of tools the model may call
tool_choiceobjectNoautoControls which function the model calls

​
Available Models

  • gpt-4
  • gpt-4-turbo
  • gpt-3.5-turbo
  • gpt-4o
  • gpt-4o-mini
  • gpt-4-gizmo-* (GPTs models)