Belangrijkste punten
- Installeer openai en maak een OpenAI(base_url=..., api_key=...) aan met het model ingesteld op uncensored.
- Streaming, JSON-modus en tool calling gebruiken de standaardparameters en async werkt op dezelfde manier.
- Beperk de concurrency tot 8 met een semaphore en laat de SDK 429-responses retryen.
- Lees X-Balance-USD uit de raw response headers om je tegoed vanuit code te bewaken.
Minimaal werkend voorbeeld
Hier is de kortst mogelijke bruikbare setup voor de openai api proxy in Python. Het gaat uit van Python 3.9 of nieuwer, een API key van de API key-pagina, het pakket geïnstalleerd met pip install openai en de sleutel geëxporteerd als UNCENSORED_API_KEY.
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)Het endpoint is OpenAI-compatible, maar het is een aparte service. Het is niet de officiële API van OpenAI of een andere leverancier, en het hostt één model, uncensored. Er bestaan slechts twee routes: POST /v1/chat/completions en GET /v1/models, dus blijf bij de chat completions-interface van de SDK.
Enkele opmerkingen bij die code. De sleutel komt uit een omgevingsvariabele in plaats van een letterlijke waarde, dus deze komt nooit in versiebeheer terecht. Het usage-object in het antwoord bevat de exacte token-tellingen waar de factuur op gebaseerd is, wat nuttig is voor logging. En max_tokens is optioneel: laat het weg en de generatie kan de rest van het venster gebruiken, wat prima is voor verhalen maar duur voor een lus met een bug.
Streaming tokens terwijl ze binnenkomen
Streaming gebruikt serververzonden gebeurtenissen. Geef stream=True door en itereer over de fragmenten. Het laatste deel van de stream bevat tokengebruik, dus controleer op fragmenten zonder keuzes.
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)Een operationeel detail: een streamende aanroep bezet een van je concurrency-slots tot de stream eindigt. Als je code de lus vroegtijdig verlaat, sluit dan de stream (stream.close()) zodat het slot vrijkomt.
Een webapp wrap deze lus meestal in een generator en stuurt elk stuk naar de browser. Met FastAPI betekent dat het retourneren van een StreamingResponse die de tekstdelen yieldt. Houd de sleutel op de server in dat ontwerp. De browser communiceert met je route, en je route communiceert met de API, dus de sleutel wordt nooit aan client-code blootgesteld.
Asynchrone clients en gecontroleerde gelijktijdigheid
Een volledige sleutel staat 8 gelijktijdige verzoeken tegelijk en 300 per minuut toe. Een proefsleutel staat 2 en 60 toe. Als je 200 coroutines afvuurt met asyncio.gather, krijg je 429-fouten met de code concurrency. Een semaphore lost dit op voordat het gebeurt.
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())Gebruik 2 als semaphoregrootte zolang je de proefsleutel gebruikt. De SDK herhaalt 429-responses standaard met backoff, en max_retries verhoogt het aantal pogingen. Bij tijdelijke overbelasting antwoordt de service met 429 en Retry-After: 5, wat de SDK respecteert.
Een semaphore beperkt alleen het aantal gelijktijdige verzoeken binnen één proces. Als je meerdere werkers draait, deel je de limiet tussen hen: met een volledige sleutel moeten vier werkers elk een semaphore van 2 gebruiken. De limiet van 300 per minuut is voor allen samen, dus een wachtrij met een constante snelheid is beter dan een piek voor grote offline taken. De limiet van 8 MB voor de body is voor chat zelden een punt van zorg, maar geldt voor elk verzoek.
JSON-modus en toolaanroepen
Beide werken via de normale parameters. Voor JSON-modus stel je response_format in en vraag je JSON in de prompt.
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 vereist een extra stap: je voert de functie zelf uit en retourneert de output als een tool-bericht.
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)De waarde die wordt geretourneerd voor de dobbelsteen hier is hardcoded voor de beknopte weergave. In echte code roep je je functie aan met sides en stuur je het resultaat.
Twee meer details over tools. Gebruik tool_choice als je een specifieke functie moet forceren in plaats van het model te laten beslissen. En houd toolbeschrijvingen specifiek: het model kiest een functie op basis van naam en beschrijving, dus "Rol een dobbelsteen met het gegeven aantal zijden" werkt beter dan "dobbelstenen". Als een antwoord meerdere toolaanroepen bevat, voer ze dan allemaal uit en voeg één tool-bericht per call ID toe voordat je om het eindantwoord vraagt.
Fouten, herhalingen en gespreksgeschiedenis
De SDK gooit getypeerde uitzonderingen, wat foutafhandeling kort houdt. Een 429 gooit openai.RateLimitError, een netwerkfout gooit openai.APIConnectionError, en andere niet-successtatussen gooien openai.APIStatusError. De SDK heeft al opnieuw geprobeerd voordat je de eerste ziet, dus wat je code bereikt, is een aanroep die herhaaldelijk is mislukt.
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."}]))De code leest Retry-After wanneer de service dit stuurt, wat gebeurt bij tijdelijke overbelasting (de waarde is 5 seconden). Als de header ontbreekt, hanteert het zijn eigen schema voor backoff. Merk op dat de lus niet elke fout vangt: een slecht verzoek verbetert niet door een herhaling, dus laat het doorwerken.
Gespreksgeschiedenis is het andere stukje van de status. De API slaat dit niet voor je op, dus jouw programma is eigenaar van de lijst met berichten. Een eenvoudig beleid dat goed werkt: bewaar het systeembericht, bewaar de laatste N beurten, en als het totaal groter wordt dan een door jou gekozen grootte, vraag het model dan om het oudste deel samen te vatten in één kort bericht.
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] + recentSamenvattingen kosten ook tokens, maar ze betalen zichzelf terug: een gesprek dat anders 20.000 tokens bij elke beurt opnieuw zou versturen, daalt naar een paar duizend.
Saldo en verzoek-ID uitlezen
Elk antwoord bevat X-Request-Id en X-Balance-USD. De SDK verbergt headers standaard, maar with_raw_response maakt ze zichtbaar terwijl je nog steeds het verwerkte object krijgt.
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)Log de request ID bij elke fout. Als je het team via de ondersteuningspagina moet bereiken, verwijst die ID rechtstreeks naar het verzoek.
De balansheader is nuttig voor meer dan alleen logging. Een geplande taak kan deze na elke batch uitlezen en stoppen wanneer het tegoed onder een door jou ingestelde drempel daalt, of je een bericht sturen zodat je kunt opwaarderen voordat gebruikers het merken. Het tegoed verloopt nooit, dus er is geen druk om het uit te geven. Opwaarderingen zijn vaste bedragen van $20 tot $500, dus je kunt in grotere stappen bijvullen als je dat prefereert.
Zonder SDK: requests of httpx
Als je de afhankelijkheid wilt vermijden, is de API eenvoudig genoeg voor een gewone 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"])Stel een ruime time-out in voor lange voltooiingen. Het model kan zoveel van het 100.000-token contextvenster gebruiken als de prompt vrijlaat, dus een verzoek zonder limiet voor lange fictie kan even duren.
Dezelfde aanpak werkt voor streaming. Voeg "stream": true toe aan de JSON-body, voeg stream=True toe aan requests.post en lees het antwoord met iter_lines(). Elke evenementregel begint met data: gevolgd door JSON, en de stream eindigt met een data: [DONE] marker. Dit handmatig parseren is een goede leeroefening, maar voor productiecode doet de SDK dit met minder randgevallen, zoals gedeeltelijke regels en reconnects.
Budgettering in je Python-code
Token-tellingen in resp.usage laten je de kosten per aanroep berekenen. De prijs is $0,15 per 1M input tokens en $0,50 per 1M output tokens.
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.25De tweede regel controleer je met de hand: 1M input tokens kosten $0,15 en 200.000 output tokens kosten 0,2 x $0,50 = $0,10, wat $0,25 maakt. Mislukte of geweigerde verzoeken worden niet in rekening gebracht, dus je hoeft ze niet af te trekken. Opwaarderingen beginnen bij $20, en de prijspagina vermeldt de bonussen bij $50, $100 en $200.
Voor de volledige parameterlijst en foutcodes, zie de documentatie.
Houd een lopend totaal bij in je taak zodat een lus niet meer kan uitgeven dan je hebt gepland. Een batchtaak die 50.000 korte teksten classificeert met 400 input tokens en 20 output tokens per stuk, gebruikt 20M input tokens en 1M output tokens. Dat kost 20 x $0,15 + 1 x $0,50 = $3,50. Als je teller aangeeft dat de taak het dubbele daarvan heeft bereikt, loopt er iets vast.
