Instructor (gateway)

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

Setup

Install packages

$ pip install instructor openai

Set environment variables

$ 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

1 import os
2 from typing import TypedDict
3 
4 import instructor
5 
6 client = instructor.from_provider(
7     "openai/gpt-5-mini",
8     api_key=os.environ["RESPAN_API_KEY"],
9     base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
10     mode=instructor.Mode.TOOLS,
11 )
12 
13 
14 class Person(TypedDict):
15     name: str
16     role: str
17 
18 
19 person = client.create(
20     response_model=Person,
21     messages=[
22         {
23             "role": "user",
24             "content": "Grace Hopper was a pioneering computer scientist.",
25         }
26     ],
27 )
28 print(dict(person))

Switch models

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

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

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.