> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Responses setup

> Use stateless Responses with the OpenAI Python SDK.

## Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the [API Keys page](https://platform.pearlresearch.ai/api-keys). Most coding agents need a tool-capable chat model; Aider's basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL.

You need Python 3.10 or later and pip to run the SDK examples below. Install the package in the Python environment you use for your application.

## Get your connection settings

Open [Integrations](https://platform.pearlresearch.ai/integrations), select a model, then choose OpenAI Responses. The screen uses your organization's region. The examples below use the public global endpoint; replace it with your regional endpoint and replace `YOUR_MODEL_ID` with the full model ID shown there. Choose one of the models listed for this integration.

Set your Pearl API key in the terminal where you run OpenAI Responses:

```bash theme={null}
export PEARL_API_KEY="YOUR_PEARL_API_KEY"
```

## Configure OpenAI Responses

Save the Python example as `pearl_example.py` in this directory.

```bash Install theme={null}
python3 -m pip install openai
```

```python Stateless Responses theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.pearlresearch.ai/v1",
    api_key=os.environ["PEARL_API_KEY"],
)
history = [{"role": "user", "content": "Hello!"}]
response = client.responses.create(
    model="YOUR_MODEL_ID", input=history, store=False,
    max_output_tokens=8192,  # covers the reasoning and the answer
    # Levels the model does not serve round up to the next one it does (GET /models lists them).
    # Send {"effort": "none"} to turn reasoning off (models marked mandatory return 400).
    reasoning={"effort": "high"},
)
print(response.output_text)

# Replay the output and history for the next turn.
history.extend(response.output)
history.append({"role": "user", "content": "Tell me more."})
follow_up = client.responses.create(
    model="YOUR_MODEL_ID", input=history, store=False,
    max_output_tokens=8192,
    reasoning={"effort": "high"},
)
print(follow_up.output_text)
```

Use `store=False` and replay conversation history and returned output items. Stored-response continuation, `previous_response_id`, background execution, and WebSocket transport are not supported.

Run the saved example in the same terminal where you set your API key:

```bash theme={null}
python3 pearl_example.py
```

A successful run prints replies for two turns using explicit history replay.

## Set reasoning effort

The examples set the effort with `reasoning={"effort": "high"}`, where `"none"` turns thinking off. The response echoes the level the model applied in `response.reasoning.effort`.

Accepted levels are `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The set a model actually serves is `supported_efforts` in its `reasoning` block on [GET /models](/docs/reference/models.md); any other level rounds up to the next served one, or to the highest past the top ([how levels map](/docs/reasoning.md#effort-mapping)). Omit the field for the model's default, which is `max` on GLM-5.3, so set it explicitly for agents and pipelines. GLM-5.3 and GLM-5.3-Flash always reason and return `400` on the off switch. The output token limit covers the reasoning and the answer.

## Stream a reply

Save this example as `pearl_stream.py` to print text as it arrives:

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.pearlresearch.ai/v1",
    api_key=os.environ["PEARL_API_KEY"],
)
with client.responses.create(
    model="YOUR_MODEL_ID", input="Hello!", store=False,
    max_output_tokens=8192, stream=True,
    # Levels the model does not serve round up to the next one it does (GET /models lists them).
    # Send {"effort": "none"} to turn reasoning off (models marked mandatory return 400).
    reasoning={"effort": "high"},
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            print("\nUsage:", event.response.usage)
        elif event.type in {"response.failed", "response.incomplete"}:
            raise RuntimeError("The response did not complete. See the response status and error details.")
```

```bash theme={null}
python3 pearl_stream.py
```

## Start using OpenAI Responses

Replace the example prompt with your own request. You can review token usage and costs on the [Analytics page](https://platform.pearlresearch.ai/usage).

## Troubleshooting

* `401`: check the key and allow time for a newly created key to reach the inference gateway.
* `404`: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in `/v1`; the Anthropic SDK and Claude Code use the URL without that suffix.
* `402`: check your organization's credit and billing status.
* `429` or Anthropic `529`: respect retry instructions and reduce concurrency.
* For truncated output, check the output limit and reasoning budget. Increase limits only within the model's maximum output length.
* If pip is missing or reports `externally-managed-environment`, follow the [Python package installation guide](https://packaging.python.org/en/latest/tutorials/installing-packages/) for your Python installation, then use that same interpreter to install the SDK and run the example.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.