Chat completions are the most common AI API endpoint. Understanding how to use them effectively is the foundation of building with AI.

The Messages Array

Chat APIs use an array of messages with roles:

• system — Sets the AI's behavior, personality, and constraints. Sent once at the beginning.
• user — The end user's input.
• assistant — The AI's previous responses. Include these for multi-turn conversations.

const messages = [
  { role: "system", content: "You are a concise technical writer." },
  { role: "user", content: "What is REST?" },
  { role: "assistant", content: "REST is an architectural style for web APIs..." },
  { role: "user", content: "How does it compare to GraphQL?" }
];

System Prompts

The system prompt is your most powerful tool for controlling output. Be specific:

• Define the persona and expertise level
• Set formatting rules (JSON, markdown, bullet points)
• Establish guardrails (what topics to avoid, length limits)
• Provide examples of desired output

Parameters That Matter

• temperature (0-2) — Lower = more focused, higher = more creative. Use 0 for data extraction, 0.7 for general chat, 1+ for creative writing.
• max_tokens — Cap on response length. Important for cost control.
• top_p — Alternative to temperature for controlling randomness. Usually use one or the other, not both.
• stop — Sequences that cause the model to stop generating. Useful for structured outputs.

Handling Responses

const response = await fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ model: "gpt-5", messages, temperature: 0.7 })
});

const data = await response.json();
const reply = data.choices[0].message.content;
const tokensUsed = data.usage.total_tokens;

Streaming Responses

For better UX, stream responses so users see text appearing in real-time:

• Set stream: true in your request
• Parse Server-Sent Events (SSE) from the response
• Each event contains a small chunk of the response
• Append chunks to the UI as they arrive

Error Handling

Common errors and how to handle them:

• 429 Rate Limited — Implement exponential backoff and retry
• 400 Bad Request — Check your message format and token limits
• 401 Unauthorized — Verify your API key
• 500 Server Error — Retry with backoff; switch to a fallback model if persistent