Jak zintegrować Claude API z aplikacją

Aby zintegrować Claude API, utwórz klucz API w Claude Console Anthropic, przechowuj go jako sekret po stronie serwera (zwykle ANTHROPIC_API_KEY) i wywołuj Messages API z trasy na własnym serwerze, korzystając z jednego z oficjalnych SDK Anthropic. Każde żądanie wskazuje model, ustawia max_tokens (najdłuższą odpowiedź, jaką akceptujesz) i przesyła rozmowę jako messages, a Twoje instrukcje — w osobnym prompcie system. Ustaw limit wydatków, strumieniuj długie odpowiedzi i obsługuj błędy limitu zapytań (429) oraz przeciążenia (529) ponownymi próbami.

Ten przewodnik obejmuje konfigurację, bezpieczny przebieg żądania, prompty dla narzędzia do budowy aplikacji AI i błędy, na które trzeba się przygotować. Szczegóły Anthropic pochodzą z ich dokumentacji według stanu na wrzesień 2026 r. Informacje o tym, jak działają tokeny i ceny w ogóle, znajdziesz w jak korzystać z API LLM.

Co możesz dzięki temu zbudować

• Asystentów czatu i widżety pomocy (jak zbudować aplikację chatbota AI)
• Podsumowania, przeróbki tekstu i projekty odpowiedzi
• Wyciąganie pól z dokumentów, e-maili i formularzy
• Odpowiadanie na pytania na podstawie Twoich własnych treści
• Agentów, które wywołują funkcje Twojej aplikacji przez użycie narzędzi (tool use)

Więcej pomysłów znajdziesz w jak dodać funkcje AI do aplikacji.

Messages API w skrócie

Według dokumentacji API od Anthropic żądanie to POST na https://api.anthropic.com/v1/messages z:

API jest bezstanowe: aby kontynuować rozmowę, wysyłasz wcześniejsze tury ponownie przy każdym żądaniu. Dlatego długie czaty kosztują więcej za każdą wiadomość.

Anthropic publikuje oficjalne SDK dla Pythona, TypeScript, C#, Go, Javy, PHP i Ruby. Ustawiają nagłówki, przetwarzają odpowiedzi i obsługują streaming. Używaj ich zamiast surowego HTTP, chyba że masz konkretny powód, by tego nie robić.

Wybór modelu

Anthropic oferuje kilka modeli Claude, które wymieniają możliwości na szybkość i cenę, a ich oferta się zmienia. Wybierz najmniejszy model, który dobrze radzi sobie z Twoim zadaniem, przetestuj go na prawdziwych przykładach i trzymaj identyfikator modelu w konfiguracji, abyś mógł go zmienić bez zmiany kodu. Aktualne opcje i stawki sprawdź na stronach Anthropic z modelami i cenami.

Konfiguracja konta

1. Zaloguj się do Claude Console pod adresem platform.claude.com i dodaj płatności.
2. Utwórz klucz API. Miej osobny klucz dla każdego środowiska (testowego i produkcyjnego), aby móc unieważnić jeden bez psucia drugiego.
3. Ustaw limit wydatków. Strona z błędami Anthropic zauważa, że gdy zużycie osiągnie ustawiony przez Ciebie limit wydatków, API zwraca błąd 400, więc Twoja aplikacja powinna wyświetlić wtedy jasny komunikat.
4. Sprawdź limity zapytań dla swojego konta w Console; są mierzone na poziomie organizacji.

Przebieg żądania

1. Użytkownik działa w Twojej aplikacji: wysyła wiadomość, klika „Podsumuj".
2. Przeglądarka wywołuje Twoją trasę na serwerze, nigdy bezpośrednio Anthropic.
3. Twój serwer sprawdza, czy użytkownik jest zalogowany i może korzystać z tej funkcji, oraz stosuje limit dla danego użytkownika.
4. Buduje żądanie: prompt systemowy z Twoimi zasadami, dane wejściowe użytkownika i dane potrzebne do zadania z bazy danych.
5. Wywołuje Messages API z kluczem z konfiguracji środowiska i rozsądnym max_tokens.
6. Przesyła odpowiedź do przeglądarki w strumieniu i zapisuje zużycie tokenów z odpowiedzi.

Opcje i kompromisy

Prompty dla Twojego narzędzia do budowy aplikacji

Pierwsza funkcja:

Dodaj panel „Zapytaj o ten dokument". Wywołuje trasę serwera POST /api/ask, która sprawdza, czy użytkownik jest zalogowany i jest właścicielem dokumentu, a następnie wywołuje Claude Messages API z oficjalnym SDK Anthropic i sekretem ANTHROPIC_API_KEY. Odczytaj identyfikator modelu z sekretu CLAUDE_MODEL. Prompt systemowy: „Odpowiadaj wyłącznie na podstawie podanego dokumentu. Jeśli odpowiedzi w nim nie ma, powiedz o tym." Wyślij tekst dokumentu i pytanie, ustaw max_tokens na 800, strumieniuj odpowiedź na stronę i nigdy nie ujawniaj klucza w przeglądarce.

Zabezpieczenia i błędy:

Ogranicz każdego użytkownika do 20 pytań na godzinę, śledzonych w bazie danych. Zapisuj liczbę tokenów wejściowych i wyjściowych z każdej odpowiedzi wraz z ID użytkownika i ID żądania. Przy błędach 429 lub 529 ponawiaj z wykładniczym opóźnieniem do 3 razy, uwzględniając nagłówek retry-after, a potem pokaż „Asystent jest teraz zajęty, spróbuj ponownie za chwilę." Jeśli API zgłasza błąd limitu wydatków, pokaż „Funkcje AI są wstrzymane" i powiadom administratora.

Błędy, na które trzeba się przygotować

Z dokumentacji błędów Anthropic — te, które Twoja aplikacja rzeczywiście napotka:

Dokumentacja Anthropic mówi, że oficjalne SDK automatycznie ponawiają przejściowe błędy (błędy połączenia, limity zapytań i błędy 5xx) domyślnie dwa razy, z wykładniczym opóźnieniem, a tę wartość można skonfigurować. Każda odpowiedź zawiera nagłówek request-id; zapisuj go, aby pomoc techniczna mogła prześledzić problemy.

Częste błędy

• Wywoływanie API z przeglądarki. Twój klucz staje się publiczny. Zawsze przechodź przez swój serwer. Zobacz jak chronić klucze API.
• Zapominanie, że max_tokens to limit, a nie cel. Ustaw go na tyle, ile potrzebuje funkcja; zbyt niski ucina odpowiedzi, zbyt wysoki grozi długimi, kosztownymi odpowiedziami.
• Wpisywanie reguł w wiadomości użytkownika. Stałe instrukcje należą do promptu system; uprawnienia powinny być w Twoim kodzie.
• Wysyłanie całego czatu w nieskończoność. Przycinaj lub podsumowuj starsze tury, gdy rozmowa się wydłuża.
• Brak limitu wydatków lub limitu na użytkownika.
• Wpisywanie na sztywno identyfikatora modelu. Modele są aktualizowane i wycofywane.
• Ignorowanie powodu zatrzymania. Jeśli odpowiedź zatrzymała się, bo osiągnęła max_tokens, poinformuj użytkownika lub podnieś limit.

Lista kontrolna

• Klucz API utworzony w Claude Console i zapisany jako sekret po stronie serwera
• Osobne klucze do testów i do produkcji
• Ustawiony limit wydatków; jasny komunikat, gdy zostanie osiągnięty
• Wszystkie żądania przechodzą przez Twój serwer z kontrolą uprawnień
• Reguły są w prompcie systemowym; identyfikator modelu jest konfigurowalny
• max_tokens ustawiony dla każdej funkcji; długie odpowiedzi strumieniowane
• Limit zapytań na użytkownika w Twojej aplikacji
• Błędy 429 i 529 obsłużone z opóźnieniem; ID żądań zapisywane
• Przyjazny stan błędu, który nie psuje strony
• Przetestowane z pustymi, bardzo długimi i wrogimi danymi wejściowymi

Używanie Claude API w Mythex

W aplikacjach budowanych w Mythex funkcje Claude korzystają z Twojego własnego klucza Anthropic i są rozliczane na Twoim koncie Anthropic, a nie w kredytach budowania Mythex. To odrębne od agenta Mythex, który pisze Twój kod. Dodaj ANTHROPIC_API_KEY jako sekret projektu przez /secrets, ustawienia projektu lub kartę sekretów w czacie, a następnie opisz funkcję, używając promptów podobnych do powyższych. Po zmianie sekretów w działającej aplikacji opublikuj ją ponownie. Gotowy prompt startowy znajdziesz w Dodawanie funkcji AI za pomocą własnych kluczy API. Jeśli wybierasz między dostawcami, jak zintegrować OpenAI API omawia to samo dla OpenAI.

Pytania