POST /v1/chat/completions

Method: POSTEndpoint: /v1/chat/completions

Official GuideOfficial API Documentation All chat models can use this interface. Change the model field to the target model name. Given a prompt, the model returns one or more predicted completions and can also return the probabilities of alternative tokens at each position. Create a completion for the provided prompt and parameters.

Request Parameters

Header Parameters

Content-Type
string
Required
Example:
application/json
Accept
string
Required
Example:
application/json
Authorization
string
Optional
Default Value:
Bearer {{YOUR_API_KEY}}

Body Parameters application/json

model
string
Required
The ID of the model to use. For details about which models work with the Chat API, see the model endpoint compatibility table.
messages
array
[object]
Required
The list of messages included in the conversation so far. See the Python example.
role
string
Optional
content
string
Optional
temperature
integer
Optional
Sampling temperature to use, between 0 and 2. Higher values such as 0.8 make the output more random, while lower values such as 0.2 make it more focused and deterministic. We usually recommend changing this or
top_p
but not both.
top_p
integer
Optional
An alternative to temperature sampling called nucleus sampling, where the model considers the tokens whose total probability mass reaches top_p. A value of 0.1 means only the tokens comprising the top 10% probability mass are considered. We usually recommend changing this or
temperature
but not both.
n
integer
Optional
Defaults to 1.
How many chat-completion choices to generate for each input message.
stream
boolean
Optional
Defaults to false. If set, partial message deltas are streamed like in ChatGPT. Tokens are sent as data-only server-sent events as they become available, and the stream ends with a data: [DONE] message. See the Python example.
stop
string
Optional
Defaults to null. Up to four sequences where the API stops generating additional tokens.
max_tokens
integer
Optional
Defaults to inf.
Maximum tokens generated in the chat completion.
The total length of input tokens and generated tokens is limited by the model context length. See the Python example for token counting.
presence_penalty
number
Optional
A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they have already appeared in the text so far, increasing the chance that the model talks about new topics.
See more details about frequency and presence penalties.
frequency_penalty
number
Optional
Defaults to 0. A number between -2.0 and 2.0. Positive values penalize new tokens based on their current frequency in the text, reducing the chance that the model repeats the same line. See more about frequency and presence penalties.
logit_bias
null
Optional
Changes the likelihood that specified tokens appear in the completion.
Accepts a JSON object that maps tokens, identified by token IDs from the tokenizer, to a bias value between -100 and 100. Mathematically, the bias is added to the model logits before sampling. The exact effect varies by model, but values between -1 and 1 usually reduce or increase the chance of selecting the associated token, while values such as -100 or 100 should effectively ban or exclusively select it.
user
string
Optional
A unique identifier representing your end user, which can help OpenAI monitor and detect abuse.
Learn more
。
response_format
object
Optional
Object specifying the format that the model must output. Setting { "type": "json_object" } enables JSON mode, which ensures the generated message is valid JSON. Important: when using JSON mode, you must also instruct the model through a system or user message to generate JSON. Otherwise, the model may emit endless whitespace until the token limit is reached, making the request appear stalled. Also note that if finish_reason="length", the message content may be cut off because generation exceeded max_tokens or the conversation exceeded the maximum context length. See attributes.
seen
integer
Optional
This feature is in beta. If specified, the system makes a best effort to sample deterministically so repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed, and you should use the system_fingerprint response field to monitor backend changes.
tools
array
[string]
Required
A list of tools the model can call. At present, only functions are supported as tools. Use this to provide a list of functions for which the model can generate JSON inputs.
tool_choice
object
Required
Controls which function the model calls, if any. none means the model does not call a function and instead generates a message. auto means the model may choose between generating a message and calling a function. Use {"type": "function", "function": {"name": "my_function"}} to force a specific function call. If no functions are provided, the default is none. If functions are present, the default is auto. See possible types.
Example
{
"model"
:
"gpt-4o-2024-08-06"
,
"messages"
:
[
{
"role"
:
"system"
,
"content"
:
"You are a helpful math tutor. Guide the user through the solution step by step."
}
,
{
"role"
:
"user"
,
"content"
:
  // provider-specific example normalized for English documentation
}
]
,
"response_format"
:
{
"type"
:
"json_schema"
,
"json_schema"
:
{
"name"
:
"math_reasoning"
,
"schema"
:
{
"type"
:
"object"
,
"properties"
:
{
"steps"
:
{
"type"
:
"array"
,
"items"
:
{
"type"
:
"object"
,
"properties"
:
{
"explanation"
:
{
"type"
:
"string"
}
,
"output"
:
{
"type"
:
"string"
}
}
,
"required"
:
[
"explanation"
,
"output"
]
,
"additionalProperties"
:
false
}
}
,
"final_answer"
:
{
"type"
:
"string"
}
}
,
"required"
:
[
"steps"
,
"final_answer"
]
,
"additionalProperties"
:
false
}
,
"strict"
:
true
}
}
}

Example Request

Shell

curl --location --request POST '/v1/chat/completions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-4o-2024-08-06",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful math tutor. Guide the user through the solution step by step."
    },
    {
      "role": "user",
  // provider-specific example normalized for English documentation
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_reasoning",
      "schema": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "explanation": {
                  "type": "string"
                },
                "output": {
                  "type": "string"
                }
              },
              "required": [
                "explanation",
                "output"
              ],
              "additionalProperties": false
            }
          },
          "final_answer": {
            "type": "string"
          }
        },
        "required": [
          "steps",
          "final_answer"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}'

Response

🟢 200 OK

Content Type: application/json

Response Schema

id
string
Required
object
string
Required
created
integer
Required
choices
array
[object]
Required
index
integer
Optional
message
object
Optional
finish_reason
string
Optional
usage
object
Required
prompt_tokens
integer
Required
completion_tokens
integer
Required
total_tokens
integer
Required

Example

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\n\nHello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}