AI 코딩

Claude API 첫 요청: 키 생성부터 사용량 확인까지

BetterToken API Key를 만들고 Anthropic-compatible endpoint로 첫 요청을 보낸 뒤 응답, 토큰 사용량, 비용을 Workspace에서 확인하는 가이드입니다.

BT

BetterToken

편집팀
3 분 분량

이 가이드는 이미 발급한 API Key에서 시작해 Claude-compatible 요청 한 건을 보내고, 응답과 사용량 기록까지 검증하는 과정을 다룹니다. 아직 어떤 액세스·결제 경로를 선택할지 비교 중이라면 먼저 Claude API 개요를 확인하세요. 여기서는 기술적인 첫 요청에만 집중합니다.

필요한 것은 세 가지입니다. 본인 소유의 API Key, 올바른 Base URL, 그리고 현재 사용 가능한 Model ID입니다. BetterToken의 API Key로 Anthropic Messages 형식에 맞춘 endpoint를 호출할 수 있지만, 이 키가 Anthropic 공식 API Key로 바뀌는 것은 아닙니다. 이 경계를 알고 시작하면 인증 오류와 잘못된 검증을 피할 수 있습니다.

1. BetterToken API Key 만들기

  1. BetterToken Workspace에 로그인합니다.
  2. 현재 안내된 Claude-compatible key group에 사용할 새 API Key를 만듭니다.
  3. 키를 한 번만 복사해 비밀 관리 도구나 Git에서 제외된 로컬 환경 변수에 저장합니다.
  4. 현재 API 문서와 가격 페이지에서 사용할 수 있는 Model ID와 제공 여부를 확인합니다.

키를 코드, 프롬프트, 스크린샷, 지원 문의 또는 공개 저장소에 붙여 넣지 마세요. 팀에서는 각자 자신의 계정과 키를 사용해야 합니다. Anthropic Console의 키나 공유된 Claude.ai 로그인 정보도 사용하지 마세요.

2. Anthropic-compatible endpoint 확인하기

이 흐름에서 사용하는 BetterToken Base URL은 다음과 같습니다.

https://bettertoken.ai/

raw HTTP 요청의 전체 경로는 다음과 같습니다.

POST https://www.bettertoken.ai/v1/messages

Base URL에 /v1을 덧붙이지 마세요. SDK는 리소스 경로를 이어 붙일 수 있지만, 아래의 raw curl 예제에는 전체 /v1/messages 경로가 필요합니다.

3. 최소 요청 보내기

아래 명령은 키, Base URL, Model ID를 환경 변수로 분리합니다. 실제 값을 명령 기록에 직접 입력하는 것보다 안전합니다.

export ANTHROPIC_API_KEY="your_api_key"
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_MODEL_ID="YOUR_MODEL_ID"

curl --fail-with-body "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{
    \"model\": \"$CLAUDE_MODEL_ID\",
    \"max_tokens\": 64,
    \"messages\": [{\"role\": \"user\", \"content\": \"Return only the word pong.\"}]
  }"

your_api_key와 YOUR_MODEL_ID는 로컬에서만 바꾸세요. 이 글은 특정 모델 이름을 고정하지 않습니다. 정확한 Model ID와 제공 여부는 바뀔 수 있으므로 항상 현재 문서나 가격 페이지에서 복사해야 합니다.

4. 응답과 사용량 확인하기

성공하면 HTTP 200과 JSON 메시지가 반환됩니다. 최소한 다음 항목을 확인하세요.

  • type이 message인지
  • content에 모델의 답변이 있는지
  • usage에 input_tokens와 output_tokens가 있는지

응답 구조는 Anthropic Messages API 참고 문서의 형식을 따릅니다. 이 형식 호환성이 BetterToken의 키를 Anthropic 키로 만들지는 않습니다.

이제 Workspace를 새로고침하고 요청 시각을 맞춰 보세요. 해당 기록에서 다음을 확인합니다.

  • 요청에 사용된 모델
  • 성공 또는 오류 상태
  • 해당하는 경우 입력·출력·캐시 토큰
  • 청구된 비용

Workspace에 전체 프롬프트나 전체 응답 본문이 저장된다고 가정하지 마세요. 라우팅과 사용량은 상태 및 사용량 필드로 검증하면 됩니다.

5. 일반적인 오류 해결하기

404 Not Found

raw HTTP 요청에 전체 /v1/messages 경로가 들어갔는지 확인하세요. /messages만 사용하면 경로가 불완전합니다.

400 Bad Request

다음 필드를 확인하세요.

  • anthropic-version: 2023-06-01
  • content-type: application/json
  • 현재 유효한 Model ID
  • 양의 정수인 max_tokens
  • 하나 이상의 유효한 user 메시지가 포함된 messages 배열

401 또는 403

다음을 확인하세요.

  • 키가 BetterToken에서 발급되었는지
  • 선택한 key group에서 요청한 모델을 사용할 수 있는지
  • Base URL이 정확히 https://bettertoken.ai인지
  • 복사한 키 앞뒤에 공백이 없는지

실제 키를 지원 문의에 보내지 마세요. 오류 코드, 요청 시각, 비밀 정보가 제거된 헤더 이름만 공유하면 됩니다.

429 Too Many Requests

응답 본문을 먼저 읽으세요. 그다음 지연 시간을 둔 뒤 단일 요청을 다시 시도하고, 동시 요청 수와 현재 계정 한도를 확인하세요.

Workspace에 기록이 없음

요청이 BetterToken Base URL로 전송되었는지 확인하세요. 다른 provider의 환경 변수가 현재 셸이나 앱에서 여전히 적용되고 있을 수 있습니다.

테스트가 끝나면 다음과 같이 셸 변수를 지울 수 있습니다.

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

그런 다음 현재 값을 다시 설정하고 요청 한 건만 보내세요. 빠른 재시도 루프는 오류를 더 빨리 반복할 뿐 원인을 더 분명하게 보여 주지 않습니다.

다음 단계

최소 요청이 성공했다면 다음 구현에서는 키를 안전한 비밀 저장소로 옮기고, 유한한 timeout을 설정하며, 일시적인 오류에만 횟수를 제한한 재시도를 적용하세요. BetterToken Docs를 열어 둔 상태에서 새 요청이 Workspace에 기대한 모델·상태·사용량으로 기록되는지 계속 확인하면 됩니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.