Endpoints, parameters, streaming and error codes at a glance
The parameters that actually change behaviour, a working request in three languages, the error codes you will hit in production, and what to do about each one.
The ones that meaningfully change output. Everything else is situational.
| Parameter | What it does | Sensible default |
|---|---|---|
model |
Which model answers the request | The newest one you can afford |
messages |
The conversation so far, oldest first | system + user |
temperature |
Randomness. 0 = repeatable, 1 = creative | 0 for extraction, 0.7 for writing |
max_tokens |
Ceiling on the REPLY length only | Set it — an unbounded reply is a runaway bill |
stream |
Send tokens as they are produced | true for anything user-facing |
response_format |
Force valid JSON | {"type":"json_object"} for pipelines |
tools |
Functions the model may call | Only what this request could need |
seed |
Best-effort determinism | Set when you need reproducibility |
The smallest thing that works, with streaming on.
from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are concise."},
{"role": "user", "content": "Explain vector embeddings in two sentences."},
],
temperature=0.3,
max_tokens=300,
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const stream = await client.chat.completions.create({
model: 'gpt-4o',
messages: [
{ role: 'system', content: 'You are concise.' },
{ role: 'user', content: 'Explain vector embeddings in two sentences.' },
],
temperature: 0.3,
max_tokens: 300,
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}Rate limits are normal, not exceptional. Handle them from day one.
import time, random
def with_backoff(fn, attempts=5):
for i in range(attempts):
try:
return fn()
except Exception as e:
status = getattr(e, 'status_code', None)
if status not in (429, 500, 502, 503, 529) or i == attempts - 1:
raise
# full jitter: avoids a thundering herd on recovery
time.sleep(random.uniform(0, 2 ** i))https://api.openai.com/v1/chat/completionsSends a conversation and returns the next assistant message.
Auth: Bearer token in the Authorization header
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | yes | Model id, e.g. gpt-4o |
messages | array | yes | Ordered list of {role, content} |
temperature | number | no | 0–2. Lower is more deterministic |
max_tokens | integer | no | Ceiling on the reply |
stream | boolean | no | Server-sent events |
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}' {
"id": "chatcmpl-123",
"object": "chat.completion",
"model": "gpt-4o",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "Hello! How can I help?" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17 }
} | Code | Meaning | What to do |
|---|---|---|
401 | Bad or missing API key | Check the header name and that the key is not expired |
400 | Malformed request | Usually a bad messages array or an unknown parameter |
429 | Rate or quota limit | Exponential backoff with jitter; check your usage tier |
500 / 503 | Upstream failure | Retry idempotently; do not retry non-idempotent side effects |
context_length_exceeded | Prompt + reply exceeds the window | Trim history or summarise older turns |
You hit max_tokens. Check finish_reason — if it is "length", raise the ceiling or ask for a shorter answer.
No. It makes sampling greedy but hardware and model updates still introduce variance. Use seed for best-effort reproducibility.