클라이언트/Claude Desktop

Claude Desktop에서 Wokey API 사용하기

Wokey API 키를 발급받고 Claude Desktop의 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 Desktop은 최신 앱이 필요하며, 개발자 모드에서 서드파티 추론을 설정합니다. 왼쪽 단계를 따르세요.

  1. 1

    최신 Claude Desktop 설치

    먼저 최신 버전으로 업데이트하세요. 이전 버전에는 Developer mode나 서드파티 추론 설정이 없을 수 있습니다.

  2. 2

    로그인하지 않고 앱 열기

    Claude Desktop을 실행하고 초기 설정 동안 로그아웃 상태를 유지하세요.

  3. 3

    Developer mode 켜기

    오른쪽 위 메뉴를 열고 Help → Troubleshooting → Enable developer mode를 선택하세요.

  4. 4

    서드파티 추론 설정 열기

    Developer mode를 켠 뒤 Claude 메뉴를 열고 Developer → Configure third-party inference를 선택하세요.

  5. 5

    Wokey 연결 정보 입력

    Connection을 Gateway로, Credential kind를 Static API key로 설정하세요. Wokey Base URL과 Wokey API 키를 입력하세요.

  6. 6

    적용 후 재시작

    Apply Changes를 클릭한 다음 Save & Restart를 클릭하세요. 재시작 후에는 Anthropic 계정에 로그인하지 않은 채로 Claude Desktop을 사용하세요. 로그인하면 요청이 Anthropic으로 전송됩니다.

Claude Desktop
Connection: Gateway
Credential kind: Static API key
URL: https://api.wokey.ai
API key: YOUR_API_KEY

Apply: Apply Changes → Save & Restart

API 형식과 Base URLlink

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

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

설정 위치: 메뉴 Developer → Configure third-party inference

curl로 확인link

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

Claude Desktop는 기본적으로 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 Desktop의 URL은 /v1로 끝나야 하나요?
아니요. Connection으로 Gateway를 선택하고 URL을 https://api.wokey.ai로 설정한 뒤, Credential kind로 Static API key를 선택하고 Wokey API 키를 입력하세요.
Configure third-party inference가 보이지 않으면 어떻게 하나요?
Claude Desktop을 최신 버전으로 업데이트한 뒤 Help → Troubleshooting → Enable developer mode를 여세요. Configure third-party inference는 개발자 모드를 켠 후에만 Developer 메뉴에 나타납니다.
설정 후에도 Anthropic 계정에 로그인해야 하나요?
아니요. Apply Changes와 Save & Restart 후 로그인하지 않고 바로 앱을 사용하세요. Anthropic 계정에 로그인하면 요청이 Wokey가 아닌 Anthropic으로 전송됩니다.

설정 및 오류 가이드link