API 키로 인증하기

이 페이지는 CLEVI 게이트웨이에 API 키로 인증하는 방법을 다룹니다.
OpenAI 호환 경로와 Anthropic 호환 경로 모두 키 하나로 인증하며,
키를 넣는 헤더의 허용 범위와 SDK 에 설정할 base URL 이 규격마다 다릅니다.

인증 헤더

두 호환 규격 모두 API 키 하나로 인증합니다. 키는 콘솔의 API 키 화면에서 발급하며, 같은 화면에서 폐기와 사용 범위를 관리합니다.

헤더 이름은 대소문자를 가리지 않습니다. Anthropic SDK 가 보내는 x-api-key 도 그대로 동작합니다.

base URL

쓰던 SDK 는 base URL 만 아래 주소로 바꾸면 그대로 씁니다. 두 주소는 /v1 을 포함하는지가 다릅니다.

인증 확인

키와 base URL 을 넣고 모델 목록을 조회하면 인증 여부를 바로 알 수 있습니다. 아래 셋은 같은 조회를 curl, OpenAI SDK, Anthropic SDK 로 합니다.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

sk-... 자리에는 API 키 화면에서 발급한 키를 넣습니다.

• 응답이 200 이면 인증이 된 것입니다. data 에 이 키로 호출할 수 있는 모델 목록이 담깁니다.
• 응답이 401 이면 아래 인증 실패 절의 순서로 확인합니다.

함께 쓰는 헤더

모두 선택 사항입니다. 문제를 추적하려면 X-Request-Id 는 넣어 두는 편이 좋습니다.

인증 실패

키가 없거나 만료·폐기된 키를 보내면 401 입니다. OpenAI 호환 경로에서 키 없이 호출하면 아래 본문이 오고, Anthropic 호환 경로의 error.type 은 authentication_error 입니다.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

1. API 키 화면에서 키 상태를 확인합니다. 만료·폐기된 키면 새로 발급합니다.
2. 헤더 이름이 X-API-Key 또는 Authorization 인지 확인합니다.
3. OpenAI 호환 경로에서 Authorization 을 쓴다면 Bearer 접두사를 확인합니다.