클라이언트/Claude Code

Claude Code에서 Wokey API 사용하기

Wokey API 키를 발급받고 Claude Code의 Base URL을 Wokey로 지정한 뒤 curl 요청 한 번으로 연결을 확인하세요.

업데이트

이 페이지 내용expand_more

API 키와 Base URL 준비link

모든 클라이언트는 같은 Wokey API 키와 같은 Base URL을 사용합니다.

API 키 만들기

로그인한 뒤 API 페이지에서 플랫폼 키를 만드세요. 같은 계정의 키는 잔액을 공유합니다.

API 키 만들기key

Wokey Base URL 사용

클라이언트의 Base URL에 게이트웨이 도메인을 입력하세요. /v1을 붙일지는 아래 설정을 참고하세요.

클라이언트 설정link

Claude Code는 Anthropic 호환 환경 변수를 사용하며, ANTHROPIC_AUTH_TOKEN을 Authorization Bearer 토큰으로 보냅니다.

Claude Code
export ANTHROPIC_BASE_URL="https://api.wokey.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
claude

API 형식과 Base URLlink

같은 클라이언트라도 API 형식을 바꾸면 Base URL 끝에 /v1을 붙일지가 달라질 수 있습니다.

형식Base URL용도
Anthropic Messageshttps://api.wokey.aiClaude 모델

설정 위치: 환경 변수 또는 ~/.claude/settings.json의 env

curl로 확인link

클라이언트에서 오류가 나면 먼저 curl로 API 키와 Base URL 문제가 아닌지 확인하세요.

Claude Code는 기본적으로 Anthropic Messages 형식을 사용합니다. 이 요청이 200을 반환하면 API 키와 Base URL이 올바른 것입니다. 보내기 전에 YOUR_API_KEY를 내 키로 바꾸세요.

cURL
curl https://api.wokey.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

오류 및 문제 해결link

먼저 인증, 잔액, 속도 제한, 모델 사용 가능 여부, 업스트림 타임아웃 중 어느 경우인지 구분하세요.

401

invalid api key

키가 없거나, 잘못 입력되었거나, 삭제되었거나, Authorization과 x-api-key 헤더가 서로 다릅니다.

402

insufficient balance

계정 잔액이 부족합니다. 요청을 더 보내기 전에 충전하세요.

403

model_denylisted / account_restricted

반복된 위반으로 해당 모델 또는 계정의 모든 모델에 대한 호출이 일시 중지되었습니다. 위반 처리 수수료 및 제한을 참고하세요.

403

request_blocked

이 요청은 업스트림에 도달하기 전에 차단되었으며 과금되지 않습니다. 예를 들어 모델이 방금 거부한 요청을 그대로 다시 보냈거나, 일시 중지된 최종 사용자(X-End-User-Id)인 경우입니다. 오류 메시지에 무엇이 차단되었는지 나와 있으니 안내에 따라 요청을 수정하거나 나중에 다시 시도하세요. 다른 요청에는 영향이 없습니다.

429

rate limited

요청이 너무 잦습니다. 나중에 다시 시도하거나 동시 실행 수를 줄이세요. 특정 모델 하나 또는 특정 최종 사용자(X-End-User-Id) 하나만 계속 429를 반환한다면 위반 후의 일시적인 제한일 수 있습니다.

499

client disconnected

응답이 끝나기 전에 클라이언트가 연결을 닫았습니다(코드 downstream_aborted). 기본적으로 무료입니다. 계정에서 지난 24시간 동안 클라이언트 연결 끊김이 50회 이상 발생하고 그것이 요청의 10% 이상을 차지하면, 이후 연결이 끊긴 요청은 업스트림이 보고한 사용량으로 과금됩니다. 대상은 캐시 읽기와 쓰기를 포함한 처리된 입력, 그리고 업스트림이 집계한 경우에만 출력입니다. 업스트림이 사용량을 보고하기 전에 끊긴 경우는 계속 무료입니다. 과금이 시작되면 계정에 알림이 가며, 연결 끊김 비율이 정상으로 돌아오면 1시간 안에 과금이 자동으로 중지됩니다. 흔한 원인은 클라이언트나 프록시의 타임아웃이 너무 짧거나, 프로그램이 완료 전에 요청을 취소하는 경우입니다.

502

upstream unavailable

업스트림 모델 서비스를 일시적으로 사용할 수 없습니다. 모델을 바꾸거나 나중에 다시 시도하세요.

504

upstream timeout

업스트림 응답 시간이 초과되었습니다. 컨텍스트를 줄이거나 max_tokens를 낮추거나 다시 시도하세요.

529

upstream overloaded

업스트림 모델이 일시적으로 과부하 상태이며, Wokey는 이미 다른 경로로 재시도했습니다(코드 upstream_overloaded). 잔액과는 관계가 없습니다. 잠시 후 다시 시도하거나 모델을 바꾸세요.

자주 묻는 질문link

Claude Code의 ANTHROPIC_BASE_URL은 /v1로 끝나야 하나요?
아니요. https://api.wokey.ai를 사용하세요. Claude Code가 /v1/messages를 직접 붙이므로 /v1로 끝나는 base URL은 /v1/v1/messages가 되어 404를 반환합니다.
ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY 중 무엇을 쓰나요?
ANTHROPIC_AUTH_TOKEN을 사용하세요. Claude Code는 이를 Authorization: Bearer로 보냅니다. 예전 ANTHROPIC_API_KEY가 아직 설정되어 있다면 먼저 unset하세요. 서로 다른 두 헤더가 있으면 401이 반환됩니다.
새 터미널에서도 설정을 유지하려면 어떻게 하나요?
두 줄의 export를 ~/.zshrc 또는 ~/.bashrc에 넣거나, Claude Code가 시작할 때마다 읽는 ~/.claude/settings.json의 env 필드에 추가하세요.

설정 및 오류 가이드link