Guida alla chiave API Codex per gli sviluppatori

Comprendere il formato della chiave API

Quando ti registri a un servizio che fornisce una codex api key, ricevi una stringa alfanumerica univoca. Questa chiave funge da credenziale di autenticazione per ogni richiesta inviata al backend. Il formato segue solitamente uno schema standard, come sk-... o prefissi simili, a seconda dell'implementazione del provider. Tuttavia, poiché stai utilizzando un proxy indipendente, il prefisso esatto può variare. Il fattore critico non è il formato stesso, ma assicurarsi che la chiave venga passata correttamente nell'intestazione HTTP Authorization come Bearer <your_key>.

La tua chiave API è associata a un account specifico e a un livello di utilizzo. A differenza di alcuni servizi che generano più chiavi per ambienti diversi (dev vs. prod), la nostra configurazione è semplice: un account, una chiave. Se perdi la tua chiave o sospetti che sia stata compromessa, puoi rigenerarla immediatamente dal tuo dashboard. Questo revoca istantaneamente la vecchia chiave, garantendo che non permanga alcun accesso non autorizzato. Ricorda di aggiornare le variabili di ambiente o i file di configurazione ogni volta che ruoti le chiavi.

Best practice di sicurezza

• Archivia la tua chiave nelle variabili di ambiente, non nel codice sorgente.
• Non commettere l'errore di inserire la tua codex api key nei repository pubblici.
• Usa la funzione di rigenerazione se sospetti una esposizione.

Errore comune: 401 Non autorizzato

Un errore 401 Unauthorized è il problema più comune quando si integra una nuova chiave API. Indica che il server ha rifiutato le tue credenziali di autenticazione. Nel contesto di un claude code proxy o di qualsiasi endpoint compatibile con OpenAI, questo significa quasi sempre che la chiave è mancante, errata o scaduta.

Per risolvere, verifica prima di aver copiato la chiave esattamente come fornita. Le chiavi sono spesso sensibili al maiuscolo/minuscolo e possono contenere spazi se copiate erroneamente. Assicurati di utilizzare l'URL di base corretto per la tua regione o livello di servizio. Se hai rigenerato di recente la tua chiave, assicurati che il tuo client utilizzi il nuovo valore. Un errore 401 non è correlato al tuo saldo di utilizzo o ai limiti di richieste; è puramente un errore di autenticazione.

Checklist per la risoluzione

1. Conferma che la stringa della chiave API corrisponda esattamente al dashboard.
2. Verifica il formato dell'intestazione Authorization: Authorization: Bearer YOUR_KEY.
3. Verifica che l'URL di base sia corretto per il tipo di account.
4. Assicurati che non siano stati aggiunti spazi bianchi durante il copia-incolla.

Limite di richieste superato: errori 429

Quando superi il volume di richieste consentito, l'API restituisce un errore 429 Too Many Requests. Per il nostro servizio, il limite è impostato a 300 richieste al minuto per chiave. Questo limite è applicato per garantire un utilizzo equo e mantenere una bassa latenza per tutti gli utenti. Se stai eseguendo sessioni di programmazione ad alto volume, potresti raggiungere questo limite rapidamente, specialmente se il tuo codice innesca più richieste interne.

Quando si verifica un errore 429, la risposta include solitamente un'intestazione Retry-After che indica quanti secondi devi attendere prima di riprovare. L'implementazione dell'esponential backoff nel codice del client è il modo standard per gestire questi errori in modo elegante. Invece di riprovare immediatamente, attendi un breve periodo, poi raddoppia il tempo di attesa per i tentativi successivi. Questo impedisce alla tua applicazione di inondare il server con richieste mentre il limite si resetta.

È importante notare che i limiti di richieste sono per chiave, non per account. Se hai più dispositivi o processi che utilizzano la stessa chiave, condividono il budget di 300 richieste/minuto. Considera l'utilizzo di chiavi separate per ambienti diversi se hai bisogno di un throughput aggregato superiore.

Configurazione corretta dell'URL di base

L'URL di base è il fondamento di qualsiasi integrazione API. Per un servizio compatibile con OpenAI, l'URL di base determina dove vengono inviate le tue richieste. Il nostro URL di base è https://api.claudecodeapikey.com/v1. Questo URL deve essere configurato nella tua libreria client o SDK prima di effettuare qualsiasi richiesta. Se usi l'URL di base sbagliato, riceverai errori di connessione o risposte impreviste.

Molti sviluppatori utilizzano l'SDK ufficiale OpenAI per Python, Node.js o altri linguaggi. Per passare al nostro proxy, devi semplicemente aggiornare la configurazione dell'URL di base. Ad esempio, in Python, potresti impostare base_url='https://api.claudecodeapikey.com/v1'. Assicurati che il protocollo (https) e il percorso (/v1) siano corretti. Omettere il percorso /v1 è un errore comune che porta a errori 404.

Verifica sempre che il client stia inviando richieste all'endpoint corretto. Puoi farlo controllando i log di rete o utilizzando uno strumento come curl per testare la connessione. Una connessione di successo all'URL di base conferma che la tua configurazione è corretta.

Gestione delle risposte in streaming

Le risposte in streaming ti permettono di ricevere parti della risposta API man mano che vengono generate, invece di attendere il completamento dell'intera risposta. Questo è cruciale per gli agenti di coding che mostrano frammenti di codice in tempo reale. La nostra API supporta lo streaming tramite Server-Sent Events (SSE). Quando abiliti lo streaming nel tuo client, riceverai uno stream di chunk, ciascuno contenente una risposta parziale.

Per abilitare lo streaming, imposta il parametro stream su true nella tua richiesta. La libreria client gestirà quindi automaticamente il protocollo SSE. Puoi elaborare ogni chunk man mano che arriva, aggiornando la tua UI o registrando i progressi. Questo fornisce una migliore esperienza utente, specialmente per le generazioni di codice lunghe.

Lo streaming non cambia il modello sottostante o le sue capacità. È puramente un meccanismo di trasporto. Il modello elabora ancora l'intero prompt e genera la risposta completa; la differenza è nel modo in cui l'output viene consegnato al tuo client.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.claudecodeapikey.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Problemi di configurazione della chiamata di funzioni

La chiamata di funzioni (o function calling) permette al LLM di richiedere azioni specifiche, come l'esecuzione di un frammento di codice o l'interrogazione di un database. La nostra API supporta la chiamata di funzioni, il che significa che puoi definire le funzioni nella tua richiesta e ricevere risposte JSON strutturate dal modello. Questo è essenziale per gli agenti di coding avanzati che devono interagire con sistemi esterni.

Per configurare la chiamata di funzioni, devi fornire un elenco di definizioni di funzioni nel parametro tools. Ogni strumento deve avere un nome, una descrizione e uno schema dei parametri. Il modello deciderà quindi quando chiamare uno strumento in base al prompt. Se il modello decide di chiamare uno strumento, la risposta includerà un array tool_calls con il nome della funzione e gli argomenti.

I problemi comuni derivano da definizioni dello schema JSON errate. Assicurati che i tipi di parametro e i campi obbligatori siano specificati con precisione. Se lo schema non è valido, il modello potrebbe non chiamare correttamente lo strumento. Testa le tue definizioni di strumenti con prompt semplici per verificare che il modello comprenda il comportamento atteso.

Limiti della finestra di contesto

La finestra di contesto definisce la quantità massima di testo che il modello può elaborare in una singola richiesta, inclusi sia il prompt (input) che il completamento (output). Il nostro modello ha una finestra di contesto di 100.000 token. Questa è una quantità significativa di testo, ma non è infinita. Se il tuo prompt più l'output previsto supera questo limite, l'API restituirà un errore.

Per gestire il contesto in modo efficiente, monitora l'utilizzo dei token dei tuoi prompt. File lunghi o cronologie di conversazione estese possono consumare rapidamente i token disponibili. Se ti avvicini al limite, considera il troncamento dei messaggi più vecchi o il riassunto delle interazioni precedenti. Alcuni client gestiscono automaticamente questo scorrendo la finestra, ma è meglio essere consapevoli del limite per evitare errori imprevisti.

Ricorda che la finestra di contesto include tutti i token inviati al modello, inclusi i messaggi di sistema, gli utenti e gli assistenti. Pianifica il tuo budget di token di conseguenza per garantire un funzionamento fluido durante le sessioni di coding lunghe.

Rigenerazione della chiave

Rigenerare la tua chiave API è un processo semplice che garantisce la sicurezza. Se sospetti che la tua chiave sia stata esposta o vuoi ruotare le credenzialiperiodicamente, puoi generare una nuova chiave dal tuo dashboard. La chiave precedente viene immediatamente invalidata, quindi qualsiasi richiesta in corso che utilizza la vecchia chiave fallirà.

Quando rigeneri una chiave, assicurati di aggiornare tutti i tuoi client e le configurazioni con il nuovo valore. Questo include le variabili d'ambiente, i file di configurazione e qualsiasi valore hardcoded nel tuo codice. Il mancato aggiornamento di tutte le posizioni potrebbe causare errori di autenticazione per alcune parti della tua applicazione.

Il nostro servizio consente rigenerazioni illimitate delle chiavi. Non ci sono penalità per ruotare la tua chiave frequentemente. Questa è una buona pratica per mantenere la sicurezza, specialmente in ambienti condivisi o quando si distribuiscono le chiavi ai membri del team.

Copycurl https://api.claudecodeapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'