Anthropic API 연동 방법 Claude를 업무 시스템에 붙이려면 콘솔에서 키를 받고 Messages API로 호출하는 흐름을 먼저 잡아야 합니다. Anthropic API는 공식 호스트의 REST 인터페이스이며 대화형 호출의 핵심은 POST /v1/messages입니다. 이 글은 키 관리부터 모델 선택, 스트리밍, 오류 대응까지 실무 순서로 안내합니다.
요청마다 anthropic-version과 JSON 콘텐츠 타입을 붙이고 인증은 x-api-key 또는 Bearer 중 하나를 고릅니다. 모델 ID와 max_tokens, 메시지 배열을 맞추면 첫 응답을 받을 수 있습니다. 한도 오류와 프롬프트 실수는 연동 직후에 자주 나타나므로 점검 항목을 함께 확인하세요.
Anthropic API 키 발급과 기본 호출 구조
기본 호출은 https://api.anthropic.com 베이스와 헤더, 본문 세 가지를 맞추는 일입니다. 엔드포인트는 POST /v1/messages이고 헤더에는 anthropic-version 값 2023-06-01과 content-type application/json이 필요합니다. 인증은 x-api-key와 Authorization Bearer 중 하나만 넣으면 됩니다.
공식 SDK를 쓰면 환경 변수 ANTHROPIC_API_KEY로 같은 키를 넘깁니다. HTTP를 직접 보낼 때는 헤더 철자와 버전 날짜를 빠뜨리면 바로 거절됩니다. 키 발급과 첫 메시지 호출은 아래 소절에서 순서대로 다룹니다.
요청은 JSON 한 건으로 보냅니다. 필수 헤더가 빠지면 본문이 맞아도 실패합니다.
콘솔에서 API 키 만들고 환경변수로 관리하기
키는 Claude Console의 Settings에서 API keys 메뉴로 들어가 발급합니다. 생성 때 만료 기간을 고르고 값은 화면에서 다시 보이지 않으니 발급 직후 안전한 곳에 복사합니다. 코드와 저장소에 키를 넣지 말고 배포 환경의 환경 변수로만 주입하세요.
로컬에서는 셸 프로필이나 .env에 ANTHROPIC_API_KEY를 두고 SDK가 읽게 합니다. HTTP 직접 호출에서는 x-api-key 헤더에 같은 값을 넣습니다. 권한이 넓은 키는 업무 서버와 실험 환경을 나누면 유출 범위를 줄일 수 있습니다.
폐기되었거나 만료된 키는 401로 이어지므로 순환 일정을 정해 두십시오. 키 이름을 팀 비밀 저장소 규칙에 맞추면 교체 때 배포만 다시 하면 됩니다.
Messages API로 첫 응답 받아보기
본문에는 model, messages, max_tokens를 넣습니다. messages는 user와 assistant가 교차하는 턴 배열이며 한 번의 요청은 무상태입니다. 이전 대화를 이어가려면 클라이언트가 과거 턴을 다시 실어 보냅니다.
첫 호출은 짧은 user 한 턴으로 충분합니다. 응답의 content 블록에서 텍스트를 꺼내 화면에 붙이면 연동 확인이 끝납니다. 모델 ID를 잘못 적으면 거절되므로 콘솔과 문서의 현재 ID를 그대로 쓰세요.
max_tokens는 출력 상한이므로 업무 회신이 길면 값을 넉넉히 둡니다. 빈 messages나 연속된 같은 역할 턴은 거절될 수 있으니 교차 순서를 지키세요.
Claude 모델 선택과 메시지·스트리밍 연동
(출처: 1Click Guides)
대화형은 같은 Messages API로 보내되 응답을 한 번에 받을지 조각으로 받을지만 갈립니다. 스트리밍은 요청 body에 stream: true를 넣고 SSE로 증분 수신합니다. 공식 SDK는 이벤트를 모아 최종 Message 객체로 만듭니다.
채팅 화면처럼 토큰이 이어져 보여야 하면 스트리밍이 맞습니다. 배치 요약처럼 완료 후 저장만 하면 일반 응답이 단순합니다. 연결이 끊기면 부분 텍스트를 버리고 재요청할지 정책을 미리 정해 두세요.
스트리밍 중에도 모델 ID와 max_tokens 규칙은 일반 호출과 같습니다. SSE 이벤트는 델타 텍스트가 이어지다가 종료 신호로 끝납니다. SDK를 쓰면 직접 파싱할 일이 줄어들고 최종 메시지 필드만 읽으면 됩니다.
Haiku·Sonnet·Opus 용도 나누기
현재 Claude API 모델 ID 예시는 claude-haiku-4-5, claude-sonnet-5, claude-opus-5, claude-fable-5입니다. 속도와 가격, 추론 깊이가 달라서 같은 프롬프트를 모든 모델에 쓰지 않습니다. 라우팅은 지연 한도와 품질 기준을 먼저 정한 뒤 ID를 고르면 됩니다.
| 모델 API ID | 용도 | 선택 기준 |
|---|---|---|
| claude-haiku-4-5 | 분류·초안·짧은 응답 | 지연과 비용이 우선일 때 |
| claude-sonnet-5 | 일반 업무 대화 | 속도와 품질의 균형 |
| claude-opus-5 | 긴 추론·어려운 작성 | 품질이 지연보다 중요할 때 |
| claude-fable-5 | 문서에 제시된 최신 라인 | 배포 전 ID 재확인 |
Haiku는 대량 분류와 초안에 두고 Sonnet은 일상 업무 대화에 둡니다. Opus는 검토와 긴 추론에 쓰되 트래픽 전부를 올리지 마세요. 모델 ID는 시점이 바뀌면 문서 표가 갱신되므로 배포 전에 한 번 더 확인합니다.
야간 배치와 실시간 채팅을 한 ID로 묶지 마세요. 비용이 갑자기 늘면 먼저 Haiku로 분류한 뒤 필요한 건만 Sonnet이나 Opus로 올리면 됩니다.
실무에서 자주 막는 인증·한도·프롬프트 이슈
401 authentication_error는 키가 틀렸거나 폐기·만료된 경우입니다. 헤더 이름 오타와 공백이 섞인 키도 같은 오류로 떨어집니다. 콘솔에서 키 상태를 확인하고 환경 변수 주입부터 다시 보십시오.
429 rate_limit_error는 계정 한도를 넘긴 상태입니다. 공식 SDK는 연결 오류와 레이트 리밋, 5xx에 대해 retry-after를 존중하며 지수 백오프로 최대 2회 재시도합니다. 프롬프트는 시스템 지시와 사용자 입력을 한 덩어리로 섞지 말고 역할을 나누세요.
max_tokens를 너무 낮추면 문장이 중간에 끊깁니다. 입력이 길면 컨텍스트 한도에 걸려 거절될 수 있으니 업무 문서는 요약 후 넣습니다. 재시도만으로 프롬프트 오류는 고쳐지지 않으므로 로그에 상태 코드를 남기세요.
Anthropic API 연동 정리와 다음 단계
연동의 뼈대는 키를 환경 변수로 두고 Messages API에 모델과 메시지, max_tokens를 보내는 일입니다. 스트리밍이 필요하면 stream true로 SSE를 받고 SDK 누적을 쓰면 화면에 붙이기가 수월합니다. 모델은 Haiku·Sonnet·Opus 용도를 나눈 뒤 ID를 고정하세요.
운영에 들어가기 전에 401과 429 처리, 재시도 한도를 점검합니다. 공식 SDK 기본값은 일시 실패를 두 번 재시도하므로 업무 큐와 맞는지 확인하십시오. 다음 단계는 도구 호출과 로그 마스킹, 키 순환을 배포 체크리스트에 넣는 일입니다.
연동이 끝나면 콘솔 사용량과 오류율부터 매일 확인하세요. 모델 ID 변경은 호환 테스트를 거친 뒤에 배포합니다. 키 권한과 만료 일정도 같은 주기에 점검하면 장애를 줄일 수 있습니다.
