Ein OpenAI-kompatibles Gateway für deine Agenten

Quickstart

Base-URL für alle OpenAI-kompatiblen Calls:

https://promptopoly.com/api/v1/proxy/v1

Erzeuge einen Proxy-Key im Cockpit unter /app → AI-Proxy. Der Key beginnt mit pk_ und wird einmal angezeigt.

Dein erster Request (OpenAI-kompatibel):

curl -s https://promptopoly.com/api/v1/proxy/v1/chat/completions \
  -H "Authorization: Bearer pk_REPLACE_WITH_YOUR_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Sag Hallo."}]}'

Authentifizierung

Jeder Request trägt den Proxy-Key. Drei gleichwertige Wege — empfohlen ist der OpenAI-konforme Bearer-Header:

• Authorization: Bearer pk_… — empfohlen, funktioniert mit jedem OpenAI-SDK out-of-the-box.
• X-Proxy-Key: pk_… — alternativer Header.
• x-api-key: pk_… — Fallback für das Anthropic-SDK / Claude Code (sendet den Key als x-api-key).

Endpunkt-Referenz

Fehlerformat & Statuscodes

Fehler kommen als OpenAI-kompatibles Objekt — typisierte Exceptions im OpenAI-SDK funktionieren:

{
  "error": {
    "message": "Budget exceeded for today.",
    "type": "insufficient_quota",
    "code": "budget_exceeded",
    "param": null
  },
  "limit_info": { "budget": "daily", "used_cents": 1234, "limit_cents": 1000 }
}

Ein unbekanntes Modell liefert model_not_found mit einer available:-Liste der erlaubten Modelle in error.message.

Integrationsbeispiele

OpenAI SDK — Python

from openai import OpenAI

client = OpenAI(
    api_key="pk_REPLACE_WITH_YOUR_PROXY_KEY",
    base_url="https://promptopoly.com/api/v1/proxy/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Sag Hallo in einem Satz."}],
    stream=False,
)
print(resp.choices[0].message.content)

OpenAI SDK — Node.js (ESM)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "pk_REPLACE_WITH_YOUR_PROXY_KEY",
  baseURL: "https://promptopoly.com/api/v1/proxy/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(resp.choices[0].message.content);

LangChain

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

llm = ChatOpenAI(
    model="gpt-4o-mini",
    api_key="pk_REPLACE_WITH_YOUR_PROXY_KEY",
    base_url="https://promptopoly.com/api/v1/proxy/v1",
)

answer = llm.invoke([HumanMessage(content="Fasse Promptopoly in einem Satz zusammen.")])
print(answer.content)

Claude Code / Anthropic SDK — nativer /v1/messages

Claude Code nutzt dieselbe Base-URL über die Umgebungsvariable ANTHROPIC_BASE_URL:

export ANTHROPIC_BASE_URL="https://promptopoly.com/api/v1/proxy"
export ANTHROPIC_API_KEY="pk_REPLACE_WITH_YOUR_PROXY_KEY"

Das Anthropic-SDK spricht den nativen Endpunkt direkt an:

from anthropic import Anthropic

client = Anthropic(
    api_key="pk_REPLACE_WITH_YOUR_PROXY_KEY",
    base_url="https://promptopoly.com/api/v1/proxy",
)

msg = client.messages.create(
    model="claude-3-5-haiku-latest",
    max_tokens=256,
    messages=[{"role": "user", "content": "Sag Hallo in einem Satz."}],
)
print(msg.content[0].text)

Generisches Agent-Framework

Funktioniert mit jedem OpenAI-kompatiblen Agent-Framework: Provider auf „OpenAI-kompatibel", Base-URL, Key und Modell setzen.

{
  "provider": "openai-compatible",
  "model": "gpt-4o-mini",
  "api_key": "pk_REPLACE_WITH_YOUR_PROXY_KEY",
  "base_url": "https://promptopoly.com/api/v1/proxy/v1",
  "options": { "stream": true, "temperature": 0.7 }
}

cURL — streaming + non-streaming

# Non-streaming
curl -s https://promptopoly.com/api/v1/proxy/v1/chat/completions \
  -H "Authorization: Bearer pk_REPLACE_WITH_YOUR_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Sag Hallo."}]}'

# Streaming (SSE): text/event-stream, endet auf data: [DONE]
curl -N https://promptopoly.com/api/v1/proxy/v1/chat/completions \
  -H "Authorization: Bearer pk_REPLACE_WITH_YOUR_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"Zähle bis drei."}]}'

Betrieb

Harte Budgets & Wallet

Tages-, Wochen- oder Monatsbudgets werden race-sicher reserviert, bevor der Call das Gateway verlässt. Prepaid-Wallet-Debit in Cent — kein Call ohne ausreichend Guthaben.

Modell-Aliase

Stabile Alias-Namen (z. B. gpt-4o → gpt-4o-mini) entkoppeln deinen Code von konkreten Provider-Modellen. Aliase, deren Ziel nicht existiert, werden nicht angelegt; die Auflösung ist fail-open.

Failover

Schlägt ein Provider fehl (Timeout/5xx) bevor das erste Byte gestreamt wurde, routet das Gateway auf das nächste Modell der Failover-Kette. Beim nativen Anthropic-Endpunkt gibt es aus Format-Gründen kein Provider-Failover.

Audit & DSGVO

Jeder Call landet in einer manipulationssicheren Hash-Chain. Response-Payloads werden automatisch nach 7 Tagen entfernt (Retention). Made in Germany, DSGVO-konform.

Rate-Limits

Zusätzlich zu den Budgets schützt ein Rate-Limit das Gateway. Überschreitungen liefern 429 (rate_limit_error).

Grenzen

• n > 1 (mehrere Antworten pro Request) wird nicht unterstützt.
• Natives /v1/messages ist auf den Anthropic-Provider beschränkt (kein Failover, kein Modell-Rewrite über Aliase hinweg).
• Fehlt die Provider-Usage im Stream, schätzt das Gateway Tokens (ca. 4 Zeichen/Token) und markiert usage_estimated=1.