Claude 구독 크레딧으로 API를 쓰는 법

Claude Max와 Team 구독에는 매달 API 크레딧이 붙습니다. 그런데 이 크레딧을 내 코드에서 쓸 수 있는지는 경로에 따라 답이 달라집니다. 같은 모델을 호출해도 어떤 경로로 호출하느냐에 따라 크레딧이 차감되기도 하고, 구독의 사용 한도에서 빠지기도 합니다.

이 글은 그 경계를 어떤 원리로 나누는지 설명하고, 연결과 호출 절차를 단계별로 보여 줍니다. 명령과 응답은 2026-10-22에 실제로 실행한 결과이고, 요금과 정책 조건은 2026-10-23 기준 공식 문서를 따랐습니다. 조건은 Anthropic이 바꿀 수 있으므로 쓰기 전에 원문을 다시 보는 것이 맞습니다.

§10. 이 글의 용어: API, ant CLI, Managed Agents

이 글에는 세 가지 용어가 나옵니다. 먼저 뜻을 정리합니다.

• API (Application Programming Interface): 프로그램이 Claude에 요청을 보내고 응답을 받는 HTTP 인터페이스입니다. https://api.anthropic.com/v1/messages에 모델 이름과 메시지를 JSON으로 보내면 JSON 응답이 옵니다. 이 글의 호출은 모두 API 호출입니다. 사람이 claude.ai에서 채팅하거나 Claude Code를 쓰는 것과 달리, API는 API 키로 인증하고 사용한 토큰 수에 따라 과금됩니다.
• ant CLI: Anthropic이 만든 공식 명령줄 도구입니다. 같은 API를 터미널 명령 한 줄로 호출하게 해 주고, --transform 옵션으로 응답에서 필요한 값만 꺼낼 수 있습니다. curl로 직접 요청을 만드는 대신 쓰는 편의 도구이며, 과금 방식은 API와 같습니다.
• Managed Agents: Anthropic이 관리하는 클라우드 샌드박스에서 에이전트를 실행하는 API 기능입니다. 에이전트, 환경, 세션, 이벤트로 구성되며, 도구 실행과 파일 작업이 Anthropic 쪽에서 일어납니다. 베타 기능이고, 이 글에서 다루는 범위에서는 크레딧이 적용됩니다. 실제로 한 번 실행해 본 기록은 Managed Agents 첫 세션 기록에서 다룹니다.

세 가지 가운데 Managed Agents만 실행 위치가 다릅니다. API와 ant CLI는 내가 요청을 보내면 응답이 돌아오는 구조이고, Managed Agents는 세션을 열어 두면 Anthropic 샌드박스에서 작업이 이어집니다.

§21. 과금 체계의 기본 구조

Claude 구독과 API는 과금 체계가 다른 별개의 장부입니다.

• 구독 사용 한도: Claude 앱과 Claude Code에서 쓰는 사용량 한도입니다. 플랜 요금에 포함되어 있고, 한도를 넘으면 기다리거나 추가 사용량을 구매합니다.
• API 과금: 호출한 토큰 수에 모델별 단가를 곱해 청구합니다. 과금 단위는 조직(Organization)입니다. 조직 안의 모든 API 키와 워크스페이스가 같은 잔액을 씁니다.

크레딧은 이 두 장부 사이를 잇는 장치입니다. 구독자가 받은 월 금액을 조직의 API 잔액에 넣어 주고, 그 잔액은 API 호출에서만 줄어듭니다. 그래서 "크레딧이 적용된다"는 말은 "이 호출이 API 장부에 기록된다"는 뜻으로 읽어야 합니다. 구독 장부에 기록되는 호출에는 크레딧이 적용되지 않습니다.

Anthropic 약관은 이 크레딧을 무상으로 제공되는 Promotional Credits로 분류합니다. 따라서 프로그램 자체가 나중에 바뀌거나 끝날 수 있습니다.

§32. 무엇이 적용되고 무엇이 적용되지 않나

판정 기준은 "호출이 어느 장부에 기록되느냐"입니다. 공식 문서 기준 목록은 다음과 같습니다.

claude -p는 목록에서 가장 헷갈리는 경우입니다. 같은 명령이라도 인증 수단에 따라 장부가 달라집니다. 연결된 조직의 API 키로 실행하면 Agent SDK 사용으로 과금되어 크레딧이 적용됩니다. Claude 플랜으로 로그인한 채 실행하면 구독 사용 한도에서 빠집니다. GitHub Action, IDE 확장, 데스크톱 앱에서 시작한 실행은 -p를 써도 Claude Code 사용으로 분류되어 크레딧이 적용되지 않습니다.

실무에서는 이렇게 정리하면 됩니다. 프로그램 코드에서 API 키로 호출하면 크레딧 대상이고, 사람이 대화형으로 쓰는 도구는 구독 대상입니다.

§43. 금액 체계

Team은 모든 시트의 크레딧을 합쳐 하나의 잔액으로 만들고, 월 합산 상한을 $500으로 둡니다. 금액은 결제 월이 시작될 때의 시트 수로 정해집니다. 계산 예를 들면, Standard 3석과 Premium 2석이면 3 × $20 + 2 × $100=100\; =$260입니다. 이 달에 Premium 1석을 더하면 다음 달부터 $360이 됩니다. 한 달 중간에 늘린 좌석은 다음 결제 월부터 반영됩니다.

API 사용량의 상한은 크레딧 금액과 별개입니다. 조직에는 사용 등급(tier)이 있고, 등급마다 월 지출 상한이 다릅니다. 문서 기준으로 Start는 $500,Build\text{는}500,\; Build는$1,000, Scale은 $200,000입니다. 연결된 조직은 최소 Start이고, 월 크레딧이 $200을 넘으면 최소 Build가 됩니다. 등급은 사용 실적에 따라 올라가며, 더 높은 상한이 필요하면 콘솔의 Rate limits 페이지에서 요청합니다.

§54. 연결 절차와 전제 조건

연결은 구독 설정과 Console 조직을 잇는 작업입니다.

1. claude.ai에서 결제 설정을 엽니다. Max는 Settings > Billing, Team은 Organization settings > Billing입니다.
2. API credits 섹션에서 크레딧을 받을 Console 조직을 고르고 Link organization을 누릅니다. 이때 Supplemental Credit Terms에 동의하게 됩니다.

연결을 마치면 같은 결제 화면의 API 크레딧 칸에 연결된 조직과 연결 날짜, 월간 크레딧, 다음 지급일이 나옵니다. 아래는 2026-10-27에 본 Max 계정의 한국어 화면이고, 조직 이름은 가렸습니다.

전제 조건에는 이유가 있습니다. 대상 플랜이 활성 상태여야 하고, 새로 가입했다면 7일이 지나야 합니다. 연결하는 사람은 Max에서는 구독자 본인, Team에서는 Primary Owner 또는 Owner여야 합니다. Console 조직에서도 Owner, Admin, Billing 중 하나의 역할이 필요합니다. 크레딧은 조직 하나에만 들어가므로, 여러 조직에 나눠 받을 수는 없습니다.

연결 뒤에는 Console의 Billing 화면에서 Promotional credits 표에 남은 금액, 적용 대상, 만료 시각, 지급일이 나오는 것을 확인할 수 있습니다.

아래 화면의 적용 대상 칸에는 Agent SDK, API, 배치 API, Playground, 관리형 에이전트가 나옵니다. 2절 표에서 "적용"으로 적은 제품과 같습니다. 2026-10-22에 부여된 크레딧의 만료일은 2026-11-25로 적혀 있습니다.

§65. 키가 어느 조직 것인지 확인하기

연결한 조직의 키로 호출해야 크레딧이 그 조직 장부에 기록됩니다. 키 하나가 어느 조직 소속인지는 응답 헤더로 확인할 수 있습니다. 모델 목록 호출은 토큰을 소비하지 않으므로 확인용으로 적합합니다.

( source ~/.secrets/anthropic.env \
  && printf 'x-api-key: %s\nanthropic-version: 2023-06-01\n' "$ANTHROPIC_API_KEY" \
  | curl -s -o /dev/null -D - -H @- 'https://api.anthropic.com/v1/models?limit=1' \
  | grep -i -E '^HTTP|^anthropic-organization-id' )

응답의 HTTP/2 200은 키가 유효하다는 뜻이고, anthropic-organization-id는 키가 속한 조직 ID입니다. 이 값을 Console의 Organization ID와 비교합니다. 같으면 연결한 조직의 키입니다.

Console의 Organization ID는 설정 > 조직 화면 아래쪽에 있습니다. 아래 화면에서는 조직 이름, 주소, 조직 ID 값을 가렸습니다.

§76. 키 취급의 원리

키를 다루는 방식은 과금 경로와 직접 연결됩니다. 셸 전역에 ANTHROPIC_API_KEY를 export하면 그 셸에서 실행되는 Claude Code도 키를 볼 수 있고, 키가 있으면 구독 대신 API 키로 인증할 수 있습니다. 그러면 대화형 사용분이 API 장부에 기록됩니다. 의도하지 않은 과금이 생기는 원인이 이것입니다.

그래서 이 글의 명령은 모두 서브셸 ( … ) 안에서만 키를 불러옵니다. 키 값은 명령 인자로 넘기지 않고, curl에는 -H @-로 표준입력에서 헤더를 읽게 합니다. 명령 인자는 ps 같은 도구로 다른 사용자에게도 보일 수 있기 때문입니다.

§87. 최소 호출과 응답 읽기

메시지 API는 POST /v1/messages에 모델, 최대 토큰 수, 메시지 배열을 보내는 방식입니다.

( source ~/.secrets/anthropic.env \
  && printf 'x-api-key: %s\n' "$ANTHROPIC_API_KEY" \
  | curl -s https://api.anthropic.com/v1/messages -H @- \
      -H 'anthropic-version: 2023-06-01' -H 'content-type: application/json' \
      -d '{"model":"claude-haiku-5-5","max_tokens":1024,"messages":[{"role":"user","content":"안녕"}]}' \
  | jq -r '.content[] | select(.type=="text") | .text' )

이 명령의 결과는 "안녕하세요! 무엇을 도와드릴까요" 한 줄이었습니다. 응답 JSON의 content는 블록의 배열이고, 텍스트 블록은 type이 text입니다. 그래서 select(.type=="text")로 텍스트 블록만 고릅니다. 도구를 쓰는 응답에는 다른 type의 블록이 함께 올 수 있습니다.

anthropic-version 헤더는 API 버전을 고정합니다. 이 값이 없으면 호출이 실패하거나 응답 형식이 예상과 달라질 수 있습니다.

§98. 같은 호출을 SDK와 CLI로 하기

Python SDK는 같은 요청을 객체 호출로 감쌉니다. 클라이언트는 환경변수 ANTHROPIC_API_KEY를 읽으므로, 코드에 키를 적을 필요가 없습니다.

# app.py
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 환경변수를 읽는다

message = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕"}],
)
print(next(b.text for b in message.content if b.type == "text"))

( source ~/.secrets/anthropic.env && export ANTHROPIC_API_KEY \
  && uv run --no-project --with anthropic python app.py )

export는 이 서브셸 안에서만 쓰입니다. 키가 셸 전역으로 새지 않습니다. 이 방식은 2026-10-22에 실행해 같은 응답을 받았습니다.

ant CLI는 Anthropic이 만든 명령줄 도구입니다. macOS에서는 Homebrew로 설치합니다.

brew install anthropics/tap/ant

( source ~/.secrets/anthropic.env && export ANTHROPIC_API_KEY \
  && ant messages create --model claude-haiku-5-5 --max-tokens 1024 \
       --message '{role: user, content: "안녕"}' \
       --transform 'content.#(type=="text").text' -r )

--transform은 응답 JSON에서 필요한 값만 꺼내는 옵션입니다. 같은 요청을 셸 스크립트에서 편하게 쓰고 싶을 때 적합합니다. 이 명령도 2026-10-22에 ant 2.1.0으로 실행해 같은 응답을 확인했습니다.

§109. Batch API: 비동기로 싸게 보내기

Message Batches API는 여러 요청을 한 번에 제출하고, 결과를 나중에 받는 방식입니다. 실시간 응답이 필요 없는 대량 작업에 맞습니다. 요청 하나의 단가는 일반 호출의 50%이고, 크레딧도 그대로 적용됩니다.

배치의 제약은 세 가지입니다. 한 배치에 요청 10만 건 또는 256MB까지 담을 수 있습니다. 결과는 모든 요청이 끝나거나 24시간이 지나면 받을 수 있습니다. 24시간 안에 끝나지 않은 요청은 만료되고 과금되지 않습니다.

요청마다 custom_id를 붙여야 합니다. 결과는 요청 순서대로 오지 않을 수 있으므로, 결과를 원래 요청과 맞추는 열쇠가 custom_id입니다. 실행해 보니 같은 요청을 두 번 돌렸을 때 결과 줄의 순서가 서로 달랐습니다.

# 1) 배치 만들기: 응답의 id(msgbatch_...)를 받는다
BATCH_ID=$( ( source ~/.secrets/anthropic.env \
  && printf 'x-api-key: %s\nanthropic-version: 2023-06-01\ncontent-type: application/json\n' "$ANTHROPIC_API_KEY" \
  | curl -s -X POST https://api.anthropic.com/v1/messages/batches -H @- \
      -d '{"requests":[
            {"custom_id":"q1","params":{"model":"claude-haiku-5-5","max_tokens":64,"messages":[{"role":"user","content":"1+1은? 숫자만 답해."}]}},
            {"custom_id":"q2","params":{"model":"claude-haiku-5-5","max_tokens":64,"messages":[{"role":"user","content":"한국의 수도는? 한 단어로 답해."}]}}
          ]}' ) | jq -r .id )

# 2) 끝났는지 확인: processing_status가 ended가 될 때까지 기다린다
for i in $(seq 1 40); do
  ST=$( ( source ~/.secrets/anthropic.env \
    && printf 'x-api-key: %s\nanthropic-version: 2023-06-01\n' "$ANTHROPIC_API_KEY" \
    | curl -s "https://api.anthropic.com/v1/messages/batches/$BATCH_ID" -H @- | jq -r .processing_status ) )
  [ "$ST" = ended ] && break
  sleep 10
done

# 3) 결과 받기: 한 줄이 요청 하나다. 텍스트만 뽑고, 실패한 요청은 result.type을 출력한다
( source ~/.secrets/anthropic.env \
  && printf 'x-api-key: %s\nanthropic-version: 2023-06-01\n' "$ANTHROPIC_API_KEY" \
  | curl -s "https://api.anthropic.com/v1/messages/batches/$BATCH_ID/results" -H @- \
  | jq -r '"\(.custom_id)\t\(.result.message.content[0].text // .result.type)"' )

이 절차를 2026-10-22에 실행했습니다. 배치 한 건은 약 2분 만에 끝났고, 결과는 q1 2, q2 서울이었습니다. 토큰은 입력 22, 출력 3이었습니다. Haiku 5.5의 배치 단가(입력 $0.05,\text{출력}0.05,\; 출력$0.25, 100만 토큰당)로 계산하면 22 × 0.05 + 3 × 0.25를 100만으로 나눈 약 $0.0000019입니다. 실제 청구 차감은 Console에서 따로 확인하지 않았습니다.

§1110. 차감, 소진, 지출 상한

차감 순서는 무상 크레딧이 먼저이고, 그다음 구매한 크레딧입니다. 자동 충전은 구매 잔액만 기준으로 판단합니다. 그래서 무상 크레딧이 아직 남아 있어도 구매 잔액이 기준 아래로 내려가면 충전이 일어날 수 있습니다.

크레딧이 바닥나면 API 요청은 다음 지급일까지 멈춥니다. 이때 요금은 구독에 청구되지 않습니다. 요청은 오류로 돌아옵니다. 즉 크레딧 잔액은 구독 한도와 독립적으로 작동하는 안전장치입니다.

지출 상한은 달력 기준입니다. 매월 1일 UTC 0시에 초기화됩니다. 크레딧은 결제 주기에 맞춰 지급되므로, 두 주기가 어긋날 수 있다는 점을 알아 두어야 합니다.

Console의 지출 한도 화면에서 이번 달 사용액, 초기화 날짜, 월별 지출 한도를 확인할 수 있습니다. 아래 화면의 조직은 Build 등급이고(속도 제한 화면 기준), 월별 한도는 3절에 적은 Build 상한과 같은 US$1,000입니다. 지출 한도는 2026년 11월 1일(UTC)에 초기화되지만, 다음 크레딧은 4절의 claude.ai 화면 기준으로 11월 24일에 들어옵니다.

§1211. 플랜을 바꿀 때

§1312. 비용을 구조로 이해하기

토큰 단가는 입력과 출력이 다르고, 캐시에 따라 입력 단가가 달라집니다. 2026-10-23 기준 공식 단가(100만 토큰당)는 다음과 같습니다.

반복되는 긴 맥락은 프롬프트 캐싱으로 보내면 싸집니다. 캐시 읽기는 기본 입력 단가의 0.1배이지만, Opus 5.5와 Sonnet 5.5는 0.05배입니다. 캐시 쓰기는 5분 캐시에서 1.25배, 1시간 캐시에서 2배입니다. 100만 토큰당 캐시 읽기 단가로 바꾸면 Opus 5.5는 $0.20,Sonnet5.5\text{는}0.20,\; Sonnet\; 5.5는$0.10, Haiku 5.5는 $0.01입니다.

작업의 성격에 따라 모델을 고르는 것이 가장 큰 차이를 만듭니다. 같은 입력이라도 Haiku와 Opus는 단가가 40배 차이 납니다.

§14참고 자료

• API credits for Max and Team plans, Claude Platform Docs^[1]
• Monthly API credits for Max and Team plans, Claude Help Center^[2]
• Supplemental Credit Terms, Anthropic^[3]
• Rate limits and spend limits, Claude Platform Docs^[4]
• Pricing, Claude Platform Docs^[5]
• Batch processing, Claude Platform Docs^[6]