Cum integrezi Claude API în aplicația ta

Pentru a integra Claude API, creează o cheie API în Claude Console-ul Anthropic, salveaz-o ca secret pe server (de obicei ANTHROPIC_API_KEY) și apelează Messages API dintr-o rută de pe propriul tău server, folosind unul dintre SDK-urile oficiale ale Anthropic. Fiecare cerere indică un model, setează max_tokens (cel mai lung răspuns pe care îl accepți) și trimite conversația ca messages, cu instrucțiunile tale într-un prompt de sistem separat, system. Setează o limită de cheltuieli, transmite în flux răspunsurile lungi și tratează erorile de limită de rată (429) și de supraîncărcare (529) cu reîncercări.

Acest ghid acoperă configurarea, un flux sigur de cereri, prompturi pentru un constructor de aplicații cu AI și erorile la care trebuie să te pregătești. Detaliile Anthropic sunt din documentația sa din septembrie 2026. Pentru cum funcționează în general tokenii și prețurile, vezi cum să folosești API-urile LLM.

Ce poți construi cu el

Asistenți de chat și widgeturi de ajutor (cum să construiești o aplicație chatbot cu AI)
Rezumate, rescrieri și răspunsuri redactate
Extragerea câmpurilor din documente, emailuri și formulare
Răspunsuri la întrebări pe baza propriului conținut
Agenți care apelează funcțiile aplicației tale prin tool use

Pentru mai multe idei, vezi cum să adaugi funcții AI în aplicația ta.

Messages API pe scurt

Conform documentației de referință a API-ului Anthropic, o cerere este un POST către https://api.anthropic.com/v1/messages, cu:

Parte	Ce este
Antetul `x-api-key`	Cheia ta API
Antetul `anthropic-version`	Versiunea API-ului, de exemplu `2023-06-01`
`model` (obligatoriu)	Modelul Claude folosit
`max_tokens` (obligatoriu)	Numărul maxim de tokeni pe care îi poate avea răspunsul; modelul se poate opri mai devreme
`messages` (obligatoriu)	Conversația: ture alternative `user` și `assistant`
`system` (opțional)	Instrucțiuni care se aplică întregii conversații
`stream` (opțional)	Setat la `true` ca să primești răspunsul pe măsură ce este scris, prin server-sent events

API-ul este fără stare: ca să continui o conversație, trimite din nou turele anterioare cu fiecare cerere. De aceea conversațiile lungi costă mai mult pe mesaj.

Anthropic publică SDK-uri oficiale pentru Python, TypeScript, C#, Go, Java, PHP și Ruby. Ele setează antetele, interpretează răspunsurile și suportă streaming. Folosește-le în locul HTTP-ului brut, cu excepția cazului în care ai un motiv anume.

Alegerea unui model

Anthropic oferă mai multe modele Claude, care fac compromisuri între capacitate, viteză și preț, iar gama se schimbă. Alege cel mai mic model care face bine treaba ta, testează-l pe exemple reale și păstrează ID-ul modelului în configurare, ca să poți schimba fără modificări de cod. Verifică paginile Anthropic cu modele și prețuri pentru opțiunile și tarifele actuale.

Configurarea contului

Autentifică-te în Claude Console la platform.claude.com și adaugă un mod de plată.
Creează o cheie API. Păstrează câte o cheie pentru fiecare mediu (testare și producție), ca să poți revoca una fără să o strici pe cealaltă.
Setează o limită de cheltuieli. Pagina de erori a Anthropic menționează că atunci când utilizarea ajunge la o limită de cheltuieli pe care ai setat-o, API-ul returnează o eroare 400, deci aplicația ta ar trebui să afișeze un mesaj clar în acest caz.
Verifică limitele de rată ale contului tău în Console; acestea se măsoară per organizație.

Fluxul unei cereri

Utilizatorul acționează în aplicația ta: trimite un mesaj, apasă pe „Rezumă”.
Browserul apelează ruta ta de pe server, niciodată direct Anthropic.
Serverul tău verifică dacă utilizatorul este autentificat și are voie să folosească funcția și aplică o limită per utilizator.
Construiește cererea: un prompt de sistem cu regulile tale, intrarea utilizatorului și orice date necesare task-ului din baza ta de date.
Apelează Messages API cu cheia din mediu și un max_tokens rezonabil.
Transmite răspunsul în flux către browser și înregistrează consumul de tokeni din răspuns.

Opțiuni și compromisuri

Decizie	Alegere simplă	Când să mergi mai departe
Streaming	Aștepți răspunsul complet	Folosește streaming pentru chat și pentru orice răspuns lung; Anthropic recomandă streaming sau batch-uri pentru cererile de lungă durată
Format de ieșire	Text simplu	Ieșire JSON structurată, când codul tău trebuie să citească câmpuri
Datele tale	Include înregistrarea relevantă	Recuperare din propriul conținut când sunt prea multe date (ce este RAG)
Acțiuni	Modelul doar scrie text	Tool use, unde modelul cere codului tău să ruleze o funcție definită de tine
Muncă în masă, fără urgență	Parcurge elementele într-o buclă	Message Batches API, unde trimiți cererile și verifici rezultatele mai târziu

Prompturi pentru constructorul tău de AI

O primă funcție:

Adaugă un panou „Întreabă despre acest document”. Apelează o rută de server POST /api/ask care verifică dacă utilizatorul este autentificat și deține documentul, apoi apelează Claude Messages API cu SDK-ul oficial Anthropic și secretul ANTHROPIC_API_KEY. Citește ID-ul modelului din secretul CLAUDE_MODEL. Prompt de sistem: „Răspunde doar pe baza documentului furnizat. Dacă răspunsul nu este în el, spune asta.” Trimite textul documentului și întrebarea, setează max_tokens la 800, transmite răspunsul în flux către pagină și nu expune niciodată cheia în browser.

Protecții și erori:

Limitează fiecare utilizator la 20 de întrebări pe oră, urmărite în baza de date. Înregistrează tokenii de intrare și de ieșire din fiecare răspuns, cu ID-ul utilizatorului și ID-ul cererii. La erorile 429 sau 529, reîncearcă cu backoff exponențial de până la 3 ori, respectând eventualul antet retry-after, apoi afișează „Asistentul este ocupat, încearcă din nou în curând.” Dacă API-ul raportează o eroare de limită de cheltuieli, afișează „Funcțiile AI sunt suspendate” și anunță administratorul.

Erori la care trebuie să te pregătești

Din documentația Anthropic privind erorile, cele pe care aplicația ta chiar le va întâlni:

Cod	Tip	Ce trebuie făcut
400	`invalid_request_error`	Repară cererea; se returnează și când atingi o limită de cheltuieli pe care ai setat-o
401	`authentication_error`	Verifică dacă cheia există, este corectă și nu a fost revocată
413	`request_too_large`	Trimite mai puțin; Messages API acceptă până la 32 MB pe cerere
429	`rate_limit_error`	Întârzie și reîncearcă, respectând `retry-after`
500	`api_error`	Reîncearcă cu backoff; contactează suportul cu ID-ul cererii dacă problema persistă
529	`overloaded_error`	Trafic temporar mare de la toți utilizatorii; întârzie și reîncearcă

Documentația Anthropic spune că SDK-urile oficiale reîncearcă automat erorile tranzitorii (erori de conexiune, limite de rată și erori 5xx) de două ori implicit, cu backoff exponențial, iar acest comportament poate fi configurat. Fiecare răspuns conține un antet request-id; înregistreaz-l, ca suportul să poată urmări problemele.

Greșeli frecvente

Apelarea API-ului din browser. Cheia ta devine publică. Treci întotdeauna prin serverul tău. Vezi cum să păstrezi în siguranță cheile API.
Uitatul că max_tokens este o limită, nu o țintă. Setează-l la ce are nevoie funcția; prea mic taie răspunsurile, prea mare riscă răspunsuri lungi și costisitoare.
Punerea regulilor în mesajul utilizatorului. Instrucțiunile stabile aparțin promptului system; permisiunile aparțin codului tău.
Trimiterea întregului chat la nesfârșit. Taie sau rezumă turele vechi pe măsură ce conversațiile cresc.
Lipsa unei limite de cheltuieli sau a unei limite per utilizator.
Scrierea ID-ului modelului direct în cod. Modelele sunt actualizate și retrase.
Ignorarea motivului opririi. Dacă răspunsul s-a oprit pentru că a atins max_tokens, spune-i utilizatorului sau mărește limita.

Listă de verificare

Cheie API creată în Claude Console și salvată ca secret pe server
Chei separate pentru testare și producție
Limită de cheltuieli setată; mesaj clar când este atinsă
Toate cererile trec prin serverul tău, cu verificări de permisiuni
Promptul de sistem conține regulile; ID-ul modelului este configurabil
max_tokens setat per funcție; răspunsurile lungi sunt transmise în flux
Limită de rată per utilizator în aplicația ta
Erorile 429 și 529 tratate cu backoff; ID-urile cererilor înregistrate
Stare de eroare prietenoasă, care nu strică pagina
Testat cu intrări goale, foarte lungi și ostile

Folosirea Claude API în Mythex

În aplicațiile pe care le construiești pe Mythex, funcțiile Claude folosesc propria ta cheie Anthropic și sunt facturate în contul tău Anthropic, nu din creditele de construire Mythex. Aceasta este separată de agentul Mythex care scrie codul tău. Adaugă ANTHROPIC_API_KEY ca secret de proiect prin /secrets, din setările proiectului sau din cardul de secrete din chat, apoi descrie funcția folosind prompturi ca cele de mai sus. Publică din nou după ce schimbi secretele unei aplicații live. Vezi Adaugă funcții AI cu propriile chei API pentru un prompt de pornire. Dacă alegi între furnizori, cum să integrezi OpenAI API acoperă aceleași aspecte pentru OpenAI.

Întrebări

Cum obțin o cheie API pentru Claude?

Autentifică-te în Claude Console, de la platform.claude.com, configurează facturarea și creează o cheie API. Salveaz-o ca secret pe server, de obicei cu numele ANTHROPIC_API_KEY, și nu o pune niciodată în codul din browser.

Ce are nevoie o cerere către Claude API?

Din septembrie 2026, documentația Messages API a Anthropic listează trei câmpuri obligatorii în corpul cererii: model, max_tokens și messages. Apelurile HTTP directe necesită și anteturile x-api-key și anthropic-version; SDK-urile oficiale le setează pentru tine.

Ce înseamnă o eroare 529 de la Claude API?

Pagina de erori a Anthropic descrie 529 drept overloaded_error: API-ul este temporar supraîncărcat din cauza traficului mare de la toți utilizatorii. Reîncearcă cu backoff exponențial. SDK-urile oficiale reîncearcă automat unele erori tranzitorii.

Pot folosi Claude cu cod scris pentru SDK-ul OpenAI?

Anthropic documentează un strat de compatibilitate cu SDK-ul OpenAI, ca să folosești Claude prin interfața SDK-ului OpenAI. Pentru cod nou, SDK-urile proprii oferă acces la funcționalitățile specifice Claude, așa că sunt de obicei un punct de plecare mai bun.