Most projects start on the official OpenAI API because it is the default. The pressure shows up later: bills that grow faster than usage, payment friction, and no way to see which team member or feature is spending what. Moving to an OpenAI-compatible gateway like Zivv should not mean rewriting business logic — done properly, it is a configuration change with a rollout plan. This is the playbook.
Pre-Migration Audit
Before touching anything, answer three questions:
- Where are the base URL and API key configured? If they already live in environment variables or a config service, migration is fast. If they are scattered through code, centralize them first — that refactor pays off regardless of the gateway.
- Are model names hard-coded? Search the codebase for model strings. Every hard-coded name is a place migration can silently break.
- Do you have a low-risk environment to validate in? Local dev, staging, or an internal tool. Never validate a gateway switch in production first.
Step 1: Centralize Configuration
Target state — the entire migration surface lives in two variables:
OPENAI_BASE_URL=https://zivv.pro/v1
OPENAI_API_KEY=sk-your-zivv-keyGet a key at Zivv; top-up is a flat 1 CNY = 1 USD and billing is pay-as-you-go on tokens.
Step 2: Update the SDK Client
Every mainstream OpenAI SDK accepts a base URL override. Python:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://zivv.pro/v1",
api_key=os.environ["OPENAI_API_KEY"],
)
resp = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)Node.js:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://zivv.pro/v1",
apiKey: process.env.OPENAI_API_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-5.5",
messages: [{ role: "user", content: "Say hello" }],
});You keep the same SDK, the same request shapes, the same streaming code. Only the destination changes. Concrete examples for other languages are in the OpenAI SDK guide.
Step 3: Map Model Names
Model names are the most common migration failure, so treat them as a first-class task:
| Situation | Recommendation |
|---|---|
| Standard model names (gpt-5.5, gpt-5.4) | Test directly — they resolve as-is |
| Internal aliases in your code | Map alias to real model name in config |
| Multiple models in production | Migrate one low-risk model first |
| Unsure what is available | Check the Model Hub before assuming |
A side benefit: through Zivv the same OpenAI-compatible endpoint also serves claude-sonnet-5 and gemini-3.5-flash, so a later move to multi-model routing needs no new plumbing.
Step 4: Verify Error Handling
A migration is not "requests succeed." Production systems need failures to be observable. After switching, confirm:
- Timeouts still trigger at the values you set
- Retry counts and backoff behave as before
- Streaming terminates cleanly on both success and error
- Request IDs land in your logs for support escalation
- Insufficient balance and disabled-key responses produce clear internal alerts, not silent 4xx noise
Wire your log matching against the error reference so on-call engineers see "key disabled" instead of a bare status code.
Step 5: Roll Out Gradually
- Switch local development and confirm the daily workflow feels identical
- Run the full test suite against staging
- Send about 5% of production traffic through the gateway
- Watch success rate, p95 latency, and cost per request for a few days
- Ramp to 100%, keeping the official config one environment variable away as a rollback
If your stack cannot split traffic by percentage, roll out by workload instead: internal tools first, low-risk production features second, core user-facing flows last. The key property is reversibility — at every stage, rollback is a config change.
Step 6: Validate the Cost Claim
Do not stop at "it works." Compare a week of data on both sides:
- Request count and token volume (input and output separately)
- Average cost per task, not just per token
- Extra cost introduced by retries
Zivv's team dashboard splits usage by key and member, so give the migration its own key and the before/after comparison builds itself. If several teammates are involved, structure this under Teams from the start.
When Not to Migrate
Be honest about the exceptions. If you have compliance contracts that require a direct provider relationship, or a hard dependency on an experimental feature that just shipped, evaluate first. Zivv fits cost-sensitive, multi-model, developer-heavy teams best.
FAQ
Do I need to change my prompts? No. The gateway is protocol-compatible; prompts, parameters, and response parsing are untouched.
What about function calling and JSON mode? They ride on the same OpenAI protocol and work unchanged. Include them in your staging test pass like any other feature.
How do I roll back? Point OPENAI_BASE_URL back at the official endpoint and swap the key. If you completed Step 1, that is one deploy with no code change.
Can I run both endpoints at once? Yes — that is exactly what the 5% rollout does. Different services or environments can point at different endpoints indefinitely, and many teams keep an internal tool on one endpoint permanently as a live canary for latency and cost comparisons.
Wrap-Up
A good migration is reversible, gradual, and measurable: centralize config, switch the base URL, map model names, verify failure paths, then ramp traffic while watching cost. Create a key and run Step 2 against staging today — the whole first pass fits in an afternoon.