Flusso API LLM in Python: configurazione passo dopo passo
Indirizza l'SDK OpenAI a una nuova base URL, usa l'ID modello uncensored e aggiungi tentativi, esecuzioni parallele e chiamate di funzioni un livello alla volta.
Aggiornato

Punti chiave
- Installa openai, imposta base_url su https://api.veo3apis.com/v1 e usa il modello uncensored.
- Gestisci il 429 attendendo Retry-After; le richieste fallite non vengono addebitate.
- Dimensiona il pool di thread in base alla chiave: 8 worker per una chiave completa, 2 per la chiave di prova.
- Leggi X-Balance-USD dalle intestazioni della risposta per monitorare la spesa per esecuzione.
La versione breve
Per creare uno script di flusso API LLM in Python, installa l'SDK ufficiale di OpenAI, imposta la base URL su https://api.veo3apis.com/v1, usa la tua chiave come chiave API e chiama il modello uncensored. Nient'altro cambia. Il servizio è compatibile con OpenAI, quindi ogni pattern che già conosci dall'SDK funziona: chiamate chat plain, streaming, modalità JSON e tool calling.
Questo articolo costruisce un piccolo flusso a strati. Inizi con una singola chiamata, poi aggiungi configurazione dalle variabili d'ambiente, un wrapper di retry, un runner parallelo, una chiamata di funzione e il monitoraggio del saldo. Ogni strato è breve e puoi fermarti a qualsiasi livello che soddisfi le tue esigenze.
Il modello è un modello a pesi aperti gestito da un provider indipendente. Non è l'API ufficiale di alcun grande fornitore e non è un router, quindi c'è un solo ID modello da ricordare. Gestisce solo testo. Non ci sono generazione di immagini, audio o video, né embedding né fine-tuning.
Installa l'SDK e fai la prima chiamata
Hai bisogno di Python 3.9 o superiore. Installa l'SDK:
pip install openai
Crea una chiave dalla pagina chiave API dopo esserti registrato con Google o con email e password. La pagina include anche un’assegnazione in un clic di $0,50 di credito di prova, valido per 7 giorni, uno per persona, senza carta. Poi esegui la chiamata più piccola possibile:
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "List three uses for a hosted text API."},
],
)
print(resp.choices[0].message.content)
print(resp.usage)
Se il codice stampa testo e un oggetto usage, autenticazione, routing e l'ID modello sono tutti corretti. L'SDK invia la tua chiave come Authorization: Bearer, e la richiesta va a POST /v1/chat/completions. Puoi controllare quali ID modello vede la tua chiave con client.models.list(), che chiama GET /v1/models.
Una versione curl grezza è utile quando si esegue il debug da un server senza Python:
curl https://api.veo3apis.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello."}]}'
Mantieni la configurazione in un unico client
Fissare una chiave in uno script è il modo più veloce per farla trapelare in un repository. Leggi entrambi i valori dall'ambiente e configura il client in un unico punto in modo che ogni fase del flusso di lavoro lo condivida.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ.get("LLM_BASE_URL", "https://api.veo3apis.com/v1"),
api_key=os.environ["LLM_API_KEY"],
max_retries=0,
timeout=120,
)
MODEL = "uncensored"
def ask(system: str, user: str, **kwargs) -> str:
resp = client.chat.completions.create(
model=MODEL,
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user},
],
**kwargs,
)
return resp.choices[0].message.content
Qui ci sono due scelte deliberate. max_retries=0 disabilita i ritentativi automatici dell'SDK, così la logica di retry nella sezione successiva è l'unica attiva, rendendo il comportamento più facile da analizzare. Il timeout di 120 secondi lascia spazio a completamenti lunghi; la finestra di contesto è di 100.000 token per prompt e completamento, e una risposta grande richiede tempo per essere inviata in streaming. I parametri di campionamento come temperature, top_p, stop, seed e le penalità passano tramite **kwargs come di consueto.
Ritenta gli errori giusti
Ogni workflow reale incontra prima o poi i limiti di richieste. Una chiave completa permette 300 richieste al minuto e 8 in parallelo. Una chiave di prova permette 60 al minuto e 2 in parallelo. Superare uno di questi limiti fa sì che l’API restituisca HTTP 429. Il codice di errore indica quale limite hai raggiunto: rate_limited per le richieste al minuto, concurrency per troppe richieste in parallelo. Durante un sovraccarico temporaneo l’API invia anche 429 con un’intestazione Retry-After: 5.
Tutti e tre i casi hanno la stessa cura: attendi, poi riprova. Questo wrapper rispetta l’intestazione e fa backoff quando è assente.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import time
from openai import RateLimitError, APIConnectionError, APIStatusError
def call_with_retry(messages, tries=5, **kwargs):
delay = 2
for attempt in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, **kwargs
)
except RateLimitError as err:
wait = err.response.headers.get("Retry-After")
time.sleep(int(wait) if wait else delay)
delay = min(delay * 2, 30)
except APIConnectionError:
time.sleep(delay)
delay = min(delay * 2, 30)
except APIStatusError as err:
if err.status_code < 500:
raise
time.sleep(delay)
delay = min(delay * 2, 30)
raise RuntimeError("request failed after retries")
Riprova solo gli errori che possono cambiare. Un 400 significa che la tua richiesta è malformata e inviarla di nuovo fallirà nello stesso modo, quindi il wrapper rilancia qualsiasi errore client diverso da 429. Le richieste fallite o rifiutate non vengono addebitate, quindi riprovare non costa nulla in più.
Esegui molti input in parallelo
Per un ciclo su molti input, un pool di thread è sufficiente. Il client SDK è sicuro da condividere tra i thread. Dimensiona il pool in base alla tua chiave: 8 worker per una chiave completa, 2 per la chiave di prova.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import time
from concurrent.futures import ThreadPoolExecutor
from openai import RateLimitError
def summarize(text: str) -> str:
for _ in range(5):
try:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Summarize the text in two sentences."},
{"role": "user", "content": text},
],
max_tokens=150,
)
return resp.choices[0].message.content.strip()
except RateLimitError as err:
time.sleep(int(err.response.headers.get("Retry-After", "5")))
return ""
documents = ["First long text...", "Second long text...", "Third long text..."]
with ThreadPoolExecutor(max_workers=8) as pool:
summaries = list(pool.map(summarize, documents))
for s in summaries:
print(s)
La dimensione del pool non è uguale al tasso di richieste. Otto worker che completano ciascuno una chiamata in mezzo secondo genererebbero 960 richieste al minuto, ben oltre 300. Se le tue chiamate sono veloci, aggiungi una piccola pausa o un limitatore a secchio di token per restare sotto il limite al minuto. Se le tue chiamate sono lente, la concorrenza è il limite che incontrerai per primo. Le richieste in streaming mantengono la loro posizione fino al termine dello streaming.
Output strutturato e chiamate di strumenti
Due funzionalità trasformano una chiamata chat in un passaggio di flusso su cui altro codice può fare affidamento. La modalità JSON garantisce output analizzabile. La chiamata di funzioni permette al modello di chiedere al tuo codice di fare qualcosa e poi usare la risposta.
Modalità JSON
Imposta response_format a un oggetto JSON e descrivi le chiavi nel prompt.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with JSON: {\"title\": string, \"tags\": [string]}"},
{"role": "user", "content": "A short post about nightly backups."},
],
)
post = json.loads(resp.choices[0].message.content)
print(post["title"], post["tags"])
Chiamata di funzioni
Dichiara gli strumenti con tools, forza opzionalmente una scelta con tool_choice, esegui la funzione tu stesso e invia il risultato indietro come messaggio con role: "tool".
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import json
tools = [{
"type": "function",
"function": {
"name": "word_count",
"description": "Count the words in a piece of text.",
"parameters": {
"type": "object",
"properties": {"text": {"type": "string"}},
"required": ["text"],
},
},
}]
messages = [{"role": "user", "content": "How many words are in 'the quick brown fox'?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = {"words": len(args["text"].split())}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)
Controlla sempre che tool_calls sia presente prima di leggerlo. Il modello può rispondere direttamente, e il tuo codice dovrebbe gestire entrambi gli esiti.
Collega i passaggi in una pipeline
I flussi reali raramente si fermano a una chiamata. Una forma comune è bozza, revisione, riscrittura: la prima chiamata produce qualcosa, la seconda la critica contro un checklist, e la terza applica la critica. Ogni passaggio è una richiesta separata con il suo messaggio di sistema, il che mantiene le istruzioni brevi e i fallimenti facili da localizzare.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
def step(system: str, user: str, temperature: float = 0.7) -> str:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user},
],
temperature=temperature,
max_tokens=800,
)
return resp.choices[0].message.content.strip()
topic = "a changelog entry for a new export feature"
draft = step("Write the requested text in under 120 words.", topic)
review = step(
"List at most three concrete problems with this text: vague wording, missing detail, wrong tone.",
draft,
temperature=0.2,
)
final = step(
"Rewrite the text so it fixes every listed problem. Reply with the text only.",
"TEXT:\n" + draft + "\n\nPROBLEMS:\n" + review,
)
print(final)
Nota la temperatura più bassa nel passaggio di revisione. La critica dovrebbe essere consistente da esecuzione a esecuzione, mentre la stesura beneficia di una certa varietà. Se esegui la pipeline su molti input, metti l'intera funzione a tre passaggi dentro il worker del thread-pool della sezione precedente, in modo che ogni worker possieda un elemento dall'inizio alla fine e il tetto di 8 richieste sia rispettato.
Mantieni i risultati intermedi. Quando il testo finale è sbagliato, la bozza e la revisione ti dicono quale passaggio è fallito, e puoi correggere un messaggio di sistema invece di riscrivere l'intera pipeline. Scrivere ogni passaggio a un file JSON-lines con l'input, i tre output e gli ID delle richieste rende questo facile, e ti dà un punto di ripresa se il processo si ferma a metà.
Monitora il saldo e gli ID delle richieste
Ogni risposta trasporta intestazioni che vale la pena loggare: X-Request-Id identifica la chiamata se contatti il supporto, X-Balance-USD mostra cosa resta del tuo credito, e i due X-RateLimit-Limit intestazioni riportano i limiti di richiesta e concorrenza per la tua chiave. L'SDK nasconde le intestazioni di default; usa il wrapper raw-response per leggerle.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the single word ready."}],
max_tokens=10,
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance usd:", raw.headers.get("X-Balance-USD"))
print("req limit:", raw.headers.get("X-RateLimit-Limit-Requests"))
print("concurrency limit:", raw.headers.get("X-RateLimit-Limit-Concurrency"))
resp = raw.parse()
print(resp.choices[0].message.content)
I prezzi sono $0.15 per milione di token di input e $0.50 per milione di token di output, quindi una chiamata con 1.000 input e 500 token di output costa $0.00015 + $0.00025 = $0.0004. Un flusso che esegue 5.000 di queste chiamate spende $2.00. Stampa il saldo all'inizio e alla fine di un'esecuzione, e saprai quanto costa ogni batch senza alcun tooling extra. Per i tassi e i bonus di ricarica, vedi la pagina dei prezzi; per ogni parametro supportato, leggi la documentazione API.
Un'altra abitudine valida da adottare: mantieni i prompt fuori dai tuoi log a meno che non ne hai bisogno. I prompt inviati a questa API non sono usati per l'addestramento, ma i tuoi file di log sono tua responsabilità.
Risoluzione dei problemi di una nuova configurazione
La maggior parte dei problemi della prima esecuzione deriva da un breve elenco di cause.
- La chiamata si blocca o genera errori di connessione. Controlla l'URL di base. Deve terminare con
/v1, e l'SDK aggiunge/chat/completionsda solo. Un percorso duplicato è l'errore più comune. - Un errore di autenticazione. La chiave è mancante, troncata o ha uno spazio o un carattere residuo da un copia e incolla. Stampa la sua lunghezza, non la chiave stessa, e confrontala con quello che mostra la pagina della chiave.
- Modello non trovato. L'ID modello è
uncensored, in minuscolo. Chiama l'endpoint models per vedere esattamente cosa può usare la tua chiave. - 429 costante su uno script piccolo. Potresti essere sulla chiave di prova, che consente 2 richieste in parallelo e 60 al minuto. Riduci il pool a 2 worker, o ricarica per ottenere una chiave completa.
- Risposte troncate. Un
max_tokensbasso termina la risposta in anticipo. Aumentalo, o rimuovilo e lascia che il completamento usi il resto della finestra. - Richiesta troppo grande. Il limite del corpo è 8 MB, e la finestra dei token è di 100.000 token per prompt e completamento insieme. Dividi gli input grandi in pezzi e processali come chiamate separate.
Quando qualcosa sembra sbagliato dal lato del servizio, invia il valore da X-Request-Id al contatto sul sito. Un ID di richiesta permette all'operatore di trovare la tua chiamata esatta, che è molto più utile di una descrizione di quello che hai visto.
Altre guide
Domande e risposte
Ho bisogno di un SDK speciale?
No. L'SDK Python ufficiale di OpenAI funziona una volta impostato l'URL di base e la tua chiave.
Quale ID modello devo usare?
Usa uncensored. Puoi elencare gli ID disponibili con GET /v1/models.
Quante richieste possono essere eseguite in parallelo?
Una chiave completa permette 8 richieste concorrenti e 300 al minuto. Una chiave di prova ne permette 2 e 60.
Lo streaming funziona nell'SDK Python?
Sì. Passa stream=True e itera sui chunk. L'utilizzo viene riportato alla fine dello streaming.
La tua chiave è a un modulo web di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.