-
You can paste the command below into your terminal to run your first API request.
-
Make sure to replace $OPENAI_API_KEY with your secret API key.
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Say this is a test!"}],
"temperature": 0.7
}'
This request queries the gpt-3.5-turbo model (which under the hood points to the latest gpt-3.5-turbo model variant) to complete the text starting with a prompt of "Say this is a test".
You should get a response back that resembles the following:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "gpt-3.5-turbo-0613",
"usage": {
"prompt_tokens": 13,
"completion_tokens": 7,
"total_tokens": 20
},
"choices": [
{
"message": {
"role": "assistant",
"content": "\n\nThis is a test!"
},
"finish_reason": "stop",
"index": 0
}
]
}
Now that you've generated your first chat completion, let's break down the response object.
We can see the finish_reason is stop which means the API returned the full chat completion generated by the model without running into any limits.
In the choices list, we only generated a single message but you can set the n parameter to generate multiple messages choices.
-
Represents a streamed chunk of a chat completion response returned by model, based on the provided input.
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{
"role":"assistant",
"content":""
},
"finish_reason":null
}]
}
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{
"content":"Hello"
},
"finish_reason":null
}]
}
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{
"content":"!"
},
"finish_reason":null
}]
}
....
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{
"content":" today"
},
"finish_reason":null
}]
}
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{
"content":"?"
},
"finish_reason":null
}]
}
{
"id":"chatcmpl-123",
"object":"chat.completion.chunk",
"created":1694268190,
"model":"gpt-3.5-turbo-0613",
"choices":[{
"index":0,
"delta":{},
"finish_reason":"stop"
}]
}
id string
A unique identifier for the chat completion. Each chunk has the same ID.
choices array
A list of chat completion choices. Can be more than one if n is greater than 1.
created integer
The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.
model string
The model to generate the completion.
object string
The object type, which is always chat.completion.chunk.
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
}'
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "gpt-3.5-turbo-0613",
"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
}
}
STREAMING
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
],
"stream": true
}'
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
....
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":" today"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"?"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
FUNCTION CALLING
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "What is the weather like in Boston?"
}
],
"functions": [
{
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
],
"function_call": "auto"
}'
{
"choices": [
{
"finish_reason": "function_call",
"index": 0,
"message": {
"content": null,
"function_call": {
"arguments": "{\n \"location\": \"Boston, MA\"\n}",
"name": "get_current_weather"
},
"role": "assistant"
}
}
],
"created": 1694028367,
"model": "gpt-3.5-turbo-0613",
"object": "chat.completion",
"usage": {
"completion_tokens": 18,
"prompt_tokens": 82,
"total_tokens": 100
}
}
messages array Required
A list of messages comprising the conversation so far. Example Python code.
model string Required
ID of the model to use. See the model endpoint compatibility table for details on which models work with the Chat API.
frequency_penalty number or null Optional Defaults to 0
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
function_call string or object Optional
Controls how the model calls functions.
"none" means the model will not call a function and instead generates a message.
"auto" means the model can pick between generating a message or calling a function.
Specifying a particular function via {"name": "my_function"} forces the model to call that function.
"none" is the default when no functions are present. "auto" is the default if functions are present.