IT ▾

Alternativa API AI senza censura per sviluppatori

https://api.veniceapialternative.com/v1

veniceapialternative.com

Alternativa API Venice Python: configurazione SDK OpenAI

Puoi usare l'SDK Python ufficiale di OpenAI contro questa API modificando l'URL base, la chiave e il nome del modello. Di seguito trovi codice funzionante per ogni attività comune.

Aggiornato

Striscia di blocchi di codice che scorre da un terminale a un server cloud, illustra la configurazione API Python

Punti chiave

  • Installa il pacchetto openai, imposta base_url su https://api.veniceapialternative.com/v1 e model su uncensored.
  • Streaming, chiamata di funzioni e modalità JSON funzionano tutte tramite le chiamate SDK standard.
  • Mantieni il lavoro parallelo a o sotto 8 richieste concorrenti con una chiave completa (2 con la chiave di prova).
  • Un 429 indica rate_limited, concurrency o sovraccarico temporaneo; riduci il ritmo e riprova.

Installa ed effettua la prima chiamata

Per una configurazione alternativa API Venice Python non hai bisogno di librerie speciali. Il servizio utilizza il formato chat OpenAI, quindi l'SDK standard funziona. Installalo con pip install openai, poi ottieni una chiave. I nuovi utenti possono richiedere $0,50 di credito di prova nella pagina della chiave API dopo essersi registrati con Google o con email e password. Non serve la carta.

Memorizza la chiave in una variabile d'ambiente invece che nel file di origine. Poi crea un client con l'URL base e chiama il modello uncensored:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise writing assistant."},
        {"role": "user", "content": "Give me three opening lines for a noir story."},
    ],
    temperature=0.8,
)

print(resp.choices[0].message.content)
print(resp.usage)

L'SDK invia Authorization: Bearer <key> per te. L'oggetto usage mostra i token prompt e completion, che userai per il tracciamento dei costi in seguito. Se la chiamata fallisce con un errore di autenticazione, controlla che la chiave non abbia una nuova riga finale e che l'URL base termini con /v1.

I parametri temperature, top_p, stop e seed, più le penalità di frequenza e presenza, vengono passati al modello, quindi puoi regolare il campionamento nello stesso modo in cui faresti altrove. Ometti max_tokens se vuoi che il modello utilizzi tutto lo spazio rimasto nella finestra, oppure impostalo quando vuoi un limite rigido alla lunghezza della risposta e al costo.

Verifica la connessione con l'endpoint dei modelli

Prima di costruire qualsiasi cosa, conferma che l'endpoint sia raggiungibile. Il secondo metodo supportato, GET /v1/models, elenca ciò che la chiave può utilizzare:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

for m in client.models.list():
    print(m.id, m.id == "uncensored")

Dovresti vedere uncensored. Quello è l'unico ID modello ed è il valore da passare come model in ogni richiesta. Se stai migrando un'app che selezionava tra diversi nomi di modello, sostituisci la logica di selezione con una costante. Non c'è altro da scegliere.

Il riferimento completo dei parametri è nella pagina della documentazione. È supportata solo la chat testuale: nessuna immagine, audio, embedding o affinamento, quindi rimuovi quelle chiamate da qualsiasi codice che porti.

Risposte in streaming

Lo streaming restituisce i token man mano che vengono prodotti, il che rende le interfacce chat più veloci. Imposta stream=True e itera sui chunk. L'utilizzo arriva alla fine dello streaming, quindi proteggi i chunk che non contengono scelte:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe a rainy harbor town in 120 words."}],
    stream=True,
)

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):
        print("\n", chunk.usage)

Un dettaglio è importante per la pianificazione della capacità: una richiesta in streaming occupa la sua slot di concorrenza fino alla fine dello stream. Se un utente apre uno stream e se ne va senza chiuderlo, quella slot rimane occupata. Chiudi gli stream lato client quando l'utente se ne va e imposta un timeout della richiesta.

Chiamata di funzioni e modalità JSON

La chiamata di funzioni segue la struttura OpenAI. Descrivi le funzioni in tools, il modello restituisce tool_calls, esegui la funzione e invia il risultato indietro con role: "tool":

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_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 the next encounter."}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"value": 14, "sides": args["sides"]}
    messages.append(msg)
    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)

Analizza sempre function.arguments con un try/except nel codice di produzione, poiché un modello può emettere JSON malformato occasionalmente. La modalità JSON aiuta quando vuoi un output strutturato senza strumenti:

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

r = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with a JSON object with keys name, mood and hook."},
        {"role": "user", "content": "Invent a tavern keeper for a fantasy campaign."},
    ],
)
print(json.loads(r.choices[0].message.content))

Indica al modello nel prompt quali chiavi vuoi. La modalità JSON rende l'output JSON valido, ma non può indovinare il tuo schema.

Gestione errori 429 e limiti di velocità

Una chiave completa consente 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova consente 2 richieste concorrenti e 60 al minuto. Superato un limite ottieni HTTP 429 e il codice errore ti dice quale:

  • rate_limited: troppe richieste al minuto. Rallenta.
  • concurrency: troppe richieste in corso. Attendi che alcune terminino.
  • Un 429 con un'intestazione Retry-After: 5: sovraccarico temporaneo. Attendi 5 secondi e riprova.

L'SDK ritenta già alcune volte per impostazione predefinita e rispetta Retry-After. Per carichi più pesanti, aggiungi il tuo wrapper e leggi le intestazioni dei limiti. Puoi accedere alla risposta grezza tramite with_raw_response:

import os
import time
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
    max_retries=0,
)

def ask(prompt, attempts=4):
    for n in range(attempts):
        try:
            raw = client.chat.completions.with_raw_response.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            print("balance:", raw.headers.get("X-Balance-USD"),
                  "request id:", raw.headers.get("X-Request-Id"))
            return raw.parse().choices[0].message.content
        except openai.RateLimitError as e:
            wait = int(e.response.headers.get("Retry-After", 2 ** n))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

print(ask("Name three plot twists for a heist story."))

Registra X-Request-Id con ogni errore. Se contatti il supporto, quell'ID permette loro di trovare la chiamata esatta. L'intestazione X-Balance-USD ti dà il credito rimanente senza una richiesta extra. Le richieste fallite e rifiutate non vengono addebitate.

Esecuzione richieste in parallelo senza superare il limite

Per i job batch, usa il client asincrono e un semaforo dimensionato alla tua chiave. Con una chiave completa, 8 è il limite massimo. Lascia un po' di margine se servi anche utenti live dalla stessa chiave.

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)
gate = asyncio.Semaphore(6)

async def summarize(text):
    async with gate:
        r = await client.chat.completions.create(
            model="uncensored",
            messages=[{"role": "user", "content": "Summarize in one sentence: " + text}],
            max_tokens=80,
        )
        return r.choices[0].message.content

async def main():
    docs = ["First long text ...", "Second long text ...", "Third long text ..."]
    for line in await asyncio.gather(*(summarize(d) for d in docs)):
        print(line)

asyncio.run(main())

Il ritmo conta anche per il limite al minuto. Con 6 worker paralleli e 4 secondi per chiamata, invii circa 90 richieste al minuto, ben sotto 300. Se le tue chiamate sono veloci, aggiungi un piccolo sleep o un token bucket così da non superare il limite a raffiche.

Spostamento di un progetto Python esistente

La maggior parte delle migrazioni è più piccola di quanto le persone si aspettino. Se il tuo codice costruisce già un client OpenAI(...), modifichi due argomenti del costruttore e una stringa. Se leggi le impostazioni dalle variabili d'ambiente, spesso puoi evitare di toccare il codice: il pacchetto openai legge OPENAI_API_KEY e OPENAI_BASE_URL, quindi impostando quelle due nel tuo shell o nel file .env punti l'intero programma verso il nuovo endpoint.

Poi cerca nel progetto questi elementi, perché sono le solite fonti di malfunzionamenti:

  • Nomi di modello hard-coded. Sostituisci ogni vecchio nome con uncensored. Un grep per model= li trova nella maggior parte dei casi.
  • Chiamate ad altri endpoint. Le chiamate per immagini, audio, embedding e fine-tuning non hanno un equivalente qui. Instradale verso un servizio che le offre, o rimuovile.
  • Extra specifici del fornitore. Campi di richiesta extra o intestazioni personalizzate appartenenti al tuo vecchio provider possono causare errori. Rimuovile per ottenere il formato OpenAI standard.
  • Budget token. La finestra è di 100.000 token per prompt più completion. Se hai tagliato la cronologia per adattarla a una finestra più piccola, ora puoi mantenerne di più, ma tieni d'occhio i costi, perché ogni messaggio mantenuto viene pagato di nuovo ad ogni turno.

I prompt meritano una nuova verifica. Un system prompt che funzionava per un modello potrebbe dare un tono diverso su un altro, quindi esegui i tuoi dieci prompt più importanti e confronta l'output con ciò che ti aspetti prima di rilasciare.

Problemi comuni e relative soluzioni

Un breve elenco degli errori che si presentano più spesso quando le persone collegano un nuovo endpoint compatibile con OpenAI da Python:

  • 404 sulla prima chiamata. Manca /v1 dall'URL base, oppure contiene un segmento di percorso extra. Dovrebbe leggere esattamente https://api.veniceapialternative.com/v1.
  • 401 o errore di autenticazione. La chiave è sbagliata, ha ancora le virgolette intorno a essa da una riga .env copiata, oppure non è stata esportata nello shell che esegue Python.
  • La richiesta si blocca con input grandi. Il corpo massimo è 8 MB. Incollare un file enorme in un prompt può superarlo molto prima di raggiungere il limite di token. Dividi il testo.
  • 429 casuali durante i test. Con la chiave di prova hai solo 2 richieste concorrenti. Un runner di test che ne avvia cinque in una volta supererà il limite. Esegui i test in serie, o ricarica e usa una chiave completa.
  • Risposte troncate. Controlla finish_reason. Un valore di length indica che l'output ha raggiunto l'impostazione max_tokens o ha riempito la finestra di contesto.
  • Risultati diversi da esecuzione a esecuzione. Passa seed e un temperature basso se ti serve un output ripetibile per i test.

Se qualcosa sembra ancora errato, invia il valore X-Request-Id al supporto insieme all'orario della chiamata.

Stima dei costi nel codice

Il prezzo è $0,15 per 1M di token di input e $0,50 per 1M di token di output. Un piccolo helper converte qualsiasi blocco di utilizzo in dollari:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veniceapialternative.com/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
)

def cost_usd(usage):
    return (usage.prompt_tokens * 0.15 + usage.completion_tokens * 0.50) / 1_000_000

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a limerick about a lighthouse."}],
)
print(round(cost_usd(r.usage), 6))

Una chiamata con 2.000 token di prompt e 500 token di completamento restituisce 0,00055. Eseguendone 1.000 si spendono $0,55. Il credito di prova di $0,50 copre circa 909 chiamate di questo tipo. Dopo la prova, le ricariche partono da $20 e il credito non scade mai; la pagina dei prezzi elenca i livelli di bonus. Se la tua app proviene da un progetto chatbot con le sue insidie, l'articolo sugli errori comuni nelle API ne copre diversi che si applicano anche qui.

Domande e risposte

Quale pacchetto Python mi serve?

Il pacchetto ufficiale OpenAI. Installalo con pip, imposta base_url su https://api.veniceapialternative.com/v1, e usa il modello uncensored. Non è richiesta un'altra libreria client.

Lo streaming funziona con l'SDK?

Sì. Passa stream=True e itera sui chunk. L'utilizzo viene riportato alla fine dello streaming.

Perché ricevo un errore 429?

Hai superato il limite di richieste al minuto (rate_limited), hai aperto troppe richieste in parallelo (concurrency) oppure il servizio era momentaneamente sovraccarico e ha inviato Retry-After: 5. Riduci il carico e riprova.

Quante richieste parallele posso eseguire?

Una chiave completa permette 8 richieste concorrenti e 300 al minuto. Una chiave di prova ne permette 2 concorrenti e 60 al minuto.

Posso usare LangChain o altri strumenti compatibili con OpenAI?

Qualsiasi client che ti permetta di impostare un URL base e una chiave compatibili con OpenAI dovrebbe funzionare. Usa lo stesso URL base e il nome del modello uncensored.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.

Ottieni la chiave API