Come testare una chiave API AI con curl e Python

Ecco come testare l'accesso con la chiave API senza scrivere codice: tre chiamate, circa due minuti, e saprai se la chiave è valida, con credito e autorizzata a generare testo.
Punti chiave
- Chiama GET /v1/models per primo: dimostra che la chiave è accettata senza spendere credito.
- Invia una breve richiesta di chat al modello uncensored per confermare che la generazione funzioni.
- Leggi l'intestazione X-Balance-USD o GET /v1/balance per vedere quanto rimane.
- 401 indica la chiave, 402 il saldo, 429 il limite di richieste.
Il test in tre chiamate
Per testare correttamente una chiave API AI devi verificare tre cose distinte: il server accetta la chiave, la chiave ha un credito associato e viene restituito un completamento effettivo. Una chiamata per domanda mantiene la diagnosi semplice. Se qualcosa fallisce, sai quale strato è responsabile.
- Elenco modelli. Autentica la chiave e non costa nulla.
- Completamento chat. Conferma che il modello risponde e che il formato della tua richiesta è corretto.
- Saldo. Conferma quanto rimane dopo il test.
Tutto quanto segue usa l'URL di base https://api.aiapisource.com/v1 e l'ID del modello uncensored. Inserisci la tua chiave in una variabile d'ambiente così non finirà mai nella cronologia della shell o in un repository.
export AIAPI_KEY="paste-your-key-here"
Se non hai ancora una chiave, la pagina della chiave API mostra come crearne una. I nuovi account possono richiedere un credito di prova da $0,50 con un clic, più che sufficiente per ogni test in questo articolo.
Fase 1: elenca i modelli con curl
Il controllo più economico è una richiesta in sola lettura. GET /v1/models restituisce l'elenco dei modelli e richiede una chiave valida, quindi una risposta di successo prova l'autenticazione.
curl -s https://api.aiapisource.com/v1/models \
-H "Authorization: Bearer $AIAPI_KEY"
Una risposta sana è JSON con un array data che include uncensored. Se vedi una pagina HTML, un errore di connessione o una risposta vuota, il problema è l'URL, non la chiave. Verifica di aver mantenuto il suffisso /v1 e che non ci sia spazio finale dopo la chiave nella tua variabile.
Aggiungi -i al comando curl per vedere le intestazioni di risposta. L'API invia X-Request-Id su ogni chiamata. Tieni quel valore se contatti mai l'assistenza, perché identifica la richiesta esatta.
Fase 2: invia una richiesta di chat
Ora verifica la generazione. Mantieni il prompt minuscolo e limita l'output così il test costa una frazione di centesimo.
curl -s https://api.aiapisource.com/v1/chat/completions \
-H "Authorization: Bearer $AIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Reply with the single word: ready"}],
"max_tokens": 10
}'
Cerca choices[0].message.content e un oggetto usage con prompt_tokens e completion_tokens. Una richiesta di circa 20 token di input e 5 token di output costa 20 / 1.000.000 x $0,15 più 5 / 1.000.000 x $0,50, che è circa $0,0000055. Potresti eseguire un centinaio di queste per ben meno di un centesimo.
Lo stesso endpoint funziona anche per lo streaming: aggiungi "stream": true e i token arrivano come eventi server-sent. Testalo separatamente una volta che la chiamata di base funziona.
Fase 3: la stessa prova in Python
Se il tuo codice reale usa un SDK OpenAI, testa anche tramite l'SDK. Cattura problemi che curl non vede, come un URL di base passato all'argomento sbagliato.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AIAPI_KEY"],
base_url="https://api.aiapisource.com/v1",
)
print([m.id for m in client.models.list().data])
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the single word: ready"}],
max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)
La prima stampa dovrebbe mostrare un elenco contenente uncensored. La seconda mostra la risposta del modello. Per una guida più dettagliata sulla configurazione dell'SDK, consulta la guida Python API OpenAI su questo sito.
Esegui la versione Python dalla stessa shell in cui hai esportato la chiave. Se genera un KeyError su AIAPI_KEY, la variabile non è impostata in quella sessione, che è la ragione più comune per cui un test fallisce prima ancora di raggiungere la rete.
Node funziona allo stesso modo: passa baseURL: "https://api.aiapisource.com/v1" e la chiave al costruttore del client OpenAI.
Verifica il saldo
Una chiave può essere valida e comunque non avere nulla da spendere. Due modi per leggere il saldo:
curl -s https://api.aiapisource.com/v1/balance \
-H "Authorization: Bearer $AIAPI_KEY"
# OpenAI-style alternative
curl -s https://api.aiapisource.com/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer $AIAPI_KEY"
Ogni risposta trasporta anche un'intestazione X-Balance-USD, quindi la chiamata chat della fase 2 ti ha già detto il credito rimanente se l'hai eseguita con -i. In Python, l'SDK OpenAI espone questo tramite client.chat.completions.with_raw_response.create(...), dove leggi response.headers["X-Balance-USD"].
Le richieste fallite o rifiutate non vengono addebitate, quindi un test che genera un errore non consuma credito. Il credito prepagato non scade, il che significa che un saldo inutilizzato ci sarà ancora la prossima settimana.
Lettura dei codici di errore
Quando un test fallisce, lo stato HTTP restringe rapidamente la causa.
| Codice | Significato comune | Cosa fare |
|---|---|---|
| 401 | La chiave è mancante, digitata male o revocata | Controlla l'intestazione Authorization: Bearer, copia di nuovo la chiave, cerca spazi nascosti o virgolette |
| 402 | Nessun credito rimasto per pagare la richiesta | Leggi il saldo, poi ricarica sulla pagina dei prezzi |
| 404 | Percorso errato o ID modello errato | Usa /v1/chat/completions e il modello uncensored |
| 429 | Limite di frequenza o concorrenza, o sovraccarico breve | Attendi e riprova; vedi sotto |
Un 429 trasporta un codice di errore. rate_limited significa troppe richieste al minuto e concurrency significa troppe contemporaneamente. Una chiave completa permette 300 richieste al minuto e 8 richieste concorrenti; una chiave di prova ne permette 60 al minuto e 2 alla volta. In caso di sovraccarico temporaneo l'API risponde con 429 e Retry-After: 5, quindi aspetta cinque secondi e invia di nuovo la richiesta. Una richiesta in streaming mantiene la sua slot di concorrenza fino al termine dello stream, che è una ragione comune per cui una chiave di prova raggiunge il limite durante test paralleli.
I codici di stato 401, 402 e 404 seguono le convenzioni API normali, quindi tratta la tabella come un primo indizio e leggi il corpo dell'errore JSON per il messaggio esatto.
Script di smoke-test riutilizzabile
Una volta superato il test manuale, mantieni uno script che puoi eseguire dopo la rotazione delle chiavi o il cambiamento degli ambienti.
import os, sys
import requests
BASE = "https://api.aiapisource.com/v1"
H = {"Authorization": "Bearer " + os.environ["AIAPI_KEY"]}
m = requests.get(BASE + "/models", headers=H, timeout=15)
print("models", m.status_code)
c = requests.post(
BASE + "/chat/completions",
headers=H,
json={"model": "uncensored",
"messages": [{"role": "user", "content": "ping"}],
"max_tokens": 5},
timeout=60,
)
print("chat", c.status_code, "balance", c.headers.get("X-Balance-USD"))
sys.exit(0 if m.ok and c.ok else 1)
Il codice di uscita rende facile integrarlo in un controllo di deploy. Per parametri oltre questo minimo, la documentazione API elenca tutto ciò che l'endpoint accetta.
Altre guide
Domande e risposte
I test di una chiave API richiedono soldi?
L'elenco dei modelli è gratuito da chiamare. Una breve richiesta di chat con un max_tokens basso costa pochi milionesimi di dollaro a $0,15 per 1M token di input e $0,50 per 1M token di output. Le richieste fallite non vengono addebitate.
Come testo una chiave senza carta?
Richiedi il credito di prova da $0,50 nella pagina della chiave API dopo esserti registrato. Non serve la carta ed è valido per 7 giorni, uno per persona.
Perché una chiave valida restituisce subito 429?
Probabilmente hai raggiunto un limite di concorrenza o per minuto. Le chiavi di prova consentono 2 richieste concorrenti e 60 al minuto; le chiavi complete ne consentono 8 e 300. Controlla il codice di errore, poi riduci il ritmo o riprova dopo qualche secondo.
Posso testare la chiave in Postman o in un'app invece che con curl?
Sì. Funziona qualsiasi client compatibile con OpenAI: imposta l'URL di base su https://api.aiapisource.com/v1, incolla la chiave come token Bearer e usa il modello uncensored.
Ti manca solo un modulo per ottenere la tua chiave
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.