Document Utilities
OpenAI API Reference
OpenAI's /v1/chat/completions endpoint is designed for conversational generation where you pass
ordered messages and receive a model-generated assistant reply. It is one of the most common interfaces used to build
chat assistants, coding copilots, and automation agents.
Endpoint Summary
- Method: POST
- URL:
https://api.openai.com/v1/chat/completions - Auth:
Authorization: Bearer OPENAI_API_KEY - Body Type: JSON
Core Request Fields
| Field | Type | Purpose |
|---|---|---|
model |
string | Target model name for inference. |
messages |
array | Conversation turns using role + content. |
temperature |
number | Controls randomness and creativity. |
max_tokens |
integer | Caps generated output length. |
VS Code Style cURL Example
# Chat Completions request
curl -X POST "https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1-mini",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain vector databases in 3 bullet points."}
],
"temperature": 0.4,
"max_tokens": 220
}'
VS Code Style Python Example
import requests
url = "https://api.openai.com/v1/chat/completions"
headers = {
"Authorization": "Bearer OPENAI_API_KEY",
"Content-Type": "application/json",
}
payload = {
"model": "gpt-4.1-mini",
"messages": [
{"role": "system", "content": "You are an API explainer."},
{"role": "user", "content": "Compare REST and GraphQL."},
],
"temperature": 0.5,
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])
Response Anatomy
The response typically includes id, created, model, and a choices
array. The first generated text is usually read from choices[0].message.content. Token usage metadata
is provided for monitoring cost and throughput.
Implementation tip: Always validate status codes and parse errors before trusting model output.