Claude Code API 이해하기

Claude Code는 터미널 에이전트이지만, 내부적으로 모든 작업은 직접 사용할 수 있는 동일한 Anthropic Messages API에 대한 호출입니다. 따라서 연결할 엔드포인트와 과금에 사용할 키, 나아가 세션 비용을 직접 제어할 수 있다는 유용한 이점이 있습니다. 이 페이지에서는 구성 요소를 설명하고 자세한 설정 가이드를 안내합니다.

“Claude Code API”의 실제 의미

Claude Code API라는 별도의 제품은 없습니다. Claude Code는 Claude 구독(Pro/Max) 또는 API 키로 인증하며, API 모드에서는 환경 설정이 가리키는 엔드포인트로 시스템 프롬프트, 대화, 도구 정의 및 도구 결과가 포함된 표준 Messages API 요청을 보냅니다.

이 엔드포인트는 설정할 수 있습니다. 두 환경 변수로 모든 것을 제어합니다. ANTHROPIC_BASE_URL는 요청을 보낼 위치를, ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY는 비용을 부담할 계정을 지정합니다. Anthropic에 직접 연결하거나 Anthropic 호환 게이트웨이에 연결해도 Claude Code는 동일하게 작동합니다.

Claude Code에서 자체 API 키 사용하기

셸 프로필 또는 ~/.claude/settings.json에 두 변수를 설정한 후 평소처럼 claude를 실행하세요. settings.json 예시를 포함한 전체 절차는 <a href="/ko/learn/claude-code-api-key-setup/">Claude Code API 키 설정 가이드</a>에서 확인할 수 있습니다.

알아두어야 할 주의점이 있습니다. 셸에 ANTHROPIC_API_KEY가 설정되어 있으면 구독이 있어도 Claude Code에 API 요금이 적용됩니다. 환경 변수가 우선하기 때문입니다. Pro/Max 요금제를 사용하려면 해당 변수의 설정을 해제하세요.

Claude Code 세션 비용

에이전트 세션은 많은 토큰을 사용합니다. 읽은 모든 파일, 도구 결과 및 diff가 컨텍스트에 포함됩니다. 집중적으로 작업하는 한 시간 동안 수백만 개의 입력 토큰을 소비할 수 있으므로 프롬프트 캐싱이 매우 중요합니다. 이를 지원하는 엔드포인트에서는 반복되는 컨텍스트를 훨씬 저렴한 비용으로 캐시에서 다시 읽습니다.

<a href="/ko/learn/claude-code-api-costs/">Claude Code API 비용 가이드</a>에서는 실제 세션별 수치, 캐시 동작 및 긴 세션의 비용을 합리적으로 유지하는 방법을 자세히 설명합니다.

Anthropic 직접 연결과 게이트웨이 비교

Anthropic API에 직접 연결하면 사용량 기반 과금과 공식 지원을 받을 수 있으므로, 안정적인 예산을 갖춘 팀에 적합한 기본 선택입니다. AI Prime Tech와 같은 독립 게이트웨이(Anthropic과 제휴 관계가 없으며 Anthropic의 보증을 받지 않음)는 정액 또는 할인 요금으로 접근 권한을 재판매하고 동일한 통신 형식을 제공하므로, 기본 URL과 키만 변경하면 Claude Code를 사용할 수 있습니다.

어떤 방식을 선택하든 스트리밍이 처음부터 끝까지 정상적으로 작동하는지, 필요한 모델을 Claude Code가 요청하는 정확한 ID로 사용할 수 있는지 확인하세요. 전체 체크리스트는 <a href="/ko/learn/use-claude-api-with-claude-code/">Claude Code에서 Claude API 사용하기</a>를 참조하세요.

# Claude Code with your own key + custom endpoint
export ANTHROPIC_BASE_URL="https://aiprimetech.io"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
claude

# or persist in ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aiprimetech.io",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  }
}

자주 묻는 질문

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.