Chat Completions
The core API pattern: send a list of messages, receive an assistant reply.
Syntax
POST /v1/chat { model, messages, ...params }Almost every modern LLM API uses the chat completions pattern. You send a JSON request containing a list of messages, and the API returns the model's next message.
The request has three essentials
- model — which model to use.
- messages — the conversation so far.
- optional parameters like temperature and max tokens.
The response contains the generated message plus metadata such as how many tokens were used.
Example
curl https://api.example-llm.com/v1/chat \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "llm-medium",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a todo app."}
]
}'When to use it
- A customer-service platform sends user messages to the chat completions endpoint to generate instant, context-aware replies.
- A writing assistant calls the chat completions API whenever a user clicks 'Improve this paragraph' to return a polished version.
- An internal knowledge-base tool wraps every employee question in a chat completions request to produce human-readable answers from policy documents.
More examples
Minimal chat completion request
The simplest possible chat completions call: one user message, one model, no extra parameters.
curl https://api.openai.com/v1/chat/completions \
-H 'Authorization: Bearer $OPENAI_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "What is the capital of Japan?"}]
}'Python chat completion and read reply
Shows how to send a system + user message and extract the text from the response object.
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': 'What is the capital of Japan?'}
]
)
print(response.choices[0].message.content)Inspect full completion response shape
Dumps the full response to JSON so you can inspect every field including id, model, usage, and choices.
from openai import OpenAI
import json
client = OpenAI()
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
# View the raw response structure
print(json.dumps(response.model_dump(), indent=2))
Discussion