Short answer. A migration is often a configuration change: keep the OpenAI SDK, change base_url in Python or baseURL in TypeScript, swap the API key, and point model IDs at the new catalogue. Then test streaming, tool calls, JSON mode and error paths. Behaviour, context limits and embedding dimensions are where migrations actually break.
| Question | One-sentence answer |
|---|---|
| Can I keep the OpenAI SDK? | Yes, if the provider implements the chat-completions shape; change the base URL and key. |
| What is the base URL for Plugsky? | https://api.plugsky.com/v1. |
| Do I need to rewrite streaming code? | Usually not; SSE chunks keep the same delta shape, but test tool-call deltas and finish reasons. |
| Do tool calls work the same? | The request and response shapes are compatible; argument validity and parallel-call behaviour still need tests. |
| How do I map model names? | Replace OpenAI IDs with Plugsky IDs from GET /v1/models; do not assume a name implies the same engine. |
| What about embeddings? | Plugsky embeddings are 2048-dimensional; re-embed and rebuild the index instead of reusing 1536-dimensional vectors. |
| How do I add a fallback? | Try a primary model, catch timeout, rate-limit and 5xx errors, then retry on a second model with the same messages. |
| How do I roll back? | Keep the old client behind a flag, shadow-test, and switch traffic gradually. |
The OpenAI SDK is a client, not a loyalty programme. It accepts a different base URL, so a migration can start with two lines of configuration. That is the easy part. The harder part is proving that streaming, tools, structured output and error handling still behave the way your product expects.
This guide uses the official OpenAI SDK interfaces because they are the shortest path for most teams. It shows Python and TypeScript, then the fallback pattern that keeps a provider outage from becoming your outage. Every snippet is deliberately small enough to run and adapt.
The first call: change the base URL
Install the current OpenAI SDK, set the key in an environment variable, and point the client at Plugsky. The request shape stays the same.
How do I call Plugsky from Python?
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["PLUGSKY_API_KEY"],
base_url="https://api.plugsky.com/v1",
)
response = client.chat.completions.create(
model="plugsky-plus",
messages=[
{"role": "user", "content": "Summarise this support ticket in one sentence."}
],
)
print(response.choices[0].message.content)
The migration-specific lines are base_url, the API key and the model ID. Keep the key out of source control and use a separate staging key for the test. If your code reads OPENAI_API_KEY today, either rename the variable or map it explicitly; do not leave both providers reading the same secret. The Python SDK retries some transient failures by default, so check the retry settings before you add your own loop.
How do I call Plugsky from TypeScript?
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.PLUGSKY_API_KEY,
baseURL: "https://api.plugsky.com/v1",
});
const response = await client.chat.completions.create({
model: "plugsky-plus",
messages: [
{ role: "user", content: "Summarise this support ticket in one sentence." },
],
});
console.log(response.choices[0]?.message?.content);
Note the spelling: baseURL in TypeScript, base_url in Python. The example uses top-level await, so run it in an ES module or inside an async function. In a browser, never ship the API key to the client; call your own backend, which holds the key and forwards the request. If your build targets CommonJS, wrap the call in an async function rather than enabling top-level await. Pin the SDK version in package.json.
Which model ID should replace gpt-4o?
There is no automatic quality equivalence. Map by job first, then test. The table below is a starting point, not a benchmark claim; the live catalogue at GET /v1/models is authoritative. A legacy ID with a familiar name can be served by a different engine, and a larger parameter count does not guarantee a better result on your task. Record the served model for every request so a routing change does not silently alter quality.
| Workload | Plugsky model ID | Context | What to test |
|---|---|---|---|
| General chat and tool use | plugsky-pro | 262,144 | Tool argument validity, latency, output style |
| Fast classification and extraction | plugsky-plus | 262,144 | Throughput, JSON conformance, cost per task |
| Long-context analysis | plugsky-longctx | 262,144 | Recall at the far end of the prompt |
| Multi-step reasoning | plugsky-reasoning | 262,144 | Step count, answer quality, token usage |
| Vision and documents | plugsky-vision-fast | 131,072 | Image limits, table extraction, OCR quality |
| Translation | plugsky-translate | 32,768 | Domain terms, dialect coverage, length |
| Embeddings | plugsky-embed | 8,192 | 2048 dimensions; rebuild the vector index |
Streaming without surprises
Streaming is where a compatible API stops being a configuration change. The chunk shape is familiar, but error handling and tool-call deltas need attention.
How do I stream responses in Python?
stream = client.chat.completions.create(
model="plugsky-plus",
messages=[{"role": "user", "content": "Write a short release note."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Iterate the stream and print only non-empty deltas. In production, wrap the loop so a mid-stream error closes the connection cleanly and does not leave a half-written record. If you need token usage for billing or evaluation, request it explicitly where the API supports stream_options, and test that the final chunk arrives before you persist the result. If the connection drops, discard the partial answer rather than appending a retry to it.
How do I stream responses in TypeScript?
// Reuse the client configured in the first example.
const stream = await client.chat.completions.create({
model: "plugsky-plus",
messages: [{ role: "user", content: "Write a short release note." }],
stream: true,
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) process.stdout.write(delta);
}
Pass an AbortSignal if the user can cancel, and handle the abort separately from a provider error. Do not retry after the first token has been rendered unless your UI can replace the partial answer; a retry at that point can duplicate text. Retry only before the first token, or restart the whole response with a clear indicator. Close the reader in a finally block so a failed render does not leak the connection.
Tools, JSON mode and structured output
Tool calls are usually compatible at the wire level. The failure mode is semantic: the model emits arguments that parse as JSON but do not satisfy your schema.
How do I send tool definitions and complete a tool loop?
import json
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["PLUGSKY_API_KEY"],
base_url="https://api.plugsky.com/v1",
)
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Return the status of an order by ID.",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
"additionalProperties": False,
},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(
model="plugsky-pro", messages=messages, tools=tools, tool_choice="auto"
)
assistant = first.choices[0].message
messages.append(assistant)
for call in assistant.tool_calls or []:
if call.function.name == "get_order_status":
args = json.loads(call.function.arguments)
result = {"order_id": args["order_id"], "status": "in_transit"}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
final = client.chat.completions.create(
model="plugsky-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)
The loop has three rules. Append the assistant message exactly as returned, including tool_calls; answer every tool call with a matching tool_call_id; and cap the number of iterations. Validate args against your schema before executing anything. A tool that moves money or sends email should also be idempotent, because a retry can repeat the side effect even when the model call succeeds. Log the tool name, arguments and result for every call so a bad answer can be traced to a step.
Does JSON mode guarantee my schema?
No. JSON mode guarantees parseable JSON, not conformance to your schema. The model can omit a required field, invent an enum value or return a string where you expected a number. Validate every response with Pydantic, Zod or an equivalent validator, and send the validation error back in a repair turn when the failure is recoverable. Keep a hard cap on repair attempts. For high-stakes extraction, treat JSON mode as a formatting aid, not as a contract.
Fallbacks and model switching
A fallback is not a second model name in a config file. It is a decision about which failures are safe to retry, and which must surface to the user.
What is a safe fallback pattern?
import os
from openai import OpenAI, APIConnectionError, APITimeoutError, RateLimitError, APIStatusError
client = OpenAI(
api_key=os.environ["PLUGSKY_API_KEY"],
base_url="https://api.plugsky.com/v1",
)
FALLBACKS = ["plugsky-pro", "plugsky-plus", "plugsky-micro"]
RETRYABLE = {429, 500, 502, 503, 504}
def complete(messages, **kwargs):
last_error = None
for model in FALLBACKS:
try:
return client.chat.completions.create(
model=model, messages=messages, **kwargs
)
except (APIConnectionError, APITimeoutError, RateLimitError, APIStatusError) as exc:
last_error = exc
status = getattr(exc, "status_code", None)
if status is not None and status not in RETRYABLE:
raise
raise last_error
Only fall back on connection errors, timeouts, rate limits and 5xx responses. A 400, 401 or 403 means the request or the credential is wrong; sending it to another model usually wastes latency and hides the bug. Log which model served each request, and expose the serving engine where the API reports it. The response header x-plugsky-served-model is the record to keep. Keep the fallback list short and ordered by cost, and alert when the primary is skipped repeatedly.
// Reuse the client configured in the first example.
const fallbacks = ["plugsky-pro", "plugsky-plus", "plugsky-micro"];
const retryable = new Set([429, 500, 502, 503, 504]);
async function complete(
messages: OpenAI.Chat.ChatCompletionMessageParam[],
params: Omit<OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, "model" | "messages"> = {},
) {
let lastError: unknown;
for (const model of fallbacks) {
try {
return await client.chat.completions.create({ model, messages, ...params });
} catch (error) {
lastError = error;
if (error instanceof OpenAI.APIError && error.status && !retryable.has(error.status)) {
throw error;
}
}
}
throw lastError;
}
The TypeScript version follows the same rule. The Omit keeps callers from overriding the model or messages, which would defeat the fallback chain. Add jittered backoff between attempts, and do not fall back after a partial stream. If the primary model is degraded rather than down, a fallback can be worse than waiting; make the threshold a product decision, not a default.
What should I test before cutover?
Build a frozen set of real requests and run it against both providers. Compare task success, not just text similarity. At minimum, cover streaming, tool calls, JSON mode, vision, long context, embeddings, rate-limit behaviour, error codes and cost per completed task. Add a regression case for every production bug you find. Test the fallback path by forcing a 429 and a timeout, and confirm that the user sees a coherent answer rather than two half-responses. Compare plan pricing on cost per completed task, not on token rate alone.
What to verify before you migrate
- Compatibility scope. Which endpoints, parameters and response fields are supported, and which are ignored.
- Model mapping. A job-based mapping with an owner and an evaluation set for each workload.
- Limits. Context, max output, concurrency, RPM and per-request ceilings for your plan; see unlimited API limits.
- Embeddings. Dimensions, normalisation and index rebuild; a model change can invalidate every vector.
- Error semantics. Status codes, retry guidance and the shape of streaming errors.
- Data terms. Residency, retention, training use and the DPA for the new provider; have counsel review the DPA.
- Exit. How you switch back, and whether the old provider stays warm during the transition.
Compatibility is a test result, not a press release. Migrate the smallest workload first, measure it, then move the traffic.
What we did not verify. The snippets use documented OpenAI SDK interfaces, but they were not executed against a live Plugsky account for this page. Run them with a staging key, confirm the installed SDK version, and check the current API reference before cutover. Model behaviour and limits should be tested on your own evaluation set, not inferred from this guide.
Frequently asked questions
Is Plugsky a drop-in replacement for OpenAI?
For the chat-completions surface, often close, but not a guarantee. The request shape, streaming chunks and tool-call fields are designed to be compatible, while model behaviour, context limits, embeddings and unsupported parameters can differ. Treat compatibility as a test plan: run your real prompts, tools and error paths against a staging key. A drop-in claim is only true for the subset you have verified. Keep a written list of what you tested and what you did not.
Do I need a new SDK?
No. The official OpenAI SDKs accept a custom base URL, so you can keep the client and change configuration. You can also use plain HTTP if you prefer fewer dependencies. The trade-off is that SDK convenience features, retries and typed responses are tied to the SDK version, so pin the version and read the release notes before upgrading. A thin internal client that wraps the SDK makes a later provider change easier.
What changes in the request body?
The model ID, the base URL and the API key are the minimum. Some parameters may be unsupported, ignored or behave differently, and provider-specific fields should not be sent blindly. Tool schemas, JSON mode and vision inputs need their own tests. Keep a request fixture per workload and diff the responses, rather than assuming that a successful HTTP 200 means the feature works. Pin the SDK version so a silent client change cannot alter the payload.
Does streaming work with the SDK?
Yes, when the provider implements server-sent events with the same chunk shape. Test the first token, the final chunk, a mid-stream error and a cancelled request. Tool-call deltas are the usual gap: arguments may arrive in fragments, so accumulate them before parsing. Do not retry after rendering a partial answer unless the UI can replace it cleanly. A cancelled stream should stop billing, close the upstream connection promptly and free the socket.
Are OpenAI fine-tuned models supported?
Not automatically. Fine-tuned model IDs are provider-specific, and a new provider will not have your OpenAI fine-tune unless you export and host it there. Check whether the catalogue offers fine-tuning, whether custom weights are allowed on your plan, and what happens to the model at contract exit. If the fine-tune is core to the product, treat portability as a procurement requirement, not an afterthought. Ask for the export format and the deletion date in writing.
How do embeddings differ?
Dimensions and training data can differ, so vectors are not interchangeable across providers. Plugsky embeddings are 2048-dimensional with an 8,192-token context; a 1536-dimensional index cannot be reused without a rebuild. Re-embed the corpus, rebuild the index, and re-run retrieval evaluation. Budget for the backfill separately from steady-state query traffic, because the one-off cost can dominate. Store the model ID and dimension alongside every vector so a mismatch is detectable before it reaches production.
Can I run both providers side by side?
Yes, and it is the safest way to migrate. Put both clients behind an internal interface, route a small percentage of traffic to the new provider, and compare task success, latency and cost on the same requests. Keep the old path warm until the new one has passed a full business cycle. A shadow mode that duplicates requests is useful for quality, but it doubles cost and needs a data-handling review.
How do I handle rate limits?
Catch HTTP 429, respect any retry guidance, add jittered exponential backoff, and queue rather than retrying immediately. Cap the queue and surface backpressure to the caller. If the limit is concurrency rather than RPM, a queue alone will not help; you need to reduce in-flight requests. Test at two to three times expected peak, because rate-limit behaviour under burst is where most integrations fail. Track 429s per 1,000 requests and alert when the rate changes.
How do I migrate vision or document workloads?
Use a vision-capable model ID, confirm the supported image formats and size limits, and test the documents that actually break: rotated scans, tables, handwriting and multi-column PDFs. Extraction quality is workload-specific, so a general benchmark is weak evidence. Compare field-level accuracy on a labelled sample, and keep a fallback to a document parser for pages the model handles poorly. Keep the original page image for audit and reprocessing when extraction is disputed.
What is the biggest migration risk?
Assuming parity. Silent quality regressions, embedding dimension mismatches and retry behaviour are more dangerous than a failed request, because they ship without an error. Instrument task success and cost per completed task before and after, and keep a frozen evaluation set. A migration that looks healthy on latency but loses accuracy on one intent is still a failure. Treat the migration as complete only after the old path is removed.
Sources
Primary sources and official documentation for this 2027 planning guide — evidence checked 20 November 2026.
- OpenAI API reference, Chat Completions — checked 20 November 2026.
- OpenAI Python SDK — checked 20 November 2026.
- OpenAI Node and TypeScript SDK — checked 20 November 2026.
- OpenAI API pricing — checked 20 November 2026.
Last checked 20 November 2026.
Related reading
Move one workload, prove it, then move the rest
Start with a staging key, run your own evaluation set, and keep the old provider warm until the new path passes.
Start Free → Migration docs