API OpenAI per sviluppatori: usa un endpoint compatibile

La versione breve

La maggior parte delle guide sull'API OpenAI per gli sviluppatori presuppone un singolo fornitore e una fattura. Il formato di trasmissione, tuttavia, è semplicemente JSON su HTTPS, e molto codice client, framework e strumenti possono comunicare con qualsiasi server che lo implementi. Questo sito ospita uno di questi server. Mantieni il tuo SDK, modifica il base URL, inserisci una chiave da questo sito e imposta il modello su uncensored.

Questo è l'intera migrazione per un'app tipica. Ecco la checklist, e il resto della pagina dettaglia ogni passaggio.

1. Crea un account e richiedi il credito di prova nella pagina chiave API.
2. Imposta la base URL su https://api.openaigatewayapi.com/v1.
3. Invia la chiave come Authorization: Bearer <key>. Gli SDK lo fanno per te quando passi api_key.
4. Usa uncensored come ID modello in ogni richiesta.
5. Gestisci l'HTTP 429 con un breve retry, come mostrato verso la fine.

Esistono due endpoint: POST /v1/chat/completions e GET /v1/models. Il servizio è solo testo. Non c'è generazione di immagini o audio, nessun embedding e nessun fine-tuning, quindi se la tua app chiama quelli, avranno bisogno di un provider diverso.

Verifica la connessione con curl

Prima di toccare la tua applicazione, conferma che la chiave funziona. L'endpoint dei modelli è il test più economico, perché non genera token.

Copyexport API_KEY="paste-your-key-here"

curl https://api.openaigatewayapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY" | grep -o uncensored

Il grep stampa l'ID modello uncensored se l'elenco lo contiene; rimuovi il grep per vedere l'elenco JSON completo. Se ottieni un 401, la chiave è errata o manca il prefisso Bearer. Ora invia una richiesta reale:

Copycurl https://api.openaigatewayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
    "temperature": 0.4
  }'

La risposta contiene gli oggetti choices e usage soliti. Include anche intestazioni degne di essere registrate: X-Request-Id per le domande di supporto, X-Balance-USD per il tuo credito rimanente, e le due intestazioni X-RateLimit-Limit-* che mostrano i limiti di richieste e concorrenza.

Python con il pacchetto openai ufficiale

In Python tocchi solo il costruttore del client. Tutto il resto è il codice che hai già.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short, accurate release notes."},
        {"role": "user", "content": "Summarise: added retry logic, fixed timeout bug."},
    ],
    temperature=0.5,
    max_tokens=200,
)

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

Leggi la chiave da una variabile d'ambiente nel codice reale. Il campione la hardcodifica solo per mantenere lo snippet breve. max_tokens è opzionale qui; se lo lasci fuori, il completamento può usare tutto ciò che rimane della finestra da 100.000 token (prompt più completamento insieme). Impostarlo comunque è un modo economico per limitare il costo su una generazione fuori controllo.

Streaming

Lo streaming utilizza Server-Sent Events e lo stesso flag stream=True che conosci. I numeri di utilizzo arrivano alla fine dello stream, quindi l'ultimo chunk potrebbe avere un elenco choices vuoto.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five edge cases for a date parser."}],
    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("\ntokens:", chunk.usage.total_tokens)

Un dettaglio è importante per la pianificazione della capacità. Una richiesta streaming mantiene la sua slot di concorrenza fino alla fine dello stream, non fino al primo token. Se un client abbandona uno stream senza chiuderlo, quella slot rimane occupata più a lungo del previsto.

Esempio Node.js

L'SDK Node prende le stesse due impostazioni con nomi diversi.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openaigatewayapi.com/v1",
  apiKey: process.env.GATEWAY_KEY,
});

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "user", content: "Write a regex that matches ISO 8601 dates, and explain it." },
  ],
  temperature: 0.3,
});

console.log(completion.choices[0].message.content);

Se usi un framework che ha la sua integrazione OpenAI, cerca un campo chiamato base URL, API base o endpoint nelle sue impostazioni. Incollare lo stesso URL lì è di solito tutto ciò che serve. Chat front end, framework agent e plugin editor seguono principalmente questo pattern. I parametri di campionamento come temperature, top_p, stop, seed e le penalità di frequenza e presenza sono passati al modello.

Chiamata di strumenti e modalità JSON

Due funzionalità decidono se un modello si adatta a un'applicazione reale: chiamare le tue funzioni e restituire dati che puoi analizzare. Entrambi sono supportati.

Chiamata di funzioni

Dichiari gli strumenti con tools, forzi opzionalmente una scelta con tool_choice e invii i risultati indietro come messaggi con role: "tool". Le risposte in streaming consegnano tool_calls in pezzi, come con il formato standard.

Copyimport json
from openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
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]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}  # your real lookup here
    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)

Convalida sempre gli argomenti prima di agire su di essi. Il modello produce JSON che corrisponde al tuo schema la maggior parte del tempo, non ogni volta, quindi tratta call.function.arguments come qualsiasi altro input non attendibile.

Modalità JSON

Per lavori di estrazione e classificazione, chiedi un oggetto JSON e dillo anche nel prompt. Menzionare JSON nelle istruzioni dà risultati migliori che affidarsi solo al flag.

Copyfrom openai import OpenAI
import json

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"sentiment\": string, \"topics\": [string]}."},
        {"role": "user", "content": "The docs are clear but the rate limits caught me off guard."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data)

Limiti, errori e retry

Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. La chiave di prova permette 2 in volo e 60 al minuto. Il corpo massimo della richiesta è 8 MB. Superi un limite e ottieni HTTP 429, e il codice errore ti dice quale limite è stato.

Codice di errore	Significato	Cosa fare
rate_limited	Troppe richieste al minuto	Rallenta il produttore o distribuisci il lavoro nel minuto
concurrency	Troppe richieste contemporaneamente	Abbassa il tuo conteggio dei worker a 8 o meno, o 2 su una chiave di prova
429 con Retry-After: 5	Sovraccarico temporaneo	Attendi i secondi indicati e riprova

Gli SDK già gestiscono il ritentativo di alcuni errori. Aggiungi la tua gestione per il 429 in modo che un burst non crashi un lavoro batch:

Copyimport time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
    max_retries=0,
)

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 2 ** i))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

Le richieste fallite o rifiutate non sono addebitate, quindi un loop di retry non raddoppia il tuo conto. Un semaforo dimensionato al tuo limite di concorrenza è il modo più pulito per rimanere sotto il cap nel codice async.

Spostare un'app esistente

Se hai un'app funzionante, non hardcodare i nuovi valori. Inserisci il base URL, la chiave e il nome del modello nelle variabili d'ambiente così puoi commutare tra gli ambienti senza un deploy. Questo ti permette anche di eseguire la stessa suite di test su due backend e confrontare l'output fianco a fianco.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openaigatewayapi.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def complete(messages, **kw):
    return client.chat.completions.create(model=MODEL, messages=messages, **kw)

Poi lavora attraverso una breve routine di migrazione:

1. Esegui il tuo set di prompt esistente contro il nuovo endpoint e leggi gli output tu stesso. I controlli automatici catturano gli errori di formato, non il tono.
2. Verifica che qualsiasi codice che analizza JSON passi ancora con response_format impostato, e mantieni un fallback che rimuove il testo estraneo intorno all'oggetto.
3. Misura i conteggi token reali da usage, perché un modello diverso tokenizza il testo in modo diverso e le tue stime vecchie potrebbero essere sbagliate.
4. Imposta il tuo pool di worker a 8 o meno in modo che il cap di concorrenza non sia mai la prima cosa a fallire sotto carico.
5. Distribuisci a una piccola fetta di traffico, monitora il tasso di 429 e i log degli errori, poi amplia.

I team spesso dimenticano il prompt di sistema in questo processo. I prompt scritti per indurre un modello propenso al rifiuto a comportarsi di solito contengono frasi di attenuazione che non sono necessarie qui e possono affollare l'output. Rileggi i tuoi e taglia ciò che non fa più nulla.

Cosa sapere prima di cambiare

La compatibilità copre il formato di richiesta e risposta. Non rende questa l'API ufficiale di nessun creatore di modelli. Il servizio esegue un modello a pesi aperti, ospitato da un provider indipendente e ottimizzato per rispondere senza rifiuto dei contenuti per l'uso adulto legale. Non è un router tra fornitori, quindi non troverai un menu di altri modelli dietro di esso. I contenuti sessuali che coinvolgono minorenni non sono consentiti, e quel limite non può essere modificato.

Pianifica intorno a tre differenze pratiche rispetto a una grande piattaforma multi-modello:

• Un solo modello. L'ID è uncensored. Se il tuo codice commuta tra modelli in base al compito, unifica tutto a un solo valore.
• Solo testo. Rimuovi qualsiasi chiamata immagine, audio o embedding dal percorso che va a questo endpoint.
• Il comportamento del prompt varia. Un modello diverso interpreta le istruzioni in modo diverso, quindi riesegui i tuoi prompt e test dopo il cambio. Raffina i prompt di sistema dove l'output devia.

I prompt non vengono utilizzati per l'addestramento. Per l'elenco completo dei parametri consulta la documentazione delle API. Se stai stimando la spesa, la pagina prezzi elenca i costi per token: $0,15 per 1M di input token e $0,50 per 1M di output token, fatturati dal credito prepagato senza abbonamento. I ricaricamenti vanno da $20 a $500 e il credito non scade. Se invece stai valutando uno strato proxy davanti a diversi servizi, la pagina su gateway LLM spiega quando questa parte aggiuntiva conviene.

Altre guide

• OpenAI Gateway API spiegata in termini semplici
• Prezzi OpenAI Gateway API: esempi di costi reali
• LLM Gateway: analisi costi vs. complessità