chat.completions.create interface. This guide walks you through migrating your code, customizing your client, leveraging message roles, and fine-tuning parameters for GPT-3.5-Turbo, GPT-4, and beyond.
Why Migrate from Legacy Endpoints
OpenAI’s oldercompletions.create and Completion.create endpoints stopped receiving updates as of July 2023. The new chat completions API supports structured conversations with roles, function calls, and more control over model behavior.
Avoid using legacy calls: they no longer receive feature updates and may be removed in future releases.
Legacy Usage Examples
Modern Chat Completions
Switch to the chat API for richer, role-based interactions:Naming Your OpenAI Client
Feel free to name your client object whatever you like. Here’s a standard pattern:Never commit your
api_key to public repositories. Use environment variables or secret management tools.Roles in Chat Messages
Themessages array defines each turn in a conversation. Supported roles:
| Role | Purpose | Example |
|---|---|---|
| system | Sets global context, tone, or behavior for the assistant. | "You are a helpful assistant." |
| user | End user’s input or question. | "What's the weather today?" |
| assistant | Model’s prior responses in a multi-turn conversation. | "The weather is sunny and 75°F." |
| function | Allows the model to call a custom function you define. | "function_call": {"name": "get_weather", "arguments": {...}} |
JavaScript Example
Adding a System Prompt in Python
Include bothsystem and user messages to guide the model’s tone:
Place the
system message before the user message to ensure the context is applied first.Exploring the create Signature
The chat.completions.create method supports numerous parameters for fine-tuning:
- temperature: Controls randomness.
- top_p: Nucleus sampling probability.
- presence_penalty & frequency_penalty: Encourage topic variety.
- functions & function_call: Invoke your own code.