CHAPTER 3: THE CORE CHAT COMPLETIONS API: Parameters, Roles, and Messages

Master the foundational OpenAI Chat Completions API. Learn how to structure message payloads using system, user, and assistant roles, and fine-tune response generation using parameters like temperature, top_p, and max_tokens.

πŸ’¬ The Heart of OpenAI: Chat Completions

The Chat Completions API is the primary interface for interacting with OpenAI's frontier models. Unlike older text-completion endpoints that took a raw string and appended text, chat models accept an array of structured messages grouped by specific roles (`system`, `user`, `assistant`). This design allows developers to maintain conversation history, enforce behavior guidelines, and precisely control generation parameters.

1. Understanding Message Roles (`system`, `user`, `assistant`)
The architectural division of conversation roles used to guide model behavior and maintain dialogue context.
Message Roles Matrix
OPENAI MESSAGE ROLES:
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ ROLE                   β”‚ PURPOSE                          β”‚ EXAMPLE USAGE                              β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ `system`               β”‚ Sets overall behavior, persona,  β”‚ `"You are a senior Python code reviewer."` β”‚
β”‚                        β”‚ and safety boundaries.           β”‚                                            β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ `user`                 β”‚ Represents the end-user query or β”‚ `"Can you refactor this sorting function?"`β”‚
β”‚                        β”‚ instruction sent to the model.   β”‚                                            β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ `assistant`            β”‚ Represents prior model responses β”‚ `"Here is the refactored function..."`     β”‚
β”‚                        β”‚ used to maintain conversation    β”‚                                            β”‚
β”‚                        β”‚ history across turns.            β”‚                                            β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Architectural Definition: Structuring inputs across distinct roles allows the model to differentiate between behavioral instructions (`system`) and active queries (`user`).
2. Core Generation Parameters
Controlling randomness, output length, and sampling diversity via request parameters (`temperature`, `top_p`, `max_tokens`).
Generation Parameters Reference
CHAT COMPLETIONS PARAMETERS:
- `model`: Specifies the model identifier (e.g., `"gpt-4o"`).
- `temperature`: Controls randomness (`0.0` = deterministic and focused, `1.0` = creative and varied).
- `top_p`: Nucleus sampling alternative to temperature; `0.1` means only tokens comprising the top 10% probability mass are considered.
- `max_tokens`: Limits the maximum number of generated output tokens per response.
- `n`: Number of chat completion choices to generate for each input message.
Engineering Insight: Setting `temperature=0.0` is essential for deterministic tasks like data extraction, JSON generation, and code translation.
3. Python Code Example: Executing a Chat Completion Request
A production Python script demonstrating how to call the Chat Completions API with system/user messages and generation parameters.
Python (chat_completion_demo.py)
from openai import OpenAI

def run_chat_completion():
    client = OpenAI()
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a concise technical writing assistant."},
            {"role": "user", "content": "What is the difference between synchronous and asynchronous execution in 2 sentences?"}
        ],
        temperature=0.3,
        max_tokens=150
    )
    
    # Extract assistant reply content
    assistant_reply = response.choices[0].message.content
    print("[+] Assistant Response:")
    print(assistant_reply)
    
    # Inspect token usage statistics
    print(f"\n[+] Token Usage: Prompt={response.usage.prompt_tokens}, Completion={response.usage.completion_tokens}, Total={response.usage.total_tokens}")

if __name__ == "__main__":
    run_chat_completion()
Execution Output: [+] Assistant Response: Synchronous execution blocks program flow, waiting for each task to complete sequentially before proceeding. Asynchronous execution allows tasks to run concurrently in the background, enabling programs to handle multiple operations without blocking. [+] Token Usage: Prompt=31, Completion=43, Total=74
4. Best Practices for Chat API Requests
Software engineering standards for structuring prompts, managing token limits, and handling API responses.
Chat API Best Practices Checklist
CHAT API BEST PRACTICES CHECKLIST:
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ BEST PRACTICE          β”‚ IMPLEMENTATION & OBJECTIVE                                                    β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Always Define System   β”‚ Provide a clear `system` prompt to establish output formatting, persona,      β”‚
β”‚ Prompts                β”‚ and refusal boundaries.                                                       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Monitor Token Usage    β”‚ Inspect `response.usage` objects to track token consumption and stay within   β”‚
β”‚                        β”‚ model context window limits.                                                  β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Handle Finish Reasons  β”‚ Check `response.choices[0].finish_reason` (e.g., `'stop'` vs `'length'`) to   β”‚
β”‚                        β”‚ verify whether generation completed fully or hit `max_tokens` limits.         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Masterclass Rule: Inspecting `finish_reason` ensures your application detects when model responses are truncated due to `max_tokens` thresholds.
5. Chapter Summary & Next Steps
Reviewing chat completion fundamentals and previewing response streaming.
Chapter Review Checklist
CHAPTER REVIEW CHECKLIST:
1. The Chat Completions API accepts an array of messages categorized by `system`, `user`, and `assistant` roles.
2. Parameters like `temperature` and `max_tokens` control output randomness and length.
3. Response objects contain choices, generated content, and detailed token usage metrics.
4. Next Chapter: We cover Chapter 4 ("Real-Time Streaming Responses with Server-Sent Events (SSE)").
Next Chapter Preview: In Chapter 4, we explore real-time response streamingβ€”learning how to stream tokens chunk by chunk using Server-Sent Events for lightning-fast user interfaces.