How to beginner · 3 min read

How to migrate from Assistants API to Responses API

Quick answer

To migrate from the Assistants API to the Responses API, replace calls to client.assistants.create() with client.responses.create() and update the request payload accordingly. The Responses API uses a simplified interface focused on generating chat completions with model and messages parameters.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the latest openai Python SDK version 1.0 or higher and set your API key as an environment variable.

bash

pip install --upgrade openai

Step by step migration

Here is a complete example showing how to migrate from the Assistants API to the Responses API using the openai Python SDK v1+.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Old Assistants API usage (deprecated):
# response = client.assistants.create(
#     assistant_id="your-assistant-id",
#     input={"text": "Hello, how are you?"}
# )
# print(response.choices[0].message.content)

# New Responses API usage:
response = client.responses.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, how are you?"}]
)
print(response.choices[0].message.content)

output

Hello! I'm doing well, thank you. How can I assist you today?

Common variations

Async usage: Use await client.responses.create(...) inside an async function.
Streaming: Add stream=True to client.responses.create() and iterate over the response.
Different models: Replace model="gpt-4o" with any supported model like gpt-4o-mini or claude-3-5-sonnet-20241022.

python

import asyncio
import os
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    
    # Async streaming example
    stream = await client.responses.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a joke."}],
        stream=True
    )
    async for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

asyncio.run(main())

output

Why did the scarecrow win an award? Because he was outstanding in his field!

Troubleshooting

If you get AttributeError: 'OpenAI' object has no attribute 'assistants', update your code to use client.responses.create() instead.
If the response is empty or missing, verify your messages parameter is correctly formatted as a list of role-content dicts.
Ensure your openai SDK is version 1.0 or higher to support the Responses API.

✅

Key Takeaways

Replace client.assistants.create() calls with client.responses.create() for migration.
Use the messages parameter with role-content dicts in the Responses API.
Update to openai SDK v1+ to access the new API methods.
Streaming and async usage are supported with client.responses.create().
Verify environment variables and SDK versions to avoid common errors.

Verified 2026-04 · gpt-4o, gpt-4o-mini, claude-3-5-sonnet-20241022

Verify ↗