OpenAI API key: come crearla e configurarla

1. Accedi e scegli il progetto giusto

Apri platform.openai.com e crea un account oppure accedi. Completa i passaggi di configurazione iniziale che ti vengono proposti. La guida introduttiva di OpenAI contiene un collegamento diretto alla pagina delle chiavi API.

Immagina l’account come il tuo badge aziendale, l’organizzazione come l’azienda e il progetto come una stanza riservata a una singola applicazione. La chiave è la credenziale con cui il software entra in quella stanza.

Scegli l’organizzazione corretta dal selettore delle organizzazioni. Seleziona un progetto esistente oppure, se sei proprietario dell’organizzazione, usa Create project nel menu dei progetti e compila i dati richiesti. Un nome come website-test rende più chiaro lo scopo del progetto. La guida di OpenAI ai progetti descrive questi comandi.

Se lavori per un’azienda, chiedi al proprietario di aggiungerti al progetto appropriato. Evita di avviare un’integrazione per un cliente usando un account con fatturazione personale solo perché hai già effettuato l’accesso.

2. Crea l’OpenAI API key del progetto

Nelle impostazioni dell’organizzazione, seleziona il progetto, apri API Keys e scegli + Create new secret key. La chiave creata sarà associata al progetto selezionato. Istruzioni per le chiavi di progetto.

Per il tuo primo test, usa una chiave di progetto associata al tuo utente. Se richiesto, assegnale un nome riconoscibile, per esempio local-test. Scegli i permessi Restricted e abilita le operazioni necessarie all’app. All, l’impostazione predefinita, concede l’accesso completo; Read Only limita la chiave alle operazioni di lettura. Permessi delle chiavi API. Per eseguire il test più avanti, autorizza la creazione di Responses con il permesso che OpenAI chiama api.responses.write. Permesso di creazione delle risposte.

Copia subito la chiave e conservala in un luogo sicuro. OpenAI ne mostra il valore completo solo al momento della creazione. Se lo perdi, devi creare una nuova chiave: non puoi visualizzare di nuovo quella originale. Dove trovare e come gestire le chiavi API.

Imposta una data di scadenza e annota chi dovrà sostituire la chiave. Le regole dell’organizzazione potrebbero imporre una scadenza o limitare i tipi di chiave che puoi creare. Se un’opzione non è disponibile, chiedi all’amministratore quali regole sono in vigore. Indicazioni di OpenAI per l’uso in produzione. Consulta il piano di scadenza e rotazione delle chiavi API prima che un test diventi un servizio operativo.

Quando conviene usare la chiave di un account di servizio

Per un’app distribuita o un flusso di lavoro pianificato del team, userei un account di servizio: un’identità assegnata al software anziché a una persona. Il proprietario dell’organizzazione o del progetto può crearlo nel progetto selezionato, da Members → + Service account. Salva subito la chiave generata. Usa un progetto dedicato: gli account di servizio non possono essere aggiunti direttamente al progetto Default. Configurazione degli account di servizio.

Dopo la creazione, controlla i permessi nella sezione API Keys del progetto. La finestra di creazione degli account di servizio non offre gli stessi controlli sui permessi disponibili per una chiave associata a un utente. Differenze nei permessi. Il vantaggio operativo è avere un responsabile chiaro della credenziale dell’applicazione anche quando cambiano i membri del team.

3. Configura la fatturazione delle API e il limite di spesa

La fatturazione di ChatGPT e quella delle API sono separate. Pagare un abbonamento a ChatGPT non completa la configurazione dei pagamenti per le API. Apri il riepilogo della fatturazione API dell’organizzazione corretta; la fatturazione può essere gestita da un proprietario dell’organizzazione. Guida di OpenAI alla fatturazione.

I nuovi account API usano la fatturazione prepagata. Seleziona Add payment details, configura il pagamento, scegli l’importo del primo acquisto di crediti e conferma. Prima di completare l’acquisto, controlla Use auto-reload: secondo OpenAI, la ricarica automatica è attiva per impostazione predefinita. Disattivala se vuoi fare una prova con ricariche manuali, oppure configura consapevolmente la soglia e il limite mensile delle ricariche. L’accredito di un acquisto può richiedere qualche minuto. Configurazione della fatturazione prepagata.

Per le tariffe aggiornate dei modelli, consulta la pagina dei prezzi di OpenAI. La guida ai prezzi delle API OpenAI di questo sito aiuta a inquadrarle nel budget di un’app.

Attiva il blocco se vuoi fermare le richieste al raggiungimento del limite

In Project settings → Limits → Spend → Edit spend limit, inserisci il Monthly spend limit, abilita Enforce a hard limit e salva. Devi avere il permesso di gestire le impostazioni del progetto. Aggiungi un avviso di spesa con una soglia inferiore al limite, così qualcuno potrà intervenire prima che il servizio si fermi. Istruzioni sui limiti di spesa.

Il blocco legato al limite rigido interviene con un ritardo, quindi la spesa registrata può superare leggermente l’importo configurato. Un limite rigido dell’organizzazione copre l’insieme dei suoi progetti. Anche il saldo prepagato può essere superato durante il ritardo nell’interruzione del servizio; inoltre, gli acquisti manuali non rientrano nel limite delle ricariche automatiche. Funzionamento dei limiti rigidi, funzionamento del prepagato.

Prima di passare alla produzione, leggi la guida ai limiti rigidi di spesa delle API OpenAI e stabilisci chi può aumentare il limite quando questo interrompe il servizio.

4. Conserva la chiave in modo che l’app possa usarla in sicurezza

Conserva la chiave in un gestore di segreti, un sistema pensato per custodire credenziali, oppure forniscila al server tramite una variabile d’ambiente chiamata OPENAI_API_KEY. Una variabile d’ambiente è un’impostazione con un nome che il programma in esecuzione può leggere senza inserire il segreto nel codice sorgente. Indicazioni per conservare le credenziali in produzione.

Non inserire una normale chiave API segreta nel JavaScript di un sito, in un’app mobile, in un repository, in uno screenshot o in un messaggio all’assistenza. Il codice per browser e dispositivi mobili arriva sui dispositivi degli utenti: è il server che deve custodire il segreto e inviare la richiesta. Assegna a ogni collega un accesso personale, invece di far circolare la chiave di una sola persona. Sicurezza delle chiavi API.

Se uno strumento ti chiede di incollare una chiave: usa il campo per le credenziali indicato nella documentazione solo se ritieni accettabile affidare quella credenziale al fornitore. Consiglio di creare un progetto dedicato e una chiave con permessi limitati per quell’integrazione, assegnando un responsabile e un tetto di spesa. Un normale campo di testo, un messaggio in chat o un servizio sconosciuto di «verifica delle chiavi» non sono il posto giusto per diagnosticare un problema di connessione. Chiedi al fornitore quali permessi servono e dove conserva il segreto.

5. Esegui una richiesta di prova con curl

Esegui questo comando in Bash sul tuo computer. curl è uno strumento da riga di comando che invia richieste web. Le prime righe chiedono la chiave senza mostrarla sullo schermo né inserirne il valore nel comando digitato; la variabile d’ambiente rimane disponibile per la durata di quella sessione della shell.

read -r -s -p "OpenAI API key: " OPENAI_API_KEY
printf '\n'
export OPENAI_API_KEY

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Reply with a short greeting."
  }'

Il comando usa la struttura della richiesta e il modello dell’esempio di generazione del testo di OpenAI. La Responses API è l’endpoint che riceve l’input e restituisce l’output del modello. L’header di autorizzazione contiene il segreto; il corpo JSON seleziona il modello e fornisce l’istruzione. La richiesta comporta l’utilizzo delle API, quindi la fatturazione e l’accesso al modello devono essere già configurati.

Una risposta riuscita contiene un array output con un messaggio che include contenuti di tipo output_text. Cerca lì il saluto. Non dare per scontato che il testo sia sempre nel primo elemento dell’array. Se ricevi un oggetto error, usa il messaggio e il codice per individuare il problema nella sezione seguente. Struttura della risposta.

Dopo il test, esegui unset OPENAI_API_KEY per eliminare la variabile da questa shell quando non ti serve più. Per distribuire l’app, configura il segreto nell’ambiente di hosting, anziché ripetere la richiesta interattiva nel terminale.

La chiave non funziona? Parti da questi controlli

Leggi l’errore prima di creare un’altra chiave. Diversi problemi non dipendono affatto dalla chiave segreta.

Una risposta 429 può indicare un problema di spesa o di credito, oltre a un limite di frequenza. Ripetere i tentativi non ricarica i crediti e non modifica il tetto configurato. Codici di errore di OpenAI, permessi delle chiavi.

Se la chiave API viene esposta, revocala subito

Considera compromessa una chiave segreta incollata in un repository pubblico, in uno screenshot o in un messaggio. Eliminare la copia visibile non invalida quelle che qualcuno potrebbe aver già ottenuto.

1. Revoca la chiave esposta. Apri la pagina delle chiavi API nel progetto corretto ed eliminala. Le applicazioni che la usano potrebbero smettere di funzionare finché non la sostituisci. Eliminazione delle chiavi.
2. Crea una nuova chiave e aggiorna le app interessate. Verifica che la nuova chiave funzioni, poi controlla che i processi distribuiti la stiano usando.
3. Controlla utilizzo e fatturazione. Indaga sulle richieste inattese e contatta l’assistenza OpenAI in caso di sospetto uso improprio. OpenAI consiglia di sostituire immediatamente la chiave se si sospetta un’esposizione. Indicazioni per gestire una chiave esposta.
4. Risolvi la causa dell’esposizione. Rimuovi il segreto dal codice e dai log e correggi il modo in cui è stato conservato o condiviso. Se anche l’account potrebbe essere compromesso, cambia la password, disconnetti le altre sessioni e segnala le attività non autorizzate. Procedura di recupero dell’account.

Cinque situazioni in cui questa configurazione è utile

Il vantaggio è avere un’integrazione con un responsabile e un budget definiti. Ecco alcuni modi concreti in cui un team potrebbe applicare questa configurazione, ordinati per utilità immediata.

Una chiave funzionante dimostra che una richiesta può essere eseguita. Non dimostra che i prompt siano affidabili, che un fornitore gestisca bene le credenziali o che sia opportuno dare a un’automazione accesso ai dati dei clienti. Queste restano decisioni di prodotto e di gestione operativa.

Due strumenti utili da costruire attorno alla configurazione

L’opportunità più promettente è un assistente di connessione integrato nei software che chiedono ai clienti una chiave OpenAI. DataForSEO stima 1,000 ricerche mensili negli Stati Uniti per “how to get openai api key.” È un segnale delle difficoltà di configurazione, non una previsione di clienti paganti. Un fornitore di software potrebbe acquistare o sviluppare una checklist guidata per il progetto, un campo sicuro per le credenziali, un pulsante di test ben identificabile e un risultato comprensibile. La versione minima dovrebbe essere integrata nel prodotto che richiede la connessione. Il limite è che i fornitori possono svilupparla da soli: il valore deve quindi derivare dalla riduzione del carico sull’assistenza e da istruzioni sempre aggiornate.

Uno strumento che spiega gli errori è una funzione utile per l’assistenza, ma ha una domanda più debole come prodotto autonomo. La stessa verifica stima appena 10 ricerche mensili negli Stati Uniti per “openai api key not working.” Un fornitore di automazioni o un’agenzia che realizza integrazioni potrebbe proporre un modulo in cui inserire il codice e il messaggio di errore, privati dei dati sensibili, per capire se intervenire su credenziali, credito, permessi o frequenza delle richieste. Per la prima versione serve una tabella decisionale aggiornata, senza dover custodire la chiave dell’utente. I limiti sono il basso volume di ricerca misurato e il fatto che molti strumenti mostrano già questi errori. Lo integrerei nella configurazione iniziale, anziché lanciarlo come prodotto a pagamento separato.

Queste sono stime di DataForSEO ottenute dalla panoramica delle parole chiave per le ricerche in inglese negli Stati Uniti, verificate per questa guida. Misurano le ricerche, non gli utenti unici né l’intenzione di acquisto.

Da fare lunedì: scegli un’integrazione, assegna un responsabile, crea il progetto, configura il controllo della spesa e salva il risultato di un test riuscito dopo aver rimosso la chiave segreta. È una consegna utile a chi dovrà occuparsene in seguito.

Se cerchi aiuto per portare l’integrazione in produzione, la pagina sui sistemi di IA in produzione illustra il lavoro operativo necessario.