In the previous lesson, we learned how to initialize and configure the OpenAI Python client. But creating a client is only the starting point. An AI application becomes useful when it sends a request, receives a model-generated result, and knows how to work with that result. The Responses API provides a unified interface for this interaction. In this beginner tutorial, we’ll focus on text requests, the essential request parameters, two input formats, and the structure of the returned response object.
By the end, you’ll be able to call client.responses.create(), inspect useful response fields, and understand why response.output_text is often the simplest way to display generated text. We will introduce instructions and message-style inputs briefly; their deeper meaning and conversation design belong to the next lesson.
1. What is the OpenAI Responses API?
The Responses API is an OpenAI API interface for creating model responses. It supports more than basic text generation including multimodal inputs and tool use but those advanced capabilities are outside the scope of this lesson. Here we use it to submit a text prompt and read the generated result.
The distinction between the SDK client and the Responses API matters. The Python client is a local object that handles API communication. client.responses.create() is a method on that client which sends a request to the remote API. The API then returns a structured response, which the SDK represents as a Python object.
2. How a Responses API request works
flowchart LR
subgraph APP["Python Application"]
A["Your Code"] --> B["OpenAI Client"]
end
B -->|"Responses request"| C["OpenAI API"]
C -->|"Response data"| B
B -->|"Response object"| AThe OpenAI SDK executes inside your Python application. Your code supplies the model name and input, the client sends the HTTP request, and the API returns structured response data. Your application then reads the response object’s fields. The model runs remotely on the API side; it is not embedded inside the SDK.
3. Prepare your Python project
This lesson builds on the environment from Blog 02 — Install the OpenAI Python SDK and Make Your First API Call. You need Python 3.10 or newer, an API key with access to your selected model, and the following packages installed in your active virtual environment:
pip install --upgrade openai python-dotenv
Create a project-root .env file:
OPENAI_API_KEY=your_openai_api_key_here
- Keep
.envout of Git by adding it to.gitignore - publish only an
.env.examplewith placeholder values. - API requests may incur charges, so check model availability and pricing before running examples.
4. Your first Responses API request
Create main.py:
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI()
response = client.responses.create(
model="gpt-4.1-mini",
input="Explain REST APIs in two simple sentences.",
)
print(response.output_text)
- The call to
load_dotenv()loads the local environment configuration.OpenAI()readsOPENAI_API_KEYautomatically. - The
responses.create()method then sends the request -
response.output_textprovides a convenient text representation of the model’s answer. The actual wording will vary between runs
5. Understand the key request parameters
A request may have many options, but beginners should start with the parameters that directly affect what is requested.
| Parameter | Purpose | Example |
|---|---|---|
model | Selects the model to call | "gpt-4.1-mini" |
input | Supplies text or structured input items | "Explain REST APIs" |
instructions | Gives high-level directions for how the model should respond | "Explain concepts for beginners." |
max_output_tokens | Sets an upper bound on tokens generated for the response | 150 |
- The
modelandinputfields are the main focus of our examples. instructionscan guide tone and behavior- while
max_output_tokenshelps cap generated output. It is a token limit, not an exact word count.
For example, you can guide a response without changing the client configuration:
response = client.responses.create(
model="gpt-4.1-mini",
instructions="Explain technical concepts in beginner-friendly language.",
input="What is an HTTP request?",
max_output_tokens=150,
)
print(response.output_text)
Here, instructions is part of this specific request, not a setting on OpenAI(). It helps shape the response but does not guarantee a particular length or wording.
6. Two ways to provide text input
Simple string input
For a single question or instruction, pass a plain string:
response = client.responses.create(
model="gpt-4.1-mini",
input="What is a Python list?",
)
print(response.output_text)
This is the clearest starting point when you do not need to explicitly label individual messages.
Structured message input
You can also provide a list of input messages. Each message identifies its role and content:
response = client.responses.create(
model="gpt-4.1-mini",
input=[
{
"role": "user",
"content": "Explain the difference between a list and a tuple.",
}
],
)
print(response.output_text)
Both examples send text input, but the second makes the message structure explicit. This becomes useful when applications handle multiple messages or richer input items. We will examine roles, instructions, and message design in the next lesson instead of expanding into multi-turn memory here.
7. Understand the response object
A successful call returns a structured response object, not just a plain string. It contains information about the request and generated output. Some useful fields are:
| Field | What it tells you |
|---|---|
response.id | Unique identifier for the response |
response.model | Model reported for the response |
response.status | Response processing status |
response.output | Structured list of output items |
response.output_text | Convenient aggregation of generated text items |
response.usage | Token usage details, when available |
Inspect these fields using a real response:
print("Response ID:", response.id)
print("Model:", response.model)
print("Status:", response.status)
print("Text:", response.output_text)
if response.usage is not None:
print("Input tokens:", response.usage.input_tokens)
print("Output tokens:", response.usage.output_tokens)
print("Total tokens:", response.usage.total_tokens)
The response ID and token counts are generated by the API, so they will differ from request to request. Usage may be unavailable in some situations.
8. Why use output_text instead of output[0]?
The response.output field is a list of structured items. Depending on the model and request, it may contain message items and other item types, and its ordering should not be assumed to place a text message at index zero. Therefore, code such as response.output[0].content[0].text is fragile.
For ordinary text-generation tutorials, prefer:
print(response.output_text)
The SDK’s output_text convenience property aggregates text from relevant output items. If there are no matching text items, it can be empty. For applications that need to inspect item types, tools, or other structured output, work with response.output directly and check item types rather than assuming a fixed shape.
9. Complete runnable example
The following example demonstrates request creation, optional instructions, text extraction, and safe inspection of metadata in one script.
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI()
response = client.responses.create(
model="gpt-4.1-mini",
instructions="You are a patient Python tutor. Be clear and concise.",
input="Explain what a Python dictionary is with one example.",
max_output_tokens=180,
)
print("Generated answer:")
print(response.output_text)
print("\nResponse details:")
print("ID:", response.id)
print("Model:", response.model)
print("Status:", response.status)
if response.usage is not None:
print("Total tokens:", response.usage.total_tokens)
Run it from the project terminal:
python main.py
10. Common mistakes and troubleshooting
| Problem | What to check |
|---|---|
| Missing API key | Confirm .env exists in the expected location and load_dotenv() runs before OpenAI() |
| Model not found or access denied | Check the model name and your API project’s access |
Empty output_text | Inspect response.status and the types of items in response.output |
| Unexpected response structure | Avoid assuming output[0] always contains text |
| Request fails with a validation error | Check the request parameter names and types |
| Request is truncated or incomplete | Review max_output_tokens and response status/details |
For now, focus on reading the error and checking request inputs. A deeper look at API errors, token limits, and costs comes later in the series.
11. Summary and next lesson
You now know how the Python client calls the Responses API, how model, input, instructions, and max_output_tokens affect a request, and how to read both generated text and structured response metadata. Most simple text applications can start with response.output_text; more sophisticated workflows need to inspect the underlying response items.
Next, Blog 05 — Messages, Roles, and Instructions in the Responses API will explain how structured messages shape model behavior and how to design clearer interactions.
Official references and related tutorials
- OpenAI Python SDK — official repository
- Responses API reference
- Responses API Python resource implementation
- Response object definition
- Available OpenAI models
- Blog 02 — Install the OpenAI Python SDK and Make Your First API Call
Raj Ranjan