Punti chiave
- Installa openai, poi crea OpenAI(base_url=..., api_key=...) con il modello impostato su uncensored.
- Streaming, modalità JSON e chiamata di funzioni usano i parametri standard, e l'async funziona allo stesso modo.
- Limita la concorrenza a 8 con un semaforo e lascia che l'SDK ritenti le risposte 429.
- Leggi X-Balance-USD dalle intestazioni della risposta grezza per monitorare il tuo credito dal codice.
Esempio minimo funzionante
Ecco la configurazione proxy api openai python più breve e utile. Presuppone Python 3.9 o superiore, una chiave dalla pagina delle chiavi API, il pacchetto installato con pip install openai e la chiave esportata come 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)L'endpoint è compatibile con OpenAI, ma è un servizio separato. Non è l'API ufficiale di OpenAI o di qualsiasi altro fornitore e ospita un solo modello, uncensored. Esistono solo due route: POST /v1/chat/completions e GET /v1/models, quindi attieniti all'interfaccia di completamento chat dell'SDK.
Alcune note su quel codice. La chiave proviene da una variabile d'ambiente invece che da un valore letterale, quindi non finisce mai nel controllo versione. L'oggetto usage nella risposta contiene i conteggi esatti dei token su cui si basa il fatturato, utile per il logging. E max_tokens è opzionale: se lo ometti, il completamento potrebbe usare il resto della finestra, il che va bene per le storie ma è costoso per un loop con un bug.
Token di streaming in arrivo
Lo streaming usa eventi server-sent. Passa stream=True e itera sui chunk. La parte finale dello streaming contiene l'utilizzo dei token, quindi proteggi gli chunk senza scelte.
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)Un dettaglio operativo: una chiamata in streaming occupa uno dei tuoi slot di concorrenza fino alla fine dello streaming. Se il tuo codice esce dal loop prima, chiudi lo streaming (stream.close()) così lo slot viene liberato.
Un'app web di solito avvolge questo loop in un generatore e inoltra ogni pezzo al browser. Con FastAPI, questo significa restituire un StreamingResponse che genera le parti di testo. Mantieni la chiave sul server in questo design. Il browser parla con la tua route, e la tua route parla con l'API, quindi la chiave non viene mai esposta al codice client.
Client asincroni e concorrenza controllata
Una chiave completa consente 8 richieste simultanee e 300 al minuto. Una chiave di prova ne consente 2 e 60. Se lanci 200 coroutine con asyncio.gather, raccoglierai errori 429 con il codice concurrency. Un semaphore risolve il problema prima che accada.
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())Usa 2 come dimensione del semaphore mentre sei sulla chiave di prova. L'SDK riprova le risposte 429 con backoff per impostazione predefinita, e max_retries aumenta il numero di tentativi. Per il sovraccarico temporaneo il servizio risponde con 429 e Retry-After: 5, che l'SDK onora.
Un semaphore limita solo le richieste in corso all'interno di un singolo processo. Se esegui più worker, dividi il limite tra di loro: con una chiave completa, quattro worker dovrebbero usare ciascuno un semaphore di 2. Il limite per minuto di 300 è condiviso da tutti, quindi una coda con un tasso costante è meglio di un burst per grandi lavori offline. Il limite del corpo di 8 MB raramente è un problema per la chat, ma si applica a ogni richiesta.
Chiamate di strumenti e modalità JSON
Entrambi funzionano attraverso i parametri normali. Per la modalità JSON, imposta response_format e chiedi JSON nel 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"])La chiamata di funzioni richiede un passaggio extra: esegui la funzione tu stesso e restituisci l'output come messaggio tool.
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)Il valore restituito per il dado qui è inserito direttamente nel codice per brevità. Nel codice reale, chiama la tua funzione con sides e invia il suo risultato.
Due altri dettagli sugli strumenti. Usa tool_choice quando devi forzare una funzione specifica invece di lasciare che il modello decida. E mantieni le descrizioni degli strumenti specifiche: il modello sceglie una funzione solo dal suo nome e descrizione, quindi "Lancia un dado con il numero di facce dato" funziona meglio di "dadi". Se una risposta contiene diverse chiamate di funzioni, eseguile tutte e aggiungi un messaggio tool per ogni ID chiamata prima di chiedere la risposta finale.
Errori, retry e cronologia conversazioni
L'SDK genera eccezioni tipizzate, il che rende la gestione degli errori breve. Un 429 genera openai.RateLimitError, un errore di rete genera openai.APIConnectionError, e altri stati non riusciti generano openai.APIStatusError. L'SDK ha già riprovato quando vedi il primo, quindi ciò che raggiunge il tuo codice è una chiamata che ha fallito ripetutamente.
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."}]))Il codice legge Retry-After quando il servizio lo invia, il che accade in caso di sovraccarico temporaneo (il valore è 5 secondi). Quando l'intestazione è assente, fa backoff secondo il proprio programma. Nota che il loop non cattura tutti gli errori: una richiesta errata non migliorerà con un retry, quindi lasciala propagare.
La cronologia delle conversazioni è l'altra parte dello stato. L'API non la memorizza per te, quindi il tuo programma possiede la lista dei messaggi. Una semplice politica che funziona bene: mantieni il messaggio di sistema, mantieni gli ultimi N turni e, quando il totale supera una dimensione che scegli, chiedi al modello di riassumere la parte più vecchia in un breve messaggio.
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] + recentI riassunti costano anche token, ma si ripagano da soli: una conversazione che altrimenti reinvierebbe 20.000 token ad ogni turno scende a poche migliaia.
Lettura del saldo e ID richiesta
Ogni risposta include X-Request-Id e X-Balance-USD. L'SDK nasconde le intestazioni per impostazione predefinita, ma with_raw_response le espone fornendo comunque l'oggetto analizzato.
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)Registra l'ID richiesta con ogni errore. Se devi contattare il team tramite la pagina di supporto, quell'ID punta direttamente alla chiamata.
L'intestazione del saldo è utile oltre al logging. Un lavoro pianificato può leggerlo dopo ogni batch e fermarsi quando il credito scende sotto una soglia che imposti, o inviarti un messaggio così puoi ricaricare prima che gli utenti se ne accorgano. Il credito non scade mai, quindi non c'è pressione per spenderlo. I ricarichi sono importi interi da $20 a $500, quindi puoi ricaricare in passi più grandi se preferisci.
Senza SDK: requests o httpx
Se preferisci evitare la dipendenza, l'API è abbastanza semplice per un client HTTP standard.
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"])Imposta un timeout generoso per le completazioni lunghe. Il modello può utilizzare fino a 100.000 token della finestra, a seconda di quanto spazio lascia libero il prompt, quindi una richiesta senza limiti per una narrativa lunga può richiedere del tempo.
Lo stesso approccio funziona per lo streaming. Aggiungi "stream": true al corpo JSON, passa stream=True a requests.post e leggi la risposta con iter_lines(). Ogni riga di evento inizia con data: seguito da JSON, e lo streaming termina con un marcatore data: [DONE]. Analizzarlo manualmente è un buon esercizio di apprendimento, anche se per il codice di produzione l'SDK lo fa con meno casi limite, come linee parziali e riconnessioni.
Gestione del budget nel codice Python
I conteggi dei token in resp.usage ti permettono di calcolare la spesa per chiamata. Il prezzo è $0,15 per 1M token di input e $0,50 per 1M token di output.
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.25La seconda riga si controlla a mano: 1M token di input costano $0,15 e 200.000 token di output costano 0,2 x $0,50 = $0,10, il che fa $0,25. Le richieste fallite o rifiutate non vengono addebitate, quindi non devi sottrarle. I ricarichi partono da $20, e la pagina dei prezzi elenca i bonus a $50, $100 e $200.
Per l'elenco completo dei parametri e i codici di errore, consulta la documentazione.
Tieni un totale cumulativo nel tuo lavoro in modo che un loop non possa spendere più di quanto hai pianificato. Un lavoro batch che classifica 50.000 testi brevi con 400 token di input e 20 token di output ciascuno utilizza 20M di token di input e 1M di token di output. Questo costa 20 x $0,15 + 1 x $0,50 = $3,50. Se il tuo contatore indica che il lavoro ha raggiunto il doppio di quella cifra, qualcosa sta andando in loop.
