Come integrare l'API di OpenAI nella tua app

Per integrare l'API di OpenAI, crea una chiave API in un progetto OpenAI, conservala come segreto lato server chiamato OPENAI_API_KEY e chiama l'API da una route del tuo server usando l'SDK ufficiale di OpenAI, mai dal codice del browser. A settembre 2026, la guida rapida di OpenAI presenta la Responses API come punto di partenza per i nuovi progetti. Imposta un limite di spesa prima del lancio, limita la lunghezza delle risposte, stabilisci quante volte ogni utente può usare la funzione e gestisci gli errori di limite di frequenza con nuovi tentativi.

Questa guida copre la configurazione, il flusso delle richieste, i prompt per un builder AI e gli errori che espongono le chiavi o bruciano denaro. I dettagli su OpenAI sono tratti dalla sua documentazione ufficiale aggiornata a settembre 2026. Per i concetti generali (token, finestre di contesto, prezzi), leggi prima come usare le API LLM.

Cosa puoi costruire

• Un assistente chat dentro la tua app (come creare un'app chatbot AI)
• Pulsanti "Riassumi questo", "riscrivi questo" o "bozza di risposta"
• Estrazione di dati strutturati da testo libero: trasformare un'email in un ordine, etichettare i ticket di supporto
• Ricerca e risposte a domande sui tuoi contenuti
• Generazione di immagini, voce e altre funzioni multimediali, a seconda dei modelli disponibili

Altre idee sono in come aggiungere funzioni AI alla tua app.

Configurare il tuo account OpenAI

1. Crea un account e un progetto nella piattaforma OpenAI. Le best practice per la produzione di OpenAI consigliano progetti separati per staging e produzione, così ciascuno può avere le proprie chiavi e i propri limiti.
2. Crea una chiave API di progetto. OpenAI consiglia di impostare una data di scadenza e di ruotare le chiavi regolarmente.
3. Imposta avvisi di spesa e un limite di spesa rigido nella pagina dei limiti. La guida di OpenAI spiega che gli avvisi ti segnalano quando l'utilizzo supera un importo, mentre un limite rigido applica un tetto mensile.
4. Aggiungi un metodo di pagamento. La documentazione sui limiti di frequenza di OpenAI descrive i livelli di utilizzo: i tuoi limiti salgono automaticamente man mano che spendi nel tempo.

Il flusso delle richieste

Browser  ->  route del tuo server  ->  API di OpenAI
         <-  risposta (in streaming) <-

1. L'utente clicca un pulsante o invia un messaggio.
2. Il browser chiama la tua route, per esempio POST /api/summarise.
3. Il tuo server verifica che l'utente abbia effettuato l'accesso e possa usare la funzione.
4. Il server costruisce la richiesta: istruzioni, input dell'utente e i dati del tuo database necessari al compito.
5. Chiama OpenAI con la chiave presa dall'ambiente. Gli SDK di OpenAI leggono automaticamente OPENAI_API_KEY.
6. Trasmette o restituisce la risposta e registra l'uso dei token.

I pacchetti SDK ufficiali di OpenAI si chiamano openai sia per JavaScript/TypeScript (npm) sia per Python (pip).

Scegliere un modello

OpenAI offre diversi modelli a prezzi e velocità diversi, e la gamma cambia spesso. Parti da un modello più piccolo ed economico, misura la qualità su esempi reali e passa a uno più potente solo se ne hai bisogno. Tieni il nome del modello in un valore di configurazione o in un segreto, così puoi cambiarlo senza riscrivere il codice. Consulta la pagina dei prezzi di OpenAI per le tariffe attuali.

Opzioni e compromessi

Prompt da dare al tuo builder AI

Una prima funzione:

Aggiungi un pulsante "Riassumi" nella pagina del ticket. Chiama una route del server POST /api/summarise che verifica che l'utente sia loggato, carica il ticket e chiama la Responses API di OpenAI usando l'SDK ufficiale openai e il segreto OPENAI_API_KEY. Leggi il nome del modello dal segreto OPENAI_MODEL. Istruzioni: "Riassumi in 3 punti elenco, poi suggerisci una breve risposta. Non inventare numeri d'ordine." Limita la lunghezza dell'output, trasmetti la risposta alla pagina e non inviare mai la chiave al browser.

Limiti:

Limita ogni utente a 30 richieste AI l'ora, salvate nel database. Registra i token di input e di output di ogni richiesta con l'ID utente e il nome della funzione. Se OpenAI restituisce 429, rispetta l'intestazione Retry-After e riprova con backoff esponenziale e jitter fino a 3 volte; dopo, mostra "L'AI è occupata, riprova tra un minuto." Mostra un errore chiaro per qualsiasi altro problema e mantieni funzionante il resto della pagina.

Gestire errori e limiti

OpenAI misura i limiti di frequenza in più modi, tra cui richieste al minuto e token al minuto, e raggiungi quello che si esaurisce per primo. Quando ne superi uno, l'API restituisce un 429 con un'intestazione Retry-After. La documentazione di OpenAI dice di trattare quel valore come un minimo e di aggiungere un piccolo ritardo casuale, così i client non riprovano tutti insieme.

Prevedi anche:

• Timeout sulle generazioni lunghe. Lo streaming aiuta, così come un limite ragionevole alla lunghezza dell'output.
• Interruzioni del fornitore. La funzione AI deve fallire con garbo senza bloccare la pagina.
• Output errato. Valida l'output strutturato prima di salvarlo e non lasciare che l'output del modello scateni azioni sensibili senza un controllo nel tuo codice.

Errori comuni

• Chiave nel frontend o nel repository. Il codice del browser è pubblico, e una chiave esposta può essere abusata in pochi minuti. Vedi come proteggere le chiavi API.
• Nessun limite di spesa. Un ciclo o un utente abusivo può far lievitare la bolletta in fretta.
• Nessun limite per utente. Il limite del fornitore protegge il tuo portafoglio, non i tuoi altri utenti.
• Fidarsi del prompt per la sicurezza. Gli utenti possono scrivere "ignora le istruzioni precedenti". I permessi vanno nel codice del server.
• Inviare più del necessario. Documenti interi e cronologie lunghe moltiplicano i costi. Invia solo ciò che serve al compito.
• Scrivere fisso il nome del modello. I modelli vengono aggiornati e ritirati; rendilo un'impostazione.
• Inviare dati personali senza pensarci. Leggi le condizioni d'uso dei dati di OpenAI e invia solo ciò che la funzione richiede.

Checklist

• Progetti OpenAI separati (o chiavi separate) per test e produzione
• Chiave salvata come segreto lato server, mai nel codice del browser o nel repository
• Avvisi di spesa e limite di spesa rigido impostati
• Tutte le chiamate passano dal tuo server e verificano i permessi dell'utente
• Lunghezza dell'output limitata; nome del modello configurabile
• Limite di frequenza per utente nella tua app
• Gestione del 429 con Retry-After, backoff e jitter
• Stato di errore chiaro; la pagina funziona anche senza AI
• Uso dei token registrato per funzione
• Testato con input lunghi, vuoti e ostili

Usare l'API di OpenAI in Mythex

Le funzioni AI nelle app che costruisci su Mythex usano la tua chiave OpenAI, addebitata sul tuo account OpenAI e non sui crediti di build di Mythex. Aggiungi OPENAI_API_KEY come segreto del progetto tramite /secrets, le impostazioni del progetto o la scheda dei segreti che l'agente mostra quando serve una chiave, poi descrivi la funzione con un prompt simile a quelli sopra. Dopo aver cambiato i segreti su un'app pubblicata, pubblicala di nuovo perché li recepisca. La ricetta della documentazione Aggiungere funzioni AI con le tue chiavi API contiene un prompt di partenza, e Segreti in chat spiega la scheda dei segreti. Stai confrontando i fornitori? Vedi come integrare l'API di Claude.

Domande