Claude API 연동 튜토리얼: Console, API 키와 Messages 호출 (2026)

Claude API 연동에서 어려운 것은 "HTTP 요청을 보낼 줄 아느냐"가 아니라 몇 가지 놓치기 쉬운 세부 사항입니다. 키를 어느 요청 헤더에 넣는지, anthropic-version이 필수인지, max_tokens를 왜 생략할 수 없는지, content가 왜 문자열이 아니라 배열인지입니다. 이것만 제대로 맞추면 최소 호출은 10분 안에 실행할 수 있습니다.

이 글은 "계정과 키, 요청 헤더, curl, Python, 스트리밍과 파라미터, 오류 해결, 키 보안" 순서로 설명하고, 마지막에 호환 게이트웨이를 대체 진입점으로 쓰는 방법을 다룹니다. 모델 ID, 컨텍스트, 과금은 Anthropic 공식 문서와 사이트 내 모델 가격을 기준으로 합니다.

안내: Anthropic과 Claude는 해당 권리자의 상표이며, OpenAI는 해당 권리자의 상표입니다. 이 글은 기술적 연동 설명만 제공합니다. 모델, 가격, 할당량은 변경될 수 있으므로 연동 전에 공식 문서를 확인하세요.

1. 연동 전 준비: 계정, 워크스페이스, 키

Claude API는 Anthropic Console에서 계정, 워크스페이스, API 키, 청구를 관리합니다. 시작 전에 세 가지를 확인하세요.

준비 항목	확인할 내용	설명
계정	이메일 인증이 가능하고 Console에 로그인할 수 있는지	팀 사용 시 회사 이메일 권장
워크스페이스	키가 어느 워크스페이스에 속하는지	워크스페이스가 멤버, 키, 사용량 귀속에 영향
과금	결제 수단, 청구 정보, 사용 가능 한도	Console에 실제 표시되는 내용 기준

팀에서 아직 청구 담당자를 정하지 않았다면 운영용 키를 서두르지 마세요. 키를 한 번 배포하면 사용량과 권한이 해당 워크스페이스에 묶이므로 나중에 분리하는 비용이 더 커집니다.

2. API 키 생성: 6단계

Anthropic Console(console.anthropic.com)을 열고 가입하거나 로그인한 뒤 이메일 인증을 마칩니다.
워크스페이스를 만들거나 선택합니다. 운영, 테스트, 개인 실험을 분리해 하나의 키를 여러 곳에서 쓰지 않도록 하세요.
API Keys 페이지에서 새 키를 만들고 이름에 용도를 분명히 적습니다. 예: prod-backend-2026-10.
키를 복사해 즉시 비밀 관리 서비스나 환경 변수에 저장합니다. 대부분의 콘솔은 생성 시점에만 전체 값을 한 번 보여 줍니다.
Console의 청구 페이지에서 결제 수단, 청구 정보, 한도 설정을 확인합니다. 선불 충전, 인보이스, 한도 상한 지원 여부는 콘솔의 실제 옵션을 기준으로 합니다.
로컬에 환경 변수를 설정하고 최소 요청을 보내 키가 동작하는지 확인합니다.

export ANTHROPIC_API_KEY="sk-ant-여기의-키"

키를 코드, Git 저장소, 프런트엔드 페이지, 채팅 기록에 적지 마세요. 테스트 단계에서도 별도 키를 만들어 두면 언제든 폐기할 수 있습니다.

3. 요청 헤더와 최소 curl 호출

Messages API의 엔드포인트는 POST https://api.anthropic.com/v1/messages이며, 세 개의 요청 헤더가 가장 중요합니다.

요청 헤더	값	역할
`x-api-key`	발급받은 API 키	Anthropic API 키 인증
`anthropic-version`	`2023-06-01`	API 버전 지정, 누락 시 오류가 날 수 있음
`content-type`	`application/json`	JSON 요청 본문 선언

주의: API 키는 Authorization: Bearer가 아니라 x-api-key로 전달합니다. 이 두 인증 방식을 섞는 것이 흔한 401 원인입니다.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "당신은 한국어 기술 어시스턴트이며 간결하게 답합니다.",
    "messages": [
      {"role": "user", "content": "API 게이트웨이가 무엇인지 세 문장으로 설명하세요."}
    ]
  }'

예시의 모델 ID는 현재 사용 가능한 모델 중 하나일 뿐이며, 실제 사용 가능한 모델, 컨텍스트, 가격은 공식 Models API와 사이트 내 모델 가격을 기준으로 합니다. 응답의 content는 콘텐츠 블록 배열이고 텍스트는 보통 content[0].text에 있지만, 순회하면서 type == "text"를 확인하는 편이 더 안전합니다.

4. Python으로 Messages API 호출

공식 SDK를 설치합니다.

pip install anthropic

최소 호출은 다음과 같습니다.

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="당신은 한국어 기술 어시스턴트이며 간결하게 답합니다.",
    messages=[
        {"role": "user", "content": "API 게이트웨이가 무엇인지 세 문장으로 설명하세요."}
    ],
)

for block in resp.content:
    if block.type == "text":
        print(block.text)

print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)

몇 가지 요점이 있습니다.

system은 최상위 파라미터입니다. {"role": "system"} 메시지로 쓰지 마세요. Messages API의 메시지 역할은 주로 user와 assistant입니다.
max_tokens는 필수이며 이번 응답의 최대 출력 길이를 뜻합니다. 너무 작으면 잘리고 stop_reason에 max_tokens가 표시됩니다. 너무 크게 잡으면 비용과 타임아웃을 함께 고려해야 합니다.
resp.content는 블록 배열이며 텍스트 블록, 사고 블록, 도구 호출 블록이 포함될 수 있습니다. 업무 코드가 텍스트만 있다고 가정하면 안 됩니다.
usage와 stop_reason을 기록하세요. 대사와 장애 분석 모두 이 값에 기댑니다.

5. system, max_tokens와 스트리밍 출력

system에는 역할 설정, 출력 형식, 경계 조건을 넣습니다. 변하지 않는 내용을 앞에 두고 변하는 사용자 입력을 messages에 두면 캐시 적중에 유리합니다.

max_tokens는 "많을수록 좋은" 값이 아닙니다. 한 번의 출력 상한을 제한할 뿐 입력 비용을 바꾸지는 않습니다. 긴 보고서와 긴 코드에는 충분한 공간을 주고, 분류와 추출에는 작게 잡아도 됩니다. 운영 환경에서는 전역 값 하나 대신 인터페이스 유형별로 따로 설정하는 편이 좋습니다.

스트리밍 출력은 긴 답변과 대화형 화면에 적합합니다. Python SDK 예시는 다음과 같습니다.

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=4096,
    system="당신은 한국어 기술 어시스턴트입니다.",
    messages=[{"role": "user", "content": "200자 분량의 제품 설명을 작성하세요."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

스트리밍 요청도 usage와 stop_reason을 반환하므로 저장할 때 빠뜨리지 마세요. 원시 HTTP를 쓴다면 요청 본문에 "stream": true를 넣고, 응답은 SSE 이벤트 스트림으로 받아 content_block_delta 등의 이벤트를 파싱합니다.

6. 모델 이름과 버전 선택

Claude 모델은 Opus, Sonnet, Haiku 등의 시리즈로 나뉘며 시리즈마다 포지션, 컨텍스트, 가격이 다릅니다. 모델 ID는 보통 안정 별칭과 날짜가 붙은 스냅샷 두 가지 형태가 있습니다. 운영 환경에서는 어느 쪽을 쓸지 명확히 정하고, 콘솔 표시 이름을 코드에 그대로 쓰지 마세요.

선택 순서는 다음과 같습니다.

먼저 업무 평가 세트로 품질 요구를 충족하는 시리즈를 추립니다.
다음으로 지연 시간, 컨텍스트, 비용을 비교합니다.
마지막으로 해당 모델이 목표 지역과 연동 방식에서 사용 가능한지 확인합니다.

모델은 추가되거나 종료될 수 있고 오래된 ID는 레거시 상태가 될 수 있습니다. 모델 이름을 설정이나 매핑 테이블에 모아 두면 이전할 때 한 곳만 고치면 됩니다. 구체적인 사용 가능 모델은 공식 Models API, 콘솔, 사이트 내 모델 가격을 기준으로 합니다.

7. 401, 429, 400 문제 해결

상태 코드	흔한 원인	처리 순서
401	키 누락, 헤더 오타, 키 폐기, 워크스페이스 불일치	`x-api-key`, 공백·줄바꿈, 키 상태, base URL 확인
429	요청 빈도 또는 토큰 속도 초과, 동시성 급증, 할당량 문제	`retry-after` 확인, 지수 백오프와 지터, 키 분리, 동시성 축소
400	잘못된 JSON, `max_tokens` 누락, 모델 ID 오류, 파라미터 초과	오류 본문과 request id 보존, 요청 본문 항목별 확인
404	경로 또는 모델 이름 없음	`/v1/messages`와 모델 ID 확인
5xx	업스트림 일시 장애	제한된 횟수로 재시도, 계속 실패하면 대체 진입점으로 전환

문제를 해결할 때는 먼저 request-id 응답 헤더를 보존하세요. 401은 잔액을 의심하기 전에 인증 헤더와 키 자체를 확인하고, 429는 반드시 "돈이 없다"는 뜻이 아니라 속도 제한일 수 있습니다. 400은 대부분 요청 본문 문제이며 오류 메시지가 보통 구체적인 필드를 알려 줍니다.

8. 키 보안과 호환 게이트웨이 대체 진입점

키 보안은 최소 네 가지를 지켜야 합니다. 환경 변수나 비밀 관리 서비스에만 저장하고, 프로젝트별로 키를 나누고, 사용량 경고를 설정하고, 퇴사한 멤버의 키를 정기적으로 교체·폐기합니다. 프런트엔드, 모바일 앱, 공개 저장소에는 장기 키를 둘 수 없습니다.

중국 내 팀이 네트워크, 결제, 인보이스 문제를 겪는다면 Anthropic 호환 엔드포인트를 제공하는 게이트웨이로 공식 주소를 대체할 수 있습니다. 공식 SDK는 보통 base_url과 키만 바꾸면 됩니다.

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

resp = client.messages.create(
    model="사이트 내 모델 목록 기준",
    max_tokens=256,
    messages=[{"role": "user", "content": "OK라고만 답하세요"}],
)
print(resp.content)

게이트웨이가 OpenAI 호환 인터페이스만 제공한다면 base URL만 바꿔서는 안 되고 요청 구조를 바꾸거나 어댑터 계층을 추가해야 합니다. 게이트웨이를 고를 때는 세 가지를 확인하세요. Anthropic 원시 프로토콜 지원 여부, 모델 이름 매핑 방식, 속도 제한과 로그 정책의 투명성입니다.

9. 자주 묻는 질문

Claude API와 Claude 웹 버전 멤버십은 같은 것인가요?

아닙니다. 웹 버전은 사용자용 제품 구독이고 API는 사용량 기반 과금입니다. 계정 체계, 할당량, 관리 진입점이 다릅니다. API의 키, 청구, 사용량은 Anthropic Console에서 관리합니다.

API 키를 만든 뒤에도 전체 값을 볼 수 있나요?

대부분의 경우 생성 시 한 번만 표시됩니다. 이후에는 접두사나 이름만 볼 수 있으므로 만든 즉시 비밀 관리 서비스에 저장해야 합니다. 잃어버렸다면 기존 키를 폐기하고 새로 만드세요.

max_tokens를 반드시 전달해야 하는 이유는 무엇인가요?

Messages API는 한 번의 출력 상한을 명시적으로 선언하도록 요구해 생성 길이와 자원을 제어합니다. 생략하면 400이 반환됩니다. 작업에 맞는 합리적인 값을 설정하고 무작정 최대로 올리지 마세요.

429는 할당량 소진인가요, 동시성 초과인가요?

둘 다 가능합니다. 먼저 응답 본문과 retry-after를 보세요. 짧은 시간에 집중되면 속도나 동시성 문제인 경우가 많고, 지속적으로 발생하면서 청구 할당량이 이상하면 플랜과 사용량을 확인합니다. 대응은 백오프 재시도, 동시성 축소, 키 분리 등입니다.

중국 내 팀은 반드시 게이트웨이를 써야 하나요?

아닙니다. 안정적으로 직접 연결할 수 있고 결제와 규정 준수 평가를 마친 팀이라면 공식 직접 연결이 더 단순합니다. 위안화 결제, 인보이스, 통합 멀티모델 진입점, 네트워크 최적화가 필요할 때 게이트웨이를 평가하고 데이터 및 장애 처리 정책을 확인하세요.

다음 단계

먼저 ZSQH AI 게이트웨이에 가입하고 테스트 키로 /v1/messages 최소 요청을 실행한 뒤 업무에 연동하세요. 모델, 컨텍스트, 과금은 모델 가격을 기준으로 합니다.