앱에 Claude API를 연동하는 법

Claude API를 연동하려면, Anthropic의 Claude Console에서 API 키를 만들고, 이를 서버 측 비밀 값(보통 ANTHROPIC_API_KEY)으로 저장한 뒤, Anthropic의 공식 SDK 중 하나를 사용해 자체 서버의 라우트에서 Messages API를 호출하세요. 각 요청은 model을 지정하고, max_tokens(받을 수 있는 가장 긴 응답)를 설정하며, 대화를 messages로 보냅니다. 지시 사항은 별도의 system 프롬프트에 둡니다. 지출 한도를 설정하고, 긴 응답은 스트리밍하고, 속도 제한(429)과 과부하(529) 오류는 재시도로 처리하세요.

이 가이드는 설정, 안전한 요청 흐름, AI 빌더용 프롬프트, 그리고 대비해야 할 오류를 다룹니다. Anthropic 관련 세부 내용은 2026년 9월 기준 공식 문서를 따릅니다. 토큰과 가격의 일반 원리는 LLM API 사용법에서 먼저 읽어 보세요.

이 API로 만들 수 있는 것

• 채팅 어시스턴트와 도움말 위젯 (AI 챗봇 앱 만드는 법)
• 요약, 다시 쓰기, 답장 초안 작성
• 문서, 이메일, 양식에서 필드 추출
• 여러분의 콘텐츠를 바탕으로 한 질문 답변
• 도구 사용(tool use)을 통해 앱의 함수를 호출하는 에이전트

더 많은 아이디어는 앱에 AI 기능 추가하는 법을 참고하세요.

Messages API 요약

Anthropic API 레퍼런스에 따르면, 요청은 https://api.anthropic.com/v1/messages로 보내는 POST이며 다음을 포함합니다:

API는 상태를 저장하지 않습니다. 대화를 이어가려면 요청마다 이전 차례를 다시 보내야 합니다. 그래서 대화가 길어질수록 메시지당 비용이 늘어납니다.

Anthropic은 Python, TypeScript, C#, Go, Java, PHP, Ruby용 공식 SDK를 제공합니다. SDK는 헤더를 설정하고, 응답을 파싱하며, 스트리밍을 지원합니다. 특별한 이유가 없다면 원시 HTTP 대신 SDK를 쓰세요.

모델 선택

Anthropic은 성능, 속도, 가격의 균형이 다른 여러 Claude 모델을 제공하며, 라인업은 바뀝니다. 작업을 잘 수행하는 가장 작은 모델을 고르고, 실제 예시로 테스트하고, 모델 ID는 설정값으로 두어 코드를 고치지 않고도 바꿀 수 있게 하세요. 최신 선택지와 요금은 Anthropic의 모델 및 가격 페이지에서 확인하세요.

계정 설정하기

1. platform.claude.com의 Claude Console에 로그인하고 결제 정보를 추가하세요.
2. API 키를 만드세요. 테스트용과 운영용으로 환경마다 키를 하나씩 두면, 하나를 폐기해도 다른 쪽이 깨지지 않습니다.
3. 지출 한도를 설정하세요. Anthropic의 오류 문서에 따르면, 설정한 지출 한도에 도달하면 API가 400 오류를 반환하므로, 앱은 이때 분명한 메시지를 보여줘야 합니다.
4. Console에서 계정의 속도 제한을 확인하세요. 제한은 조직 단위로 측정됩니다.

요청 흐름

1. 사용자가 앱에서 행동합니다. 메시지를 보내거나 “요약”을 클릭합니다.
2. 브라우저는 Anthropic을 직접 호출하지 않고, 여러분의 서버 라우트를 호출합니다.
3. 서버는 사용자가 로그인했고 이 기능을 쓸 권한이 있는지 확인하며, 사용자별 한도를 적용합니다.
4. 서버가 요청을 만듭니다. 여러분의 규칙이 담긴 시스템 프롬프트, 사용자의 입력, 작업에 필요한 데이터베이스의 데이터를 포함합니다.
5. 환경 변수의 키와 적절한 max_tokens로 Messages API를 호출합니다.
6. 응답을 브라우저로 스트리밍하고, 응답에서 토큰 사용량을 기록합니다.

선택지와 트레이드오프

AI 빌더에 줄 프롬프트

첫 기능:

문서 페이지에 “이 문서에 대해 질문하기” 패널을 추가해 주세요. 서버 라우트 POST /api/ask를 호출하는데, 이 라우트는 사용자가 로그인했고 문서를 소유하고 있는지 확인한 뒤, 공식 Anthropic SDK와 비밀 값 ANTHROPIC_API_KEY로 Claude Messages API를 호출합니다. 모델 ID는 비밀 값 CLAUDE_MODEL에서 읽어 주세요. 시스템 프롬프트: “제공된 문서에서만 답하세요. 답이 문서에 없으면 그렇다고 말하세요.” 문서 텍스트와 질문을 보내고, max_tokens는 800으로 설정하고, 답변을 페이지로 스트리밍하며, 키는 절대 브라우저에 노출하지 마세요.

가드레일과 오류 처리:

사용자당 시간당 질문 20개로 제한하고, 이 제한은 데이터베이스에 기록해 주세요. 각 응답의 입력·출력 토큰을 사용자 ID와 요청 ID와 함께 기록하세요. 429 또는 529 오류가 나면 지수 백오프로 최대 3번 재시도하되, retry-after 헤더를 따르세요. 그 후에도 실패하면 “어시스턴트가 바쁩니다. 잠시 후 다시 시도해 주세요.”를 보여 주세요. API가 지출 한도 오류를 보고하면 “AI 기능이 일시 중지되었습니다”를 보여 주고 관리자에게 알리세요.

대비해야 할 오류

Anthropic의 오류 문서에 따르면, 앱이 실제로 마주치게 될 오류는 다음과 같습니다:

Anthropic 문서에 따르면, 공식 SDK는 일시적인 실패(연결 오류, 속도 제한, 5xx 오류)를 기본값으로 지수 백오프와 함께 두 번 자동 재시도하며, 이 설정은 바꿀 수 있습니다. 모든 응답에는 request-id 헤더가 붙어 있으니, 지원팀이 문제를 추적할 수 있도록 기록해 두세요.

흔한 실수

• 브라우저에서 API 호출하기. 키가 공개됩니다. 항상 서버를 거치세요. API 키를 안전하게 보관하는 법을 참고하세요.
• max_tokens가 목표가 아니라 상한이라는 것을 잊기. 기능에 필요한 만큼으로 설정하세요. 너무 낮으면 답이 잘리고, 너무 높으면 길고 비싼 응답의 위험이 있습니다.
• 규칙을 사용자 메시지에 넣기. 변하지 않는 지시는 system 프롬프트에 두고, 권한은 코드에서 처리하세요.
• 대화 전체를 영원히 보내기. 대화가 길어지면 오래된 차례를 잘라내거나 요약하세요.
• 지출 한도나 사용자별 상한이 없음.
• 모델 ID를 하드코딩하기. 모델은 업데이트되고 폐기됩니다.
• 정지 사유(stop reason) 무시하기. 응답이 max_tokens에 도달해 멈췄다면, 사용자에게 알리거나 상한을 올리세요.

체크리스트

• Claude Console에서 API 키를 만들고 서버 측 비밀 값으로 저장함
• 테스트용과 운영용 키를 분리함
• 지출 한도를 설정하고, 도달했을 때 분명한 메시지를 보여 줌
• 모든 요청이 권한 확인을 거치는 서버를 통함
• 시스템 프롬프트에 규칙을 두고, 모델 ID는 설정 가능함
• 기능별로 max_tokens를 설정하고, 긴 응답은 스트리밍함
• 앱에 사용자별 속도 제한이 있음
• 429와 529를 백오프로 처리하고, 요청 ID를 기록함
• 페이지를 깨뜨리지 않는 친절한 오류 상태가 있음
• 빈 입력, 아주 긴 입력, 악의적인 입력으로 테스트함

Mythex에서 Claude API 사용하기

Mythex로 만든 앱에서 Claude 기능은 Mythex 빌드 크레딧이 아니라, 여러분 자신의 Anthropic 키를 사용하고 여러분의 Anthropic 계정에 청구됩니다. 이는 여러분의 코드를 작성하는 Mythex 에이전트와는 별개입니다. ANTHROPIC_API_KEY는 /secrets, 프로젝트 설정, 또는 채팅의 비밀 값 카드를 통해 프로젝트 비밀 값으로 추가하세요. 그다음 위와 같은 프롬프트로 기능을 설명하면 됩니다. 게시된 앱에서 비밀 값을 바꾼 뒤에는 다시 게시해야 라이브 앱에 반영됩니다. 시작용 프롬프트는 AI 기능을 자체 API 키로 추가하기를 참고하세요. 제공업체를 비교 중이라면, OpenAI API 연동하는 법에서 OpenAI에 대해 같은 내용을 다룹니다.

자주 묻는 질문