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. This section contains endpoint-specific behavior, parameters, or usage notes for this API.

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 support the Chat API, see
the model endpoint compatibility table.
messages
array
[object]
Required
in
the chat format
to generate a chat completion message.
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
How many chat-completion choices to generate for each input message.
stream
boolean
Optional
If set, partial message deltas are streamed just like in ChatGPT. Tokens are sent as data-only
server-sent events
data: [DONE]
events as they become available, and the stream is terminated by a final message.
For sample code
, see the OpenAI Cookbook.
stop
string
Optional
Up to four stop sequences where the API stops generating additional tokens.
max_tokens
integer
Optional
The maximum number of tokens generated in the chat completion. The combined length of input tokens and generated tokens is limited by the model context length.
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
A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text, reducing the chance that the model repeats the same line verbatim.
See more details 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 in the tokenizer, to a bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model before sampling. The exact effect varies by model, but values between -1 and 1 usually reduce or increase the chance of selection; values such as -100 or 100 should result in the associated token being banned or exclusively selected.
user
string
Optional
A unique identifier representing your end user, which can help OpenAI monitor and detect abuse.
Learn more
。
Example
{
"model"
:
"gpt-4o"
,
"stream"
:
false
,
"messages"
:
[
{
"role"
:
"user"
,
"content"
:
[
{
"type"
:
"text"
,
"text"
:
  // provider-specific example normalized for English documentation
}
,
{
"type"
:
"image_url"
,
"image_url"
:
{
"url"
:
"https://github.com/dianping/cat/raw/master/cat-home/src/main/webapp/images/logo/cat_logo03.png"
}
}
]
}
]
,
"max_tokens"
:
400
}

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",
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
  // provider-specific example normalized for English documentation
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://github.com/dianping/cat/raw/master/cat-home/src/main/webapp/images/logo/cat_logo03.png"
                    }
                }
            ]
        }
    ],
    "max_tokens": 400
}'

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
    }
}