How to Use an OpenAI SDK Compatible API: Base URL, Model IDs, and Troubleshooting

An OpenAI SDK compatible API does not make every model identical. Its main value is letting developers reuse familiar SDKs, request shapes, streaming readers, and error handling. For many existing projects, the only required changes are the API key, Base URL, and model ID.

Check whether your project can switch directly

• Good fit: your project already uses the OpenAI Python or Node SDK, or your tool supports a custom OpenAI compatible endpoint.
• Good fit: your workload uses common chat completions, responses, streaming, or tool-call patterns.
• Needs testing: you depend on provider-specific fields, exact error codes, file uploads, or realtime audio.
• Do not switch blindly: production traffic needs retries, quotas, logs, and key rotation.

Three settings matter most

• API key: identifies account, permission, and billing ownership. Create separate keys by project and environment.
• Base URL: the request endpoint. BigModel.io uses https://bigmodel.io/v1; do not append /v1 twice.
• Model ID: the actual model name. The model catalog and pricing page determine availability, capability notes, and billing.

Minimal Python example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://bigmodel.io/v1",
)

response = client.chat.completions.create(
    model=os.environ["BIGMODEL_MODEL_ID"],
    messages=[
        {"role": "system", "content": "You are concise."},
        {"role": "user", "content": "Explain vector databases in three sentences."},
    ],
)

print(response.choices[0].message.content)

Node.js streaming example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.BIGMODEL_API_KEY,
  baseURL: "https://bigmodel.io/v1",
});

const stream = await client.chat.completions.create({
  model: process.env.BIGMODEL_MODEL_ID,
  stream: true,
  messages: [{ role: "user", content: "Give me an API launch checklist." }],
});

for await (const part of stream) {
  process.stdout.write(part.choices[0]?.delta?.content || "");
}

Troubleshooting common errors

• 401: check that the key is complete, has no whitespace, and the tool is not reading an old environment variable.
• 404: usually means the model ID is unavailable, misspelled, or the Base URL path is wrong.
• 429: check model, account, or key limits, then add exponential backoff on the client side.
• 5xx: record request id, time, model ID, request type, and streaming mode before contacting the Support & feedback page in the console.

Production checklist

• Verify non-streaming, streaming, and tool-call requests with a test key.
• Make sure logs never print full API keys or sensitive user content.
• Add notes, limits, and allowlists to production keys.
• Review usage records, token counts, spend, and balance changes in the console.
• Log and handle 401, 404, 429, and 5xx errors separately.

FAQ

• Do I need to change business code? Usually no, but provider-specific fields still need testing.
• Where should Base URL go? Put https://bigmodel.io/v1 in SDK initialization, tool settings, or environment variables.
• Can one key be shared by every tool? It can, but separate keys make cost and risk easier to trace.