AI API 시작 가이드: 프로토콜, API Key, 첫 요청

API 접근, 웹 구독, 공유 계정의 차이

세 가지는 서로 다른 제품입니다.

일반적인 개발에서는 본인이 관리하는 계정과 키를 사용하세요. 구매하거나 공유받은 로그인 정보를 기반으로 연동을 구축하지 마세요.

1. 클라이언트에 맞는 프로토콜 선택하기

모델을 선택하기 전에 클라이언트 또는 SDK 문서를 읽으세요. 도구가 OpenAI SDK, Chat Completions, Responses API 또는 OPENAI_BASE_URL 같은 필드를 요구하면 OpenAI-compatible을 사용합니다. Messages 요청을 만들고 ANTHROPIC_BASE_URL 또는 x-api-key를 요구한다면 Anthropic-compatible을 사용합니다.

모델 이름이 프로토콜을 결정하지는 않습니다. 클라이언트가 엔드포인트에서 받아들이는 것과 동일한 요청 규격을 생성할 수 있어야 합니다.

BetterToken의 Base URL은 다음과 같습니다.

OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

OpenAI-compatible 값에는 이미 /v1이 포함되어 있습니다. Anthropic-compatible 값에는 포함되지 않으며, raw Messages 요청에서는 전체 리소스 경로인 /v1/messages를 사용합니다.

2. Base URL과 request path 구분하기

SDK나 도구에는 보통 Base URL을 입력하며, SDK가 리소스 경로를 뒤에 붙입니다. 직접 HTTP 호출을 할 때는 전체 path가 필요합니다.

OpenAI-compatible raw path:  https://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/v1/messages

Base URL만 요구하는 필드에 전체 요청 경로를 붙여 넣지 마세요. 클라이언트가 resource를 한 번 더 덧붙여 404를 반환할 수 있습니다.

3. API Key를 코드 밖에 보관하기

첫 테스트에는 로컬 환경 변수를 사용하고, 프로덕션 인증 정보는 이후 플랫폼에서 제공하는 비밀 관리 도구로 옮기세요.

export BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

실제 키를 소스 코드, .env.example, 프롬프트, issue, 스크린샷 또는 지원 문의에 넣지 마세요. Model ID를 마케팅 이름에서 추측하지 말고, 제공업체의 현재 문서나 모델 카탈로그에서 정확한 값을 복사하세요.

4. 최소 OpenAI-compatible 요청 보내기

스트리밍이나 도구를 활성화하기 전에 짧은 텍스트 요청부터 보내세요.

curl https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

다른 사람과 공유하는 로그에서는 curl -v를 사용하지 마세요. verbose 출력에 민감한 header가 노출될 수 있습니다.

5. 최소 Anthropic-compatible 요청 보내기

Messages 요청은 인증 헤더와 요청 본문 구조가 다릅니다.

curl https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSION은 placeholder입니다. 테스트 전에 API reference에서 현재 지원되는 헤더 값을 확인하세요. 작업이 특히 Claude-compatible access에 관한 것이라면 최소 요청으로 돌아오기 전에 Claude API 설정과 access boundary를 확인하세요.

6. 응답과 사용량 기록 검증하기

다음 신호가 모두 일치해야 첫 테스트가 완료된 것입니다.

• HTTP status가 성공을 나타냅니다.
• 응답에 예상한 Model ID 또는 문서에 정의된 표시 값이 있습니다.
• 선택한 규격이 예상한 content와 usage 필드를 반환합니다.
• BetterToken Workspace에서 같은 시각의 기록을 찾을 수 있고, 모델, 상태, 해당하는 input/output/cache token과 청구 금액이 표시됩니다.

Workspace는 사용량과 결제 기록을 확인하는 곳입니다. 전체 프롬프트나 응답 본문을 저장한다고 가정하지 마세요. 연동 메모에 동적인 목록을 복사하지 말고, 제공 여부와 가격은 현재 모델 카탈로그에서 확인하세요.

7. 응답 단계별로 문제 해결하기

• 401 또는 403: 선택한 프로토콜에 필요한 키, key group, 공백, Base URL, 인증 헤더를 확인합니다.
• 404: Base URL과 전체 path를 비교합니다. /v1, /chat/completions 또는 /messages가 중복되지 않았는지 확인합니다.
• model not found: 현재의 정확한 Model ID를 복사하고, 선택한 key group과 프로토콜에서 사용할 수 있는지 확인합니다.
• 429: 응답 본문을 읽고, 안내된 재시도 대기 시간를 지키며, 현재 동시 요청 수나 요청 한도를 확인한 다음 요청 한 건만 다시 보냅니다.
• Timeout 또는 TLS error: 로컬 proxy, firewall, DNS, 인증서 문제와 API 응답을 구분합니다. TLS 검증을 영구적으로 끄지 마세요.
• Workspace 기록 없음: 이전 환경 변수가 요청을 다른 제공업체로 라우팅하지 않았는지 확인합니다.

설정을 바꾼 뒤에는 짧은 요청 한 건을 다시 보내 Workspace 기록과 시각을 맞춰 보세요. 정상 작동이 확인된 후 streaming, tools, 긴 컨텍스트 또는 에이전트 루프를 한 단계씩 추가하면 새 오류가 생길 때마다 진단 범위를 작게 유지할 수 있습니다.

다음 단계: OpenAI-compatible API

자신의 key와 OpenAI-compatible route를 사용하는 practical setup은 OpenAI API 페이지에서 확인하세요. 이는 official OpenAI key가 아니라 BetterToken의 compatible API를 설명합니다.