Skip to main content
Unlock richer conversational experiences by switching from legacy completions endpoints to the modern 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 older completions.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:
Or with a custom client name:
Console output:
Never commit your api_key to public repositories. Use environment variables or secret management tools.

Roles in Chat Messages

The messages array defines each turn in a conversation. Supported roles:
RolePurposeExample
systemSets global context, tone, or behavior for the assistant."You are a helpful assistant."
userEnd user’s input or question."What's the weather today?"
assistantModel’s prior responses in a multi-turn conversation."The weather is sunny and 75°F."
functionAllows the model to call a custom function you define."function_call": {"name": "get_weather", "arguments": {...}}

JavaScript Example


Adding a System Prompt in Python

Include both system and user messages to guide the model’s tone:
Console output:
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:
Experiment with these options for customized responses:
  • temperature: Controls randomness.
  • top_p: Nucleus sampling probability.
  • presence_penalty & frequency_penalty: Encourage topic variety.
  • functions & function_call: Invoke your own code.

Watch Video