The Chat Completions API

The Chat Completions API is the foundational interface for communicating with OpenAI's language models. Every interaction follows a simple request-response pattern: you send a list of messages with assigned roles, and the API returns a completion.

The message array is the heart of every request. Each message has a role and content. The available roles are:

system / developer — High-level instructions shaping the model's behavior. Newer GPT-5.x models prefer developer.
user — Messages from the human end-user.
assistant — Previous model responses (used for multi-turn context).
tool — Results from tool/function calls, referencing a tool_call_id.

Request / Response Lifecycle

The basic flow is straightforward:

For streaming responses, you set stream: true and receive Server-Sent Events:

Minimal Python Example

The response includes a choices array (usually one element), each with a message object and a finish_reason indicating why generation stopped (stop, length, tool_calls, or content_filter). The usage object tells you exactly how many tokens were consumed.

Code

Request shape (HTTP)·text

Client → POST /v1/chat/completions (messages[], model, params)
       ← HTTP 200 { id, object, created, model, choices[], usage }

Streaming SSE shape·text

Client → POST /v1/chat/completions (stream: true)
       ← HTTP 200 text/event-stream
         data: {"id":"...","choices":[{"delta":{"content":"..."}}]}
         data: [DONE]

Minimal Python example·python

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from env

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "developer", "content": "You are a concise assistant."},
        {"role": "user", "content": "What is the speed of light?"},
    ],
    temperature=0.7,
    max_completion_tokens=200,
)

print(completion.choices[0].message.content)
print(f"Tokens used: {completion.usage.total_tokens}")
print(f"Finish reason: {completion.choices[0].finish_reason}")

Request / Response Lifecycle

Minimal Python Example

Code

External links

Exercise

Progress

Comments 0