Com integrar l’API d’OpenAI a la teva app

Per integrar l’API d’OpenAI, crea una clau d’API en un projecte d’OpenAI, guarda-la com a secret del servidor anomenat OPENAI_API_KEY i crida l’API des d’una ruta del teu propi servidor fent servir el SDK oficial d’OpenAI, mai des de codi del navegador. A partir de setembre de 2026, el quickstart d’OpenAI presenta la Responses API com el punt de partida per a projectes nous. Estableix un límit de despesa abans del llançament, limita la longitud de les respostes, restringeix amb quina freqüència cada usuari pot cridar la funció i gestiona els errors de límit de velocitat amb reintents.

Aquesta guia cobreix la configuració, el flux de peticions, prompts per a un constructor d’IA i els errors que filtren claus o fan malbaratar diners. Els detalls d’OpenAI són de la seva documentació oficial a setembre de 2026. Per als conceptes generals (tokens, finestres de context, preus), llegeix primer com fer servir les APIs de LLM.

Què pots construir amb això

• Un assistent de xat dins de la teva app (com construir una app de xatbot amb IA)
• Botons de «Resumeix això», «reescriu això» o «redacta una resposta»
• Extracció de dades estructurades de text lliure: convertir un correu en una comanda, etiquetar tiquets de suport
• Cerca i respostes a preguntes sobre el teu propi contingut
• Funcions de imatge, àudio i altres de multimèdia, segons els models disponibles

Hi ha més idees a com afegir funcions d’IA a la teva app.

Configurar el teu compte d’OpenAI

1. Crea un compte i un projecte a la plataforma d’OpenAI. Les bones pràctiques de producció d’OpenAI recomanen projectes separats per a staging i producció, perquè cadascun tingui les seves pròpies claus i límits.
2. Crea una clau d’API del projecte. OpenAI recomana establir una data de caducitat i rotar les claus regularment.
3. Configura alertes de despesa i un límit de despesa rígid a la pàgina de límits. La guia d’OpenAI diu que les alertes t’avisen quan l’ús supera un import, i que un límit rígid aplica un topall mensual.
4. Afegeix la facturació. La documentació de límits de velocitat d’OpenAI descriu nivells d’ús: els teus límits pugen automàticament a mesura que gastes més amb el temps.

El flux de la petició

Navegador  ->  la teva ruta del servidor  ->  API d’OpenAI
           <-  resposta (en streaming)     <-

1. L’usuari fa clic en un botó o envia un missatge.
2. El navegador crida la teva ruta, per exemple POST /api/summarise.
3. El teu servidor comprova que l’usuari ha iniciat sessió i pot fer servir la funció.
4. El servidor construeix la petició: instruccions, l’entrada de l’usuari i les dades de la teva base de dades que la tasca necessiti.
5. Crida OpenAI amb la clau de l’entorn. Els SDK d’OpenAI llegeixen OPENAI_API_KEY automàticament.
6. Retorna la resposta, en streaming o completa, i registra l’ús de tokens.

Els paquets SDK oficials d’OpenAI es diuen openai tant per a JavaScript/TypeScript (npm) com per a Python (pip).

Triar un model

OpenAI ofereix diversos models a diferents preus i velocitats, i la gamma canvia sovint. Comença amb un model més petit i més barat, mesura la qualitat amb exemples reals i passa a un de més gran només si cal. Guarda el nom del model en un valor de configuració o en un secret perquè el puguis canviar sense reescriure el codi. Consulta la pàgina de preus d’OpenAI per a les tarifes actuals.

Opcions i compromisos

Prompts per donar al teu constructor d’IA

Una primera funció:

Afegeix un botó «Resumeix» a la pàgina del tiquet. Crida una ruta del servidor POST /api/summarise que comprova que l’usuari ha iniciat sessió, carrega el tiquet i crida la Responses API d’OpenAI amb el SDK oficial openai i el secret OPENAI_API_KEY. Llegeix el nom del model del secret OPENAI_MODEL. Instruccions: «Resumeix en 3 punts i després suggereix una resposta breu. No inventis números de comanda». Limita la longitud de la sortida, fes streaming de la resposta a la pàgina i no enviïs mai la clau al navegador.

Límits:

Limita cada usuari a 30 peticions d’IA per hora, guardades a la base de dades. Registra els tokens d’entrada i de sortida de cada petició amb l’ID de l’usuari i el nom de la funció. Si OpenAI retorna 429, respecta la capçalera Retry-After i reintenta amb backoff exponencial i jitter fins a 3 vegades; després mostra «La IA està ocupada, torna-ho a provar d’aquí a un minut». Mostra un error amigable per a qualsevol altra fallada i mantén la resta de la pàgina en funcionament.

Gestionar errors i límits

OpenAI mesura els límits de velocitat de diverses maneres, incloent peticions per minut i tokens per minut, i t’arribes a quin s’esgoti primer. Quan en superes un, l’API retorna un 429 amb una capçalera Retry-After. La documentació d’OpenAI diu que cal tractar aquest valor com un mínim i afegir un petit retard aleatori perquè els clients no reintentin tots alhora.

També cal preveure:

• Temps d’espera en generacions llargues. El streaming ajuda, i també un límit de sortida raonable.
• Caigudes del proveïdor. La funció d’IA ha de fallar de manera controlada sense trencar la pàgina.
• Sortida incorrecta. Valida la sortida estructurada abans de guardar-la, i no deixis que la sortida del model dispari accions sensibles sense una comprovació al teu codi.

Errors habituals

• Clau al frontend o al repositori. El codi del navegador és públic, i una clau filtrada es pot abusar en minuts. Consulta com mantenir segures les claus d’API.
• Cap límit de despesa. Un bucle o un usuari abusiu pot fer pujar la factura molt ràpidament.
• Cap límit per usuari. El límit del proveïdor protegeix la teva cartera, no els altres usuaris.
• Confiar en el prompt per a la seguretat. Els usuaris poden escriure «ignora les instruccions anteriors». Els permisos pertanyen al codi del servidor.
• Enviar més del necessari. Els documents sencers i els historials llargs multipliquen el cost. Envia només el que necessita la tasca.
• Codificar el nom del model. Els models s’actualitzen i es retiren; fes-lo una configuració.
• Enviar dades personals sense pensar-hi. Llegeix les condicions d’ús de dades d’OpenAI i envia només el que la funció necessita.

Llista de comprovació

• Projectes d’OpenAI separats (o claus) per a proves i producció
• Clau guardada com a secret del servidor, mai al codi del navegador ni al repositori
• Alertes de despesa i límit de despesa rígid establerts
• Totes les crides passen pel teu servidor i comproven els permisos de l’usuari
• Longitud de sortida limitada; nom del model configurable
• Límit de peticions per usuari a la teva app
• Gestió del 429 amb Retry-After, backoff i jitter
• Estat d’error amigable; la pàgina funciona sense la IA
• Ús de tokens registrat per funció
• Provat amb entrades llargues, buides i hostils

Fer servir l’API d’OpenAI a Mythex

Les funcions d’IA dels apps que construeixes a Mythex fan servir la teva pròpia clau d’OpenAI, facturada al teu compte d’OpenAI i no als crèdits de construcció de Mythex. Afegeix OPENAI_API_KEY com a secret del projecte a través de /secrets, de la configuració del projecte o de la targeta de secrets que mostra l’agent quan necessita una clau, i després descriu la funció amb un prompt com els d’aquí. Després de canviar els secrets en una app publicada, publica-la de nou perquè els recollí. La recepta de la documentació Afegir funcions d’IA amb les teves pròpies claus d’API té un prompt inicial, i Secrets al xat explica la targeta de secrets. Si estàs comparant proveïdors, consulta com integrar l’API de Claude.

Preguntes