Com integrar l’API de Claude a la teva app

Per integrar l’API de Claude, crea una clau d’API a la Claude Console d’Anthropic, guarda-la com a secret del servidor (normalment ANTHROPIC_API_KEY) i crida la Messages API des d’una ruta del teu propi servidor fent servir un dels SDK oficials d’Anthropic. Cada petició indica un model, estableix max_tokens (la resposta més llarga que acceptaràs) i envia la conversa com a messages, amb les instruccions en un system prompt separat. Estableix un límit de despesa, fes streaming de les respostes llargues i gestiona els errors de límit de velocitat (429) i de sobrecàrrega (529) amb reintents.

Aquesta guia cobreix la configuració, un flux de petició segur, prompts per a un constructor d’IA i els errors que cal preveure. Els detalls d’Anthropic són de la seva documentació a setembre de 2026. Per entendre com funcionen els tokens i els preus en general, consulta primer com fer servir les APIs de LLM.

Què pots construir amb això

• Assistents de xat i widgets d’ajuda (com construir una app de xatbot amb IA)
• Resums, reescriptures i respostes redactades
• Extracció de camps de documents, correus i formularis
• Respostes a preguntes a partir del teu propi contingut
• Agents que criden funcions de la teva app mitjançant tool use

Per a més idees, consulta com afegir funcions d’IA a la teva app.

La Messages API en resum

Segons la referència de l’API d’Anthropic, una petició és un POST a https://api.anthropic.com/v1/messages amb:

L’API no guarda estat: per continuar una conversa, cal enviar els torns anteriors a cada petició. Per això els xats llargs costen més per missatge.

Anthropic publica SDK oficials per a Python, TypeScript, C#, Go, Java, PHP i Ruby. Configuren les capçaleres, analitzen les respostes i admeten streaming. Fes-los servir en lloc de HTTP directe, tret que tinguis un motiu per no fer-ho.

Triar un model

Anthropic ofereix diversos models de Claude que equilibren capacitat amb velocitat i preu, i la gamma canvia. Tria el model més petit que faci bé la teva tasca, prova’l amb exemples reals i guarda l’ID del model a la configuració perquè puguis canviar-lo sense modificar el codi. Consulta les pàgines d’Anthropic de models i preus per a les opcions i tarifes actuals.

Configurar el teu compte

1. Inicia sessió a la Claude Console a platform.claude.com i afegeix la facturació.
2. Crea una clau d’API. Tingues una clau per entorn (proves i producció) perquè en puguis revocar una sense trencar l’altra.
3. Estableix un límit de despesa. La pàgina d’errors d’Anthropic indica que, quan l’ús arriba al límit de despesa que has definit, l’API retorna un error 400; la teva app hauria de mostrar un missatge clar quan passi.
4. Revisa els límits de velocitat del teu compte a la Console; es mesuren per organització.

El flux de la petició

1. L’usuari actua a la teva app: envia un missatge, fa clic a «Resumeix».
2. El navegador crida la teva ruta del servidor, mai directament Anthropic.
3. El teu servidor comprova que l’usuari té la sessió iniciada i que pot fer servir la funció, i aplica un límit per usuari.
4. Construeix la petició: un system prompt amb les teves regles, l’entrada de l’usuari i les dades que la tasca necessiti de la teva base de dades.
5. Crida la Messages API amb la clau de l’entorn i un max_tokens raonable.
6. Envia la resposta al navegador en streaming i registra l’ús de tokens que retorna la resposta.

Opcions i compromisos

Prompts per donar al teu constructor d’IA

Una primera funció:

Afegeix un panell «Pregunta sobre aquest document». Crida una ruta del servidor POST /api/ask que comprova que l’usuari ha iniciat sessió i és propietari del document, i després crida la Messages API de Claude amb el SDK oficial d’Anthropic i el secret ANTHROPIC_API_KEY. Llegeix l’ID del model del secret CLAUDE_MODEL. System prompt: «Respon només a partir del document proporcionat. Si la resposta no hi és, digues-ho». Envia el text del document i la pregunta, posa max_tokens a 800, fes streaming de la resposta a la pàgina i no exposis mai la clau al navegador.

Límits i errors:

Limita cada usuari a 20 preguntes per hora, guardades a la base de dades. Registra els tokens d’entrada i de sortida de cada resposta amb l’ID de l’usuari i l’ID de la petició. En cas d’error 429 o 529, reintenta amb backoff exponencial fins a 3 vegades, respectant la capçalera retry-after, i després mostra «L’assistent està ocupat, torna-ho a provar en un moment». Si l’API indica un error de límit de despesa, mostra «Les funcions d’IA estan pausades» i avisa l’administrador.

Errors que cal preveure

Segons la documentació d’errors d’Anthropic, aquests són els que la teva app trobarà de veritat:

Segons la documentació d’Anthropic, els SDK oficials reintenten automàticament els errors transitoris (errors de connexió, límits de velocitat i errors 5xx) dues vegades per defecte amb backoff exponencial, i pots configurar-ho. Cada resposta porta una capçalera request-id; registra-la perquè el suport pugui seguir els problemes.

Errors habituals

• Cridar l’API des del navegador. La teva clau queda pública. Passa sempre pel teu servidor. Consulta com mantenir segures les claus d’API.
• Oblidar que max_tokens és un límit, no un objectiu. Posa-hi el que necessiti la funció: si és massa baix, talla les respostes; si és massa alt, hi ha riscos de respostes llargues i costoses.
• Posar les regles al missatge de l’usuari. Les instruccions estables van al system prompt; els permisos, al teu codi.
• Enviar tot el xat per sempre. Retalla o resumeix els torns antics a mesura que les converses creixen.
• Cap límit de despesa ni límit per usuari.
• Codificar l’ID del model al codi. Els models s’actualitzen i es retiren.
• Ignorar el motiu de parada. Si la resposta s’ha aturat perquè ha arribat a max_tokens, informa l’usuari o augmenta el límit.

Llista de comprovació

• Clau d’API creada a la Claude Console i guardada com a secret del servidor
• Claus separades per a proves i producció
• Límit de despesa establert; missatge clar quan s’arriba
• Totes les peticions passen pel teu servidor amb comprovació de permisos
• El system prompt conté les regles; l’ID del model és configurable
• max_tokens definit per funció; respostes llargues amb streaming
• Límit de velocitat per usuari a la teva app
• 429 i 529 gestionats amb backoff; IDs de petició registrats
• Estat d’error amigable que no trenca la pàgina
• Provat amb entrades buides, molt llargues i hostils

Fer servir l’API de Claude a Mythex

Als apps que construeixes a Mythex, les funcions de Claude fan servir la teva pròpia clau d’Anthropic i es facturen al teu compte d’Anthropic, no als crèdits de construcció de Mythex. Això és independent de l’agent de Mythex que escriu el teu codi. Afegeix ANTHROPIC_API_KEY com a secret del projecte a través de /secrets, de la configuració del projecte o de la targeta de secrets del xat, i després descriu la funció amb prompts com els d’aquí. Publica de nou després de canviar els secrets en una app en directe. Per a un prompt inicial, consulta Afegir funcions d’IA amb les teves pròpies claus d’API. Si estàs triant entre proveïdors, com integrar l’API d’OpenAI cobreix el mateix per a OpenAI.

Preguntes