> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Drop-in SDKs

> Use the OpenAI, Anthropic, Google AI, or TypeSafe SDK against Opper by changing the base URL and API key.

The gateway speaks the protocols you already use: the OpenAI, Anthropic, and Google AI APIs, with messages, tools, and multi-turn conversation working exactly as they do natively.

If you already use one of those SDKs, keep it. Point it at Opper and swap the API key for an Opper one, and every call now flows through the gateway. You get 700+ models, fallback routing, per-call usage and cost in [Logs](https://docs.opper.ai/control-plane/logs.md), and organization Rules without rewriting anything.

The TypeSafe SDKs also work with the gateway for classification and scoring. See [TypeSafe SDKs](#typesafe-sdks) below for setup, or [Classification & scoring](https://docs.opper.ai/build/gateway/evaluations.md) for question types and HTTP examples.

The OpenAI SDK's `client.decisions` works too, in OpenAI's Decisions format.

## Setup

For the OpenAI, Anthropic, and Google AI SDKs the change is the same:

1. Set the base URL to `https://api.opper.ai/v3/compat`
2. Pass your Opper API key as the SDK's normal `api_key`

Opper reads the key from `Authorization: Bearer`, which is what the OpenAI SDK sends. On the routes that serve a vendor's own protocol it reads that protocol's header too — `x-api-key` on the Anthropic Messages endpoints, `x-goog-api-key` on the Google ones. So all three SDKs authenticate with nothing but their normal `api_key`.

## SDK examples

> [tab] OpenAI
>
> ```python Python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(
>     base_url="https://api.opper.ai/v3/compat",
>     api_key=os.environ["OPPER_API_KEY"],
> )
>
> response = client.chat.completions.create(
>     model="openai/gpt-5-mini",
>     messages=[{"role": "user", "content": "Hello"}],
> )
> print(response.choices[0].message.content)
> ```
>
> ```typescript TypeScript theme={null}
> import OpenAI from "openai";
>
> const client = new OpenAI({
>     baseURL: "https://api.opper.ai/v3/compat",
>     apiKey: process.env.OPPER_API_KEY!,
> });
>
> const response = await client.chat.completions.create({
>     model: "openai/gpt-5-mini",
>     messages: [{ role: "user", content: "Hello" }],
> });
> console.log(response.choices[0].message.content);
> ```
>
> Works with `chat.completions.create`, `embeddings.create`, and `responses.create`.

> [tab] Anthropic
>
> ```python Python theme={null}
> import os
> from anthropic import Anthropic
>
> client = Anthropic(
>     base_url="https://api.opper.ai/v3/compat",
>     api_key=os.environ["OPPER_API_KEY"],
> )
>
> message = client.messages.create(
>     model="anthropic/claude-sonnet-4-6",
>     max_tokens=1024,
>     messages=[{"role": "user", "content": "Hello"}],
> )
> print(message.content[0].text)
> ```
>
> ```typescript TypeScript theme={null}
> import Anthropic from "@anthropic-ai/sdk";
>
> const client = new Anthropic({
>     baseURL: "https://api.opper.ai/v3/compat",
>     apiKey: process.env.OPPER_API_KEY!,
> });
>
> const message = await client.messages.create({
>     model: "anthropic/claude-sonnet-4-6",
>     max_tokens: 1024,
>     messages: [{ role: "user", content: "Hello" }],
> });
> if (message.content[0].type === "text") console.log(message.content[0].text);
> ```
>
> `client.models.list()` also works, but the model list isn't a Messages route, so it reads only the bearer header. On a client you list models from, pass the key as `auth_token` (`authToken` in TypeScript) instead of `api_key`.

> [tab] Google AI
>
> ```python Python theme={null}
> import os
> from google import genai
>
> client = genai.Client(
>     api_key=os.environ["OPPER_API_KEY"],
>     http_options={"base_url": "https://api.opper.ai/v3/compat"},
> )
>
> response = client.models.generate_content(
>     model="gemini/gemini-3.1-pro-preview",
>     contents="Hello",
> )
> print(response.text)
> ```
>
> ```typescript TypeScript theme={null}
> import { GoogleGenAI } from "@google/genai";
>
> const client = new GoogleGenAI({
>     apiKey: process.env.OPPER_API_KEY!,
>     httpOptions: { baseUrl: "https://api.opper.ai/v3/compat" },
> });
>
> const response = await client.models.generateContent({
>     model: "gemini/gemini-3.1-pro-preview",
>     contents: "Hello",
> });
> console.log(response.text);
> ```

## TypeSafe SDKs

Keep the [TypeSafe SDK](https://docs.typesafe.ai/sdk), set its base URL to `https://api.opper.ai/v3/compat`, and use your Opper API key. The SDK sends its native `state` and `questions` format to `/v1/systemone` and returns typed answers with probabilities and confidence.

Install `typesafe-sdk` for Python or `@typesafe-ai/sdk` for TypeScript:

```python Python theme={null}
import os
from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(
    base_url="https://api.opper.ai/v3/compat",
    api_key=os.environ["OPPER_API_KEY"],
) as client:
    response = client.system_one(
        model="typesafe/jev-1.13.0",
        state="I was charged twice. Please refund the duplicate payment.",
        questions={
            "refund_requested": Noul(
                instructions="Is the customer requesting a refund?"
            ),
        },
    )

print(response.nouls["refund_requested"].noul)
```

```typescript TypeScript theme={null}
import { noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
    baseURL: "https://api.opper.ai/v3/compat",
    apiKey: process.env.OPPER_API_KEY!,
});

const response = await client.systemOne({
    model: "typesafe/jev-1.13.0",
    state: "I was charged twice. Please refund the duplicate payment.",
    questions: {
        refund_requested: noul("Is the customer requesting a refund?"),
    },
});
console.log(response.answers.refund_requested.noul);
```

Your organization needs a card on file. TypeSafe evaluation models use the System One protocol; use the TypeSafe SDK for these models. See [Classification & scoring](https://docs.opper.ai/build/gateway/evaluations.md) for `noul`, `choice`, and `score`, supported model aliases, and gateway limits.

OpenAI's `gpt-6-luna-decisions` answers System One too.

## Cross-vendor models

For generation models, the `model` field is provider-prefixed: `openai/gpt-5.5`, `anthropic/claude-sonnet-4-6`, `gemini/gemini-3.1-pro-preview`. You can call these generation models from the OpenAI, Anthropic, or Google AI SDK. Your code calling `client.messages.create(...)` with the Anthropic SDK can still talk to a Google model.

> [!TIP]
>
> Browse the full catalog on the [Models](https://docs.opper.ai/capabilities/models.md) page.

## Opper extras

For generation requests, the OpenAI, Anthropic, and Google AI SDKs let you send Opper-specific options through an extras field. Use them to attach tags for filtering traces, link a call to a parent span, or skip automatic scoring.

TypeSafe System One requests accept only `model`, `state`, and `questions`; the extras below are unsupported on that endpoint.

OpenAI Decisions requests accept only `model`, `input`, `questions`, and `safety_identifier`, so the extras are unsupported there too.

| Option | Does this |
| - | - |
| `tags` | A key/value object for grouping calls in traces. |
| `span_uuid` | Attach this call to a parent span you created with the Opper SDK. |
| `evaluate` | Set to `false` to skip [score check](https://docs.opper.ai/control-plane/rules/checks.md#score-checks) scoring. |

```python Python with extras theme={null}
response = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "tags": {"user_id": "u_123"},
        "evaluate": False,
    },
)
```

> [!NOTE]
>
> **Per-request fallbacks: `models`, on chat completions only.** The Chat
> Completions endpoint reads the same `models` array OpenRouter does: the
> primary in `model`, the rest in `models`, tried in order when the one before
> fails for any reason. Omit `model` and the first entry is the primary. A
> [compliance rule](https://docs.opper.ai/control-plane/rules/overview.md) that blocks an entry removes
> it from the chain without an error. Which model answered is in
> `meta.routing.served` and the `X-Opper-Served-Model` header; the response
> `model` echoes what you sent.
>
> ```python theme={null}
> client.chat.completions.create(
>     model="openai/gpt-5.6-luna",
>     messages=[{"role": "user", "content": "Hello"}],
>     extra_body={"models": ["azure/gpt-5.6-luna", "deepseek-v4.1-flash"]},
> )
> ```
>
> The other endpoints on this page do not read `models` or `fallback_models`.
> For a chain you manage in one place, with ranking, versions and rollback,
> build a [dynamic route](https://docs.opper.ai/capabilities/routes/overview.md) for generation models
> and call its name as `model` from the OpenAI, Anthropic, or Google AI SDK
> on supported generation endpoints.

To attribute usage and **cost** per customer or team — not just label traces — send tags with the `X-Opper-Tags` header instead, then group spend by tag in analytics. See [Tags & usage attribution](https://docs.opper.ai/build/gateway/usage-attribution.md).

## All the URLs

You usually don't need this. Your SDK appends the right path. For reference:

| URL | What it mimics |
| - | - |
| `POST /v3/compat/chat/completions` | OpenAI Chat Completions |
| `POST /v3/compat/responses` | OpenAI Responses API |
| `POST /v3/compat/embeddings` | OpenAI Embeddings |
| `POST /v3/compat/decisions` | [OpenAI Decisions](https://docs.opper.ai/build/gateway/evaluations.md) |
| `POST /v3/compat/v1/messages` | Anthropic Messages |
| `GET /v3/compat/v1/models` | Anthropic Models list |
| `POST /v3/compat/v1beta/interactions` | Google AI Interactions |
| `POST /v3/compat/openresponses` | [OpenResponses](https://openresponses.org) (vendor-neutral) |
| `POST /v3/compat/v1/systemone` | [TypeSafe System One](https://docs.opper.ai/build/gateway/evaluations.md) |

## Hostnames: global and EU

The same gateway is reachable on three hostnames. All of them take the same auth and serve the same models.

| Hostname | What it is |
| - | - |
| `api.opper.ai/v3/compat` | The canonical URL used above. Served from the EU (Stockholm). |
| `gw.opper.ai` | Global edge endpoint — TLS terminates at the CDN edge nearest your callers, then rides an accelerated path to the EU backend. |
| `eu.gw.opper.ai` | EU-resident twin of `gw` — TLS terminates only in Stockholm, for hard EU-residency requirements. |

The `gw` hosts also serve the vendor paths at cleaner base URLs, so SDK config gets shorter:

```text theme={null}
OpenAI SDK:     base_url = "https://gw.opper.ai/openai/v1"
Anthropic SDK:  base_url = "https://gw.opper.ai/anthropic"
Google AI SDK:  base_url = "https://gw.opper.ai/google"
```

## Frameworks

> [card] [Vercel AI SDK](https://docs.opper.ai/integrations/frameworks/vercel-ai-sdk.md)
>
> Use Opper's native provider for `streamText` and `generateObject`. No compat layer needed.

> [card] [LangChain / LlamaIndex](https://docs.opper.ai/integrations/overview.md)
>
> Point them at the `/v3/compat` base URL.

## What's next

> [card] [Tool calling](https://docs.opper.ai/build/gateway/tools.md)
>
> Let the model invoke your tools.

> [card] [Vision & PDFs](https://docs.opper.ai/build/multimodal/vision-pdfs.md)
>
> Send images and documents in messages.

> [card] [Streaming](https://docs.opper.ai/build/gateway/streaming.md)
>
> Stream the response token-by-token.

> [card] [Structured output](https://docs.opper.ai/build/gateway/structured-output.md)
>
> Get JSON back, validated against a schema.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.