OpenAI-Compatible Unified Calling

⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs Updated: 2026-08-29 · Status: Pending Verification

Background

After 2023, nearly every new model vendor cloned OpenAI's POST /v1/chat/completions path: same request body, same response body, same streaming chunk shape, same effort to align error codes. The reason is not that OpenAI's design is optimal — it is ecosystem gravity. SDKs, tutorials, prompt libraries, and agent frameworks all orbit this protocol. A de facto standard outweighs a designed one, and the unified gateway adopts it as the egress contract.

Core Concepts

• Request normalization: whether the upstream is Claude, Gemini, or Llama, the gateway accepts messages / model / temperature / stream / tools.
• Response normalization: maps each vendor's usage, finish_reason, and tool_calls shapes into the OpenAI form, so clients write parsing logic once.
• Error normalization: Anthropic's overloaded_error and Google's RESOURCE_EXHAUSTED both translate to HTTP 429 with an OpenAI-style error body.
• Capability probing: /v1/models exposes unified aliases with flags for vision, tool_calls, and json_mode support.

Code Example

# Inside the gateway: translate an Anthropic response into OpenAI shape
def anthropic_to_openai(resp: dict) -> dict:
    return {
        "id": resp["id"],
        "object": "chat.completion",
        "model": resp["model"],
        "choices": [{
            "index": 0,
            "message": {"role": "assistant",
                        "content": resp["content"][0]["text"]},
            "finish_reason": "stop",
        }],
        "usage": {
            "prompt_tokens": resp["usage"]["input_tokens"],
            "completion_tokens": resp["usage"]["output_tokens"],
            "total_tokens": resp["usage"]["input_tokens"]
                         + resp["usage"]["output_tokens"],
        },
    }

Protocol Evolution and Compatibility Tiers

OpenAI itself keeps evolving the protocol fast: response_format went from json_object to json_schema, and reasoning_effort is exclusive to the o1/o3 family. The gateway needs a compatibility tier: it exposes the latest protocol to clients (supporting json_schema), but for older upstream models that lack the field, it auto-degrades to prompt injection (a system message saying "please output JSON conforming to the following schema"). This "protocol adapter" pattern lets clients see only one top-tier interface; the cost is that the gateway maintains a capability matrix.

Trade-offs and Best Practices

• Not every field maps: Claude's thinking and Gemini's safety_settings have no OpenAI equivalent — funnel them through extra_body or a dedicated extension header.
• Pin the version: OpenAI itself keeps evolving the protocol (response_format, reasoning_effort); the gateway must track upstream versions or drift apart silently.
• Always keep an escape hatch: let clients pass provider_params through to native upstream fields instead of hard-closing them.
• Capability-aware routing: expose supports_tools, supports_vision, supports_json_schema flags in /v1/models so clients can pick by capability.

OpenAI compatibility is not the destination — it is the strategy that lets "code written today still run tomorrow."

🚀 Get Started: One-Click Free API Access

Want to call all the free models above with a single API key, no need to sign up for each provider? Apishare.cc provides a unified API Key — one key, 100+ models, free models at zero cost.

👉 Register on Apishare.cc → Get your unified API Key

📊 Want to see more free model rankings? Check out the Sep 2026 Free LLM API Rankings →

Get Started: APIShare Free API Directory

• 🆓 Claim your free credits：Register on APIShare · Sign in to console
• 🔍 Browse every free API and live ranking：APIShare Free API Directory
• 📊 See the leaderboard：Free LLM API Rankings

About the Free API Aggregator

The models covered in this guide are all served through the APIShare free API aggregator, which gives you one key for the whole catalog.

• Full model catalog: APIShare free API directory
• Sign up for a free trial key: Register and claim your API key