OpenAI Python SDK

The OpenAI Python SDK takes a base_url on the client constructor, so pointing it at an LLM Registry entry needs no wrapper. It can also send custom headers, which is how the Agent Access Key travels when an entry requires one.

All three credential modes below are verified working against an OpenAI entry.

note

base_url must end in /v1. The SDK appends only /chat/completions to whatever you give it, so the version segment has to come from the base URL. This applies to every OpenAI-compatible provider (OpenAI, OpenRouter, Kimi, Groq, Mistral). Gemini is the exception and takes no /v1, which is why it has its own guide.

Setup

Pick the credential mode your entry runs in. You'll find it on the entry's Provider Credential panel.

API Key

The gateway stores the OpenAI credential, so no OpenAI key leaves your machine. api_key carries your Agent Access Key instead.

from openai import OpenAI

client = OpenAI(
    base_url="https://<gateway-host>/llm/<url-prefix>/v1",
    api_key="<your-agent-access-key>"
)

response = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

The SDK sends api_key as Authorization: Bearer, which the gateway accepts as your credential on this mode. It then attaches the stored OpenAI credential on the outbound side.

Passthrough (Agent Access Key Required)

Two credentials travel on every call, in two separate places: your own OpenAI key in api_key, and the Agent Access Key in a custom header.

from openai import OpenAI

client = OpenAI(
    base_url="https://<gateway-host>/llm/<url-prefix>/v1",
    api_key="<your-openai-api-key>",
    default_headers={"X-Agent-Key": "<your-agent-access-key>"}
)

response = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

What each argument does:

• api_key carries your own OpenAI key, which the gateway forwards to OpenAI unchanged. The SDK sends it as Authorization: Bearer.
• default_headers carries the Agent Access Key on X-Agent-Key, which identifies you to the gateway. It applies to every request the client makes.

note

To set the header per call rather than per client, client.chat.completions.create(..., extra_headers={"X-Agent-Key": "<your-agent-access-key>"}) works the same way.

Without a custom header

If setting a header is awkward in your setup, both credentials can travel in api_key instead, combined provider key first and separated by two colons:

client = OpenAI(
    base_url="https://<gateway-host>/llm/<url-prefix>/v1",
    api_key="<your-openai-api-key>::<your-agent-access-key>"
)

The gateway splits the value apart before authenticating, exactly as it does for clients with only one credential field. The header form above is clearer when you have the choice, since each credential stays in its own place.

Passthrough (No Agent Access Key)

With Require an agent access key off, only your OpenAI key travels and no headers are needed.

from openai import OpenAI

client = OpenAI(
    base_url="https://<gateway-host>/llm/<url-prefix>/v1",
    api_key="<your-openai-api-key>"
)

response = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

Where to find each value

Placeholder	Where to find it
<gateway-host>	Host from the entry's Overview tab, for example gw.aigateway.example.com
<url-prefix>	The URL prefix field on the entry's Overview tab
<model-id>	A model identifier from the entry's Allowed Models list, for example gpt-5-nano
<your-agent-access-key>	Generate from the entry's Agent Access Keys step. Plaintext is shown once.
<your-openai-api-key>	Your own OpenAI API key, needed only in the passthrough modes

Tips

• Keep credentials out of your source. The snippets inline the values so the shape is clear, but read them from environment variables or a secret store in anything you commit.
• A missing /v1 looks like a routing error, not a credential one. If calls fail with a not-found rather than an authentication message, check the base URL before checking your key.
• Anthropic entries need the Anthropic SDK. This guide is verified against an OpenAI entry. Pointing the OpenAI SDK at an Anthropic-provider entry is not a supported path today, so use the Anthropic Python SDK for those.
• Working in a different SDK? There are sibling guides for the Anthropic Python SDK and the Google Gen AI Python SDK.