> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.respan.ai/docs/_mcp/server.

# Instructor (gateway)

> Set up Instructor with the Respan gateway.

Route Instructor's underlying OpenAI-compatible LLM calls through the Respan gateway to use 1000+ models from different providers. Only your Respan API key is needed - no separate provider key is required.

## Setup

#### Install packages

```bash
pip install instructor openai
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"
```

No `OPENAI_API_KEY` is needed when the request is routed through the Respan gateway.

#### Point Instructor to the Respan gateway

```python
import os
from typing import TypedDict

import instructor

client = instructor.from_provider(
    "openai/gpt-5-mini",
    api_key=os.environ["RESPAN_API_KEY"],
    base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
    mode=instructor.Mode.TOOLS,
)


class Person(TypedDict):
    name: str
    role: str


person = client.create(
    response_model=Person,
    messages=[
        {
            "role": "user",
            "content": "Grace Hopper was a pioneering computer scientist.",
        }
    ],
)
print(dict(person))
```

## Switch models

Change the model string passed to `instructor.from_provider` to use another OpenAI model through the same gateway endpoint.

```python
client = instructor.from_provider(
    "openai/gpt-5.5",
    api_key=os.environ["RESPAN_API_KEY"],
    base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
    mode=instructor.Mode.TOOLS,
)
```

> **Note**
>
> Instructor's `from_provider` string includes the SDK provider namespace. Keep this page to OpenAI models so Claude or Gemini are not shown as OpenAI-provider models. Use the Respan API or OpenAI SDK gateway pages for provider-neutral Claude and Gemini examples.

See the [full model list](https://platform.respan.ai/platform/models).