Connect an OpenAI upstream

This chapter assumes you've already got the gateway running (see Docker single node). Below we configure an OpenAI upstream + a gpt-4o model, then call it from the OpenAI SDK / curl, and explain a few cross-protocol details.

Prerequisites

• The gateway is running (http://localhost:7890) and you can log in to the Console
• ENCRYPTION_KEY is set — the upstream API key and access key you're about to save are encrypted before storage; if unset, saving reports encryption_key not set in config. See Docker single node → Prerequisites
• An OpenAI API key (sk-...)

1. Create an upstream

Console → Upstreams → New, fill in:

Field	Value	Description
Name	openai	Unique upstream identifier
Protocol	openai	Determines the executor and request schema
Base URL	https://api.openai.com/v1	The upstream's real address, no trailing /
API Key	sk-...	The key the upstream gave you; click "Add" to add more, distributed by weight
Enabled	✓

Save. The upstream openai appears in the list with status active.

2. Create a model

In the openai upstream row, click Expand → model sub-table → New model, fill in:

Field	Value	Description
Name	gpt-4o	The model name clients use when calling
Upstream	openai	Select the upstream you just created
Upstream model ID	gpt-4o	The upstream's real model name
Enabled	✓

Save. When clients call using gpt-4o, the gateway routes to gpt-4o on the openai upstream.

"Name" is what's exposed to clients; "upstream model ID" is the real name sent to the upstream. When they differ, that's how model aliasing/renaming works.

3. Configure a key group to allow it

Console → Access Keys → Key Groups tab → New:

Field	Value	Description
Name	default	Group name
Models	Select gpt-4o, or * (all)	Determines which models this group's keys can call
Enabled	✓

4. Issue an access key

Console → Access Keys → New:

Field	Value	Description
Name	my-app-key	Identifier
API Key	click "Generate"	Auto-generates a string; the credential the client actually carries
Group	default	Select the group you just created
Enabled	✓

Save. Click the "Copy" button on that row to get the full key value.

The client uses this access key, not the upstream's sk-....

5. Call with the OpenAI SDK

OpenAI Python / Node SDK:

base_url = http://localhost:7890/v1
api_key  = <your access key>

Python example:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7890/v1",
    api_key="<your access key>",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "hello"}],
)
print(resp.choices[0].message.content)

6. Or use curl

curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <your access key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"hello"}]
  }'

Receiving a model reply means it works.

Cross-protocol translation

An OpenAI upstream + an OpenAI client is a "same-protocol identity path": the gateway does no translation and just forwards directly. But you can also call this gpt-4o model with the Anthropic SDK / Gemini SDK — the gateway translates the client protocol to the upstream protocol (openai), then translates the response back to the client's format.

For example, calling with the Anthropic SDK:

curl http://localhost:7890/v1/messages \
  -H "x-api-key: <your access key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}'

The request body is in Anthropic format; the gateway translates it to OpenAI format and sends it to the upstream, then translates the response back to Anthropic format. The client is unaware. For the full interop matrix, see Protocol interop matrix.

FAQ

Q: Client reports 401? The access key isn't right. Check that Authorization: Bearer is followed by the gateway access key (not the upstream's sk-...).

Q: Client reports 403 model_access_denied? The key group your key belongs to doesn't include gpt-4o in its "models" list. Go back to the key group and add that model, or change it to *.

Q: Client reports 404 model_not_found? The model name is misspelled, or the model has hide_name set (only accessible by alias). Check that the model's "Name" field in the Console matches the client's model parameter.

Q: Client reports 502 bad_gateway? The upstream is unreachable. Check that OpenAI's base_url (must be https://api.openai.com/v1, no trailing /) and API key are correct, and whether the upstream is reachable.

Q: How do I make multiple upstreams (multiple OpenAI keys) fail over? Use a load balancer; see Multi-upstream load balancing.

Next: Endpoints · auth · protocol interop for the full endpoint list; Client integration and gateway differences for each SDK's connection method and gateway-specific behavior; Anthropic cross-protocol for the reverse cross-protocol example.