> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/sdk/index · Doc index: https://docs.gatellm.io/en/llms.txt


# SDK Integration Overview

The gateway is a **protocol-oriented** entry point: whatever SDK you use on the client, as long as it speaks one of the gateway's supported protocols (OpenAI / Anthropic / Gemini / DashScope / Realtime / MCP / passthrough), pointing its base_url at the gateway and swapping its API key for a gateway-issued access key lets you call any model configured in the gateway — including **cross-protocol calls to other vendors' models**. This group of pages is organized by "which SDK you already have", each with a copy-paste minimal example.

## The three universal steps {#three-steps}

Every SDK follows the same wiring rule:

1. **Point `base_url` at the gateway** (default `http://localhost:7890`). Note that each SDK differs on whether base_url includes `/v1` — see the per-page examples.
2. **Set the API key to a gateway-issued access key**, not an upstream `sk-...`. Access keys are issued on the Console's "Access keys" page.
3. **Set `model` to the model name configured in the gateway**. The gateway does not restrict calls by model name — whatever name you configure in the console is what the client uses.

Model names that appear in examples (`gpt-5.4-mini`, `claude-haiku-4-5`, `gemini-3.5-flash`, `qwen3.8-max`, …) are just "real names under some gateway config"; use whatever your console defines.

## Auth headers {#auth-headers}

Data-plane endpoints try the following auth methods in order, first match wins (see [Endpoints · Auth](/en/reference/endpoints.md#auth)):

| Header | Corresponding SDK | Notes |
|--------|-------------------|-------|
| `Authorization: Bearer <access key>` | OpenAI, DashScope, generic | `Bearer` prefix is case-insensitive |
| `x-api-key: <access key>` | Anthropic SDK | `Authorization` also accepted |
| `x-goog-api-key: <access key>` | Gemini SDK | `Authorization` also accepted |
| (none of the above) | — | Anonymous fallback, only if an `anonymous=true` key is configured |

> The three headers are just different mounting slots for the same "gateway access key" — issue one in the console and put it in whichever header your SDK expects.

## SDK selection matrix {#selection-matrix}

"I'm already using X — how do I connect it to the gateway?" Find your row:

| SDK / framework | Language | Protocol / endpoint | Text | Image | Video | Realtime | Embed/rerank | Page |
|-----------------|----------|---------------------|------|-------|-------|----------|--------------|------|
| OpenAI SDK | Py / Node | `openai` family (`/v1/chat/completions`, `/v1/responses`, …) | ✅ | ✅ | — | ✅¹ | ✅ | [Vendor SDKs](/en/sdk/vendor-sdks.md) |
| Anthropic SDK | Py / Node | `anthropic` (`/v1/messages`) | ✅ | input understanding | — | — | — | [Vendor SDKs](/en/sdk/vendor-sdks.md) |
| Google GenAI SDK | Py / JS | `google` (`/v1beta/models/*`) | ✅ | ✅ | — | — | — | [Vendor SDKs](/en/sdk/vendor-sdks.md) |
| DashScope SDK / HTTP | Py | `dashscope` (`/v1/services/*`) | ✅ | ✅ | ✅ async | ✅¹ | ✅ | [DashScope native & async](/en/sdk/dashscope-native.md) |
| OpenAI-compatible third parties (DeepSeek/GLM/Kimi/Grok…) | Py / Node | `openai` compatible | ✅ | vendor-dependent | — | — | vendor-dependent | [Vendor SDKs](/en/sdk/vendor-sdks.md) |
| Vercel AI SDK | TS | `openai` / `anthropic` (provider layer) | ✅ | provider-dependent | — | — | provider-dependent | [Unified SDKs & gateways](/en/sdk/unified-sdks.md) |
| LiteLLM | Py | `openai` compatible | ✅ | model-dependent | — | — | ✅ | [Unified SDKs & gateways](/en/sdk/unified-sdks.md) |
| LangChain / LangGraph | Py / TS | underlying chat model (OpenAI/Anthropic…) | ✅ | model-dependent | — | — | ✅ | [Orchestration frameworks](/en/sdk/orchestration-frameworks.md) |
| LlamaIndex | Py / TS | `OpenAILike` / chat model | ✅ | model-dependent | — | — | ✅ | [Orchestration frameworks](/en/sdk/orchestration-frameworks.md) |
| CrewAI | Py | underlying LiteLLM | ✅ | model-dependent | — | — | — | [Orchestration frameworks](/en/sdk/orchestration-frameworks.md) |
| AutoGen / AG2 | Py | `openai` compatible | ✅ | model-dependent | — | — | — | [Orchestration frameworks](/en/sdk/orchestration-frameworks.md) |
| OpenAI Agents SDK | Py / TS | `openai_response` (default) | ✅ | model-dependent | — | — | — | [Agent SDKs](/en/sdk/agent-sdks.md) |
| Claude Agent SDK | Py / TS | `anthropic` | ✅ | input understanding | — | — | — | [Agent SDKs](/en/sdk/agent-sdks.md) |
| Pydantic AI | Py | `openai` compatible | ✅ | model-dependent | — | — | — | [Agent SDKs](/en/sdk/agent-sdks.md) |
| Realtime (WebSocket) | any WS client | `openai_realtime` (`/v1/realtime`) | — | — | — | ✅ | — | [Realtime & audio](/en/sdk/realtime-and-audio.md) |

> ¹ Realtime connects through the gateway's OpenAI Realtime client protocol (`/v1/realtime`) over a raw WebSocket — no vendor SDK is required; `model` is the realtime model's config name in the gateway (OpenAI or DashScope).

## Cross-SDK pitfalls {#common-pitfalls}

No matter which SDK, after going through the gateway watch for these (each page repeats them; here they are in one place):

- **The model name must match the gateway config.** The `model` you pass is "the name configured in the gateway" — not the vendor's official name, not the upstream's real model ID. Wrong name → 404 `model_not_found`.
- **Whether base_url includes `/v1` varies by SDK.** OpenAI SDK takes `/v1`; Anthropic SDK takes the root (it appends `/v1/messages`); Google GenAI takes the root (via `http_options.base_url`). Getting it wrong adds or drops a path segment.
- **Fields get translated and constrained by the target protocol across protocols.** For example, if the gateway's `gpt-5.6-sol` upstream is a Responses protocol, a `max_tokens` passed by the client is translated to `max_output_tokens`, and the upstream may impose a lower bound (e.g. ≥16) — too small → 400.
- **Thinking blocks / signatures are wrapped by the gateway.** Claude and Gemini thinking content (thinking / thoughtSignature) is passed through or stripped by the gateway; to get the text, take the `type == "text"` element of the `content` array — don't assume `content[0]` is text.
- **Third-party SDK model-name allowlists.** Some frameworks (LlamaIndex, AutoGen, …) validate the model name against families they recognize and reject unknown gateway names — use their "any model" entry point or declare the model info explicitly (see each page).

## Next {#next}

- Want the smallest possible call: start with [Vendor SDKs](/en/sdk/vendor-sdks.md).
- Frontend / Next.js: see [Unified SDKs & gateways](/en/sdk/unified-sdks.md).
- Already on LangChain / LlamaIndex / CrewAI: see [Orchestration frameworks](/en/sdk/orchestration-frameworks.md).
- Voice / video and other niche capabilities: see [Realtime & audio](/en/sdk/realtime-and-audio.md) and [DashScope native & async tasks](/en/sdk/dashscope-native.md).
- Full provider and model list (without SDK examples): see [Supported providers & models](/en/reference/supported-models-and-sdks.md).