Anthropic-SDK & Claude Code

Das Gateway nimmt unter POST /v1/messages Anfragen im Format der Anthropic-API an, dazu POST /v1/messages/count_tokens. Das Anthropic-SDK und Claude Code funktionieren deshalb, sobald die Basis-URL und der Schlüssel auf Noirdoc zeigen.

SDK installieren

Installieren Sie das Paket anthropic für Python oder @anthropic-ai/sdk für Node.js.

Shell

pip install anthropic

Shell

npm install @anthropic-ai/sdk

Client einrichten

Setzen Sie die Basis-URL auf https://api.noirdoc.de, ohne /v1. Das SDK hängt den Pfad /v1/messages selbst an.

Übergeben Sie den px--Schlüssel als auth_token (TypeScript: authToken). Das SDK sendet ihn dann im Header Authorization: Bearer. Als api_key übergeben, sendet das SDK ihn im Header x-api-key. Das Gateway nimmt beide Header an.

Das SDK liest die Werte auch aus ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN und ANTHROPIC_API_KEY. Setzen Sie eine der beiden Schlüssel-Variablen, nicht beide. Sonst sendet das SDK beide Header.

Python

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.noirdoc.de",
    auth_token=os.environ["NOIRDOC_API_KEY"],
)

message = client.messages.create(
    model="<modell-id>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hallo"}],
)
print(message.content[0].text)

TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.noirdoc.de",
  authToken: process.env.NOIRDOC_API_KEY,
});

const message = await client.messages.create({
  model: "<modell-id>",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hallo" }],
});
console.log(message.content);

Tokens zählen

client.messages.count_tokens (TypeScript: countTokens) ruft POST /v1/messages/count_tokens über das Gateway auf. Die Methode nimmt model und messages wie messages.create und gibt die Zahl der Eingabe-Tokens zurück.

Python

count = client.messages.count_tokens(
    model="<modell-id>",
    messages=[{"role": "user", "content": "Hallo"}],
)
print(count.input_tokens)

TypeScript

const count = await client.messages.countTokens({
  model: "<modell-id>",
  messages: [{ role: "user", content: "Hallo" }],
});
console.log(count.input_tokens);

Maskierung einschalten

Senden Sie den Header X-Noirdoc-Mask: on, mit default_headers (TypeScript: defaultHeaders) für jede Anfrage des Clients. Das Gateway entfernt den Header, bevor es die Anfrage an den Anbieter weiterleitet. Ob der Header wirkt, hängt von der Maskierungsrichtlinie Ihrer Organisation ab (siehe Maskierung einschalten).

Python

client = Anthropic(
    base_url="https://api.noirdoc.de",
    auth_token=os.environ["NOIRDOC_API_KEY"],
    default_headers={"X-Noirdoc-Mask": "on"},
)

TypeScript

const client = new Anthropic({
  baseURL: "https://api.noirdoc.de",
  authToken: process.env.NOIRDOC_API_KEY,
  defaultHeaders: { "X-Noirdoc-Mask": "on" },
});

Claude Code einrichten

Claude Code liest die Umgebungsvariablen ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN und ANTHROPIC_API_KEY. Setzen Sie ANTHROPIC_BASE_URL auf https://api.noirdoc.de und ANTHROPIC_AUTH_TOKEN auf Ihren px--Schlüssel. Claude Code sendet den Schlüssel dann im Header Authorization: Bearer.

ANTHROPIC_API_KEY funktioniert ebenfalls und sendet den Schlüssel im Header x-api-key. Setzen Sie nicht beide Variablen.

Das Modell wählen Sie mit ANTHROPIC_MODEL, zum Beispiel mit einer Modell-ID aus GET /v1/models. Claude Code ist für Claude-Modelle gebaut; Anthropic unterstützt Claude Code mit anderen Modellen über ein Gateway nicht.

Zusätzliche Header setzt Claude Code aus ANTHROPIC_CUSTOM_HEADERS, ein Paar Name: Wert pro Zeile. So schalten Sie die Maskierung für Claude Code ein: ANTHROPIC_CUSTOM_HEADERS="X-Noirdoc-Mask: on".

Mit POST /v1/messages/count_tokens zählt Claude Code die Tokens im Kontext. Das Gateway unterstützt diesen Endpunkt und rechnet ihn nicht ab. Für Claude über Google Vertex leitet es die Anfrage an die Zählmethode von Vertex weiter; Details stehen unter Messages.

Shell

export ANTHROPIC_BASE_URL="https://api.noirdoc.de"
export ANTHROPIC_AUTH_TOKEN="$NOIRDOC_API_KEY"
export ANTHROPIC_MODEL="<modell-id>"
claude

Fehler behandeln

Fehler des Gateways haben ein Fehlerobjekt mit "type": "proxy_error", einem code und einer message. Fehler des Anbieters gibt das Gateway mit Statuscode und Body des Anbieters weiter. Ein fehlender oder ungültiger Schlüssel ergibt Statuscode 401 mit dem Body {"detail": "..."}.

Im Anthropic-SDK steht der type am Fehler. Den code lesen Sie aus dem Body: in Python aus e.body["error"]["code"], in TypeScript aus dem Feld error.code von err.error. Prüfen Sie im Programm den code, nicht die message.

Python

import anthropic

try:
    message = client.messages.create(
        model="<modell-id>",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hallo"}],
    )
except anthropic.APIStatusError as e:
    provider = e.response.headers.get("x-noirdoc-provider")
    if e.type == "proxy_error":
        code = e.body["error"]["code"]
        print("Gateway:", e.status_code, code)
    elif provider:
        print("Anbieter:", provider, e.status_code)
    else:
        print("Gateway:", e.status_code, e.message)  # z. B. 401

TypeScript

type GatewayBody = {
  error?: { type?: string; code?: string };
};

try {
  const message = await client.messages.create({
    model: "<modell-id>",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hallo" }],
  });
} catch (err) {
  if (!(err instanceof Anthropic.APIError)) throw err;
  const body = err.error as GatewayBody | undefined;
  const provider = err.headers?.get("x-noirdoc-provider");
  if (body?.error?.type === "proxy_error") {
    console.log("Gateway:", err.status, body.error.code);
  } else if (provider) {
    console.log("Anbieter:", provider, err.status);
  } else {
    // z. B. 401
    console.log("Gateway:", err.status, err.message);
  }
}

Alle Codes und ihre Abhilfe stehen unter Fehlercodes. Streaming mit messages.stream beschreibt Streaming.

Status	Code	Bedeutung
400	`wrong_endpoint_for_model`	Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt.
402	`insufficient_credit`	Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage.
402	`key_budget_exhausted`	Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus.
403	`model_not_allowed_for_key`	Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels.
404	`model_not_available`	Die Modell-ID ist für die Organisation nicht verfügbar.