Wichtige Punkte
- Installiere openai, erstelle dann OpenAI(base_url=..., api_key=...) mit dem Modell auf uncensored.
- Streaming, JSON-Modus und Tool-Calling nutzen die Standardparameter, und Async funktioniert genauso.
- Begrenze die Parallelität auf 8 mit einem Semaphor und lass das SDK 429-Antworten wiederholen.
- Lese X-Balance-USD aus den Rohantwort-Headern, um dein Guthaben im Code zu überwachen.
Minimal funktionierendes Beispiel
Hier ist die kürzeste nützliche openai-api-proxy-python-Einrichtung. Sie setzt Python 3.9 oder höher voraus, einen Schlüssel von der API-Schlüssel-Seite, das mit pip install openai installierte Paket und den als UNCENSORED_API_KEY exportierten Schlüssel.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.openaiapiproxy.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Give me a one-line product tagline for a hiking app."}],
temperature=0.8,
max_tokens=60,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)Der Endpunkt ist OpenAI-kompatibel, aber ein separater Dienst. Es ist nicht die offizielle API von OpenAI oder einem anderen Anbieter, und er hostet nur ein Modell, uncensored. Es gibt nur zwei Routen: POST /v1/chat/completions und GET /v1/models, also bleibe bei der Chat-Vervollständigungs-Schnittstelle des SDK.
Einige Hinweise zu diesem Code. Der Schlüssel stammt aus einer Umgebungsvariable statt aus einem Literal, landet also nie im Versionskontrollsystem. Das usage-Objekt in der Antwort enthält die exakten Token-Anzahlen, auf die die Abrechnung basiert, was für Logging nützlich ist. Und max_tokens ist optional: Lass es weg, und die Generierung kann den Rest des Fensters nutzen, was für Geschichten in Ordnung ist, aber für eine Schleife mit einem Fehler teuer werden kann.
Streaming-Token beim Eintreffen
Streaming nutzt Server-Sent Events. Übergebe stream=True und iteriere über die Blöcke. Der letzte Teil des Streams enthält Token-Nutzungsdaten, also schütze dich vor Blöcken ohne Choices.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Tell a two-paragraph ghost story."}],
stream=True,
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
if usage:
print("tokens:", usage.prompt_tokens, usage.completion_tokens)Ein betrieblicher Hinweis: Eine Streaming-Anfrage belegt einen deiner Parallelitäts-Slots, bis der Stream endet. Wenn dein Code die Schleife vorzeitig verlässt, schließe den Stream (stream.close()), damit der Slot freigegeben wird.
Eine Web-App packt diese Schleife normalerweise in einen Generator und leitet jeden Teil an den Browser weiter. Mit FastAPI bedeutet das, einen StreamingResponse zurückzugeben, der die Textteile ausliefert. Halte den Schlüssel in diesem Design auf dem Server. Der Browser spricht mit deiner Route, und deine Route spricht mit der API, sodass der Schlüssel niemals Client-Code ausgesetzt ist.
Async-Clients und kontrollierte Parallelität
Ein Voll-Key erlaubt 8 gleichzeitige Anfragen und 300 pro Minute. Ein Trial-Key erlaubt 2 und 60. Wenn du 200 Coroutinen mit asyncio.gather startest, sammelst du 429-Fehler mit dem Code concurrency. Ein Semaphore behebt das, bevor es passiert.
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=4)
gate = asyncio.Semaphore(8)
async def ask(prompt: str) -> str:
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
)
return r.choices[0].message.content
async def main():
prompts = [f"Write a title for chapter {i} of a sea adventure." for i in range(1, 41)]
results = await asyncio.gather(*(ask(p) for p in prompts))
for t in results:
print(t)
asyncio.run(main())Nutze 2 als Semaphore-Größe, solange du den Trial-Key hast. Das SDK wiederholt 429-Antworten standardmäßig mit Backoff, und max_retries erhöht die Anzahl der Versuche. Bei temporärer Überlastung antwortet der Dienst mit 429 und Retry-After: 5, was das SDK beachtet.
Ein Semaphore begrenzt nur aktive Anfragen innerhalb eines Prozesses. Wenn du mehrere Worker ausführst, teile das Limit zwischen ihnen auf: Bei einem Voll-Key sollten vier Worker jeweils ein Semaphore von 2 nutzen. Das pro Minute geltende Limit von 300 wird von allen geteilt, daher ist eine Warteschlange mit gleichmäßiger Rate besser als ein Burst für große Offline-Jobs. Das 8-MB-Körperlimit ist für Chats selten relevant, gilt aber für jede Anfrage.
JSON-Modus und Tool-Aufrufe
Beides funktioniert über die normalen Parameter. Für den JSON-Modus setze response_format und fordere JSON im Prompt an.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Return JSON with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy game."},
],
)
npc = json.loads(r.choices[0].message.content)
print(npc["name"])Tool-Calling erfordert einen zusätzlichen Schritt: Du führst die Funktion selbst aus und gibst die Ausgabe als tool-Nachricht zurück.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll a die with the given number of sides.",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
messages = [{"role": "user", "content": "Roll a twenty-sided die for me."}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
sides = json.loads(call.function.arguments)["sides"]
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": "14"})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)Der zurückgegebene Wert für den Würfel hier ist der Kürze halber fest codiert. In echtem Code ruf deine Funktion mit sides auf und sende das Ergebnis.
Zwei weitere Details zu Tools. Nutze tool_choice, wenn du eine bestimmte Funktion erzwingen musst, anstatt das Modell entscheiden zu lassen. Und halte Tool-Beschreibungen spezifisch: Das Modell wählt eine Funktion nur anhand von Name und Beschreibung aus, also funktioniert "Würfle mit der angegebenen Anzahl an Seiten" besser als "Würfel". Wenn eine Antwort mehrere Tool-Aufrufe enthält, führe sie alle aus und füge vor der Anfrage der endgültigen Antwort eine tool-Nachricht pro Call-ID an.
Fehler, Wiederholungen und Konversationsverlauf
Das SDK wirft typisierte Ausnahmen, was die Fehlerbehandlung kurz hält. Eine 429 löst openai.RateLimitError aus, ein Netzwerkfehler löst openai.APIConnectionError aus, und andere Nicht-Erfolgsstatus lösen openai.APIStatusError aus. Das SDK hat bereits wiederholt, bevor du die erste siehst, also erreicht deinen Code ein Aufruf, der wiederholt fehlgeschlagen ist.
import time
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=2)
def chat(messages, attempts=4):
delay = 2.0
for n in range(attempts):
try:
r = client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content
except openai.RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", delay))
time.sleep(wait)
delay *= 2
except openai.APIConnectionError:
time.sleep(delay)
delay *= 2
raise RuntimeError("gave up after repeated failures")
print(chat([{"role": "user", "content": "Name a color."}]))Der Code liest Retry-After, wenn der Dienst ihn sendet, was bei temporärer Überlastung passiert (der Wert ist 5 Sekunden). Wenn der Header fehlt, weicht er nach eigenem Zeitplan aus. Beachte, dass die Schleife nicht jeden Fehler abfängt: Eine ungültige Anfrage verbessert sich durch eine Wiederholung nicht, also lasse sie weiter propagieren.
Der Konversationsverlauf ist die andere Zustandskomponente. Die API speichert ihn nicht für dich, also besitzt dein Programm die Liste der Nachrichten. Eine einfache Strategie, die gut funktioniert: Behalte die Systemnachricht, behalte die letzten N Runden, und wenn die Gesamtzahl über eine von dir gewählte Größe wächst, bitte das Modell, den ältesten Teil in eine kurze Nachricht zusammenzufassen.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def compact(history, keep=6):
system, rest = history[0], history[1:]
if len(rest) <= keep:
return history
old, recent = rest[:-keep], rest[-keep:]
text = "\n".join(m["role"] + ": " + m["content"] for m in old)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize this conversation in 120 words:\n" + text}],
max_tokens=250,
)
summary = {"role": "system", "content": "Earlier in this conversation: " + r.choices[0].message.content}
return [system, summary] + recentZusammenfassungen kosten ebenfalls Token, aber sie amortisieren sich: Eine Konversation, die sonst bei jeder Runde 20.000 Token neu senden würde, sinkt auf ein paar tausend.
Kontostand und Request-ID abfragen
Jede Antwort enthält X-Request-Id und X-Balance-USD. Das SDK verbirgt Header standardmäßig, aber with_raw_response macht sie verfügbar, während es dir weiterhin das analysierte Objekt liefert.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance USD:", raw.headers.get("X-Balance-USD"))
completion = raw.parse()
print(completion.choices[0].message.content)Logge die Request-ID bei jedem Fehler. Wenn du das Team über die Support-Seite kontaktieren musst, zeigt diese ID direkt auf den Aufruf.
Der Kontostand-Header ist auch über das Logging hinaus nützlich. Ein geplanter Job kann ihn nach jedem Batch lesen und stoppen, wenn das Guthaben unter einen von dir festgelegten Schwellenwert fällt, oder dir eine Nachricht senden, damit du aufladen kannst, bevor Nutzer es bemerken. Guthaben verfällt nie, also besteht kein Druck, es auszugeben. Aufladungen sind ganze Beträge von $20 bis $500, sodass du in größeren Schritten nachfüllen kannst, wenn du das bevorzugst.
Ohne SDK: requests oder httpx
Wenn du die Abhängigkeit vermeiden möchtest, ist die API einfach genug für einen normalen HTTP-Client.
import requests
r = requests.post(
"https://api.openaiapiproxy.com/v1/chat/completions",
headers={"Authorization": "Bearer YOUR_KEY"},
json={
"model": "uncensored",
"messages": [{"role": "user", "content": "Name three sea shanty topics."}],
},
timeout=120,
)
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])Setze einen großzügigen Timeout für lange Completions. Das Modell kann so viel vom 100.000-Token-Fenster nutzen, wie der Prompt frei lässt, sodass eine unlimitierte Anfrage für lange Fiktion eine Weile dauern kann.
Der gleiche Ansatz funktioniert für Streaming. Füge "stream": true zum JSON-Körper hinzu, übergebe stream=True an requests.post und lese die Antwort mit iter_lines(). Jede Ereigniszeile beginnt mit data: gefolgt von JSON, und der Stream endet mit einem data: [DONE]-Marker. Das manuell zu parsen ist eine gute Lernübung, aber für Produktionscode erledigt das SDK das mit weniger Randfällen, wie partiellen Zeilen und Reconnects.
Budgetierung in deinem Python-Code
Token-Anzahlen in resp.usage lassen dich die Ausgaben pro Aufruf berechnen. Der Preis ist $0,15 pro 1M Input-Token und $0,50 pro 1M Output-Token.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def cost_usd(prompt_tokens: int, completion_tokens: int) -> float:
return prompt_tokens * 0.15 / 1_000_000 + completion_tokens * 0.50 / 1_000_000
r = client.chat.completions.create(model="uncensored", messages=[{"role": "user", "content": "Hi"}])
print(cost_usd(r.usage.prompt_tokens, r.usage.completion_tokens))
print(cost_usd(1_000_000, 200_000)) # 0.25Die zweite Zeile lässt sich von Hand prüfen: 1M Input-Token kosten $0,15 und 200.000 Output-Token kosten 0,2 x $0,50 = $0,10, was $0,25 ergibt. Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, also musst du sie nicht abziehen. Aufladungen beginnen bei $20, und die Preisseite listet die Boni bei $50, $100 und $200 auf.
Für die vollständige Parameterliste und Fehlercodes sieh dir die Dokumentation an.
Halte in deinem Job eine laufende Summe, damit eine Schleife nicht mehr ausgeben kann, als du geplant hast. Ein Batch-Job, der 50.000 kurze Texte klassifiziert, mit 400 Input-Token und 20 Output-Token pro Text, nutzt 20M Input-Token und 1M Output-Token. Das kostet 20 x $0,15 + 1 x $0,50 = $3,50. Wenn dein Zähler sagt, dass der Job das Doppelte kostet, läuft etwas in einer Schleife.
