API 키로 인증하기

CLEVI 게이트웨이는 OpenAI 호환 경로와 Anthropic 호환 경로를 API 키 하나로 인증합니다.
클라이언트에서 설정할 값은 키를 담는 인증 헤더와 SDK의 base URL 두 가지이며, 허용되는 헤더 형식과 base URL이 규격마다 다릅니다.
설정을 마친 뒤 모델 목록을 조회하면 인증 여부를 바로 확인할 수 있습니다.
인증에 실패하면 401을, 인증을 통과한 뒤 권한이나 한도 조건을 충족하지 못하면 403을 반환합니다.

API 키는 콘솔의 API 키 화면에서 발급하세요. 같은 화면에서 키의 폐기와 사용 범위를 관리할 수 있습니다.

인증 헤더

두 규격 모두 요청 헤더 하나에 API 키를 담습니다. X-API-Key 헤더와 Authorization 헤더 중 하나를 사용하며, 허용되는 형식은 규격에 따라 다릅니다.

OpenAI 호환 경로에서 Authorization 헤더를 사용할 때는 Bearer 접두사가 필요합니다. 접두사 없이 키만 보내면 게이트웨이가 요청을 거절합니다.

헤더 이름은 대소문자를 구분하지 않으므로 Anthropic SDK가 보내는 x-api-key 헤더도 그대로 동작합니다. 두 헤더를 모두 지정하면 X-API-Key 값이 우선 적용됩니다.

base URL

기존에 사용하던 SDK는 base URL만 아래 주소로 바꾸면 그대로 사용할 수 있습니다. 두 주소는 /v1을 포함하는지가 다르므로 규격에 맞는 주소를 그대로 지정하세요.

인증 확인

키와 base URL을 설정한 뒤 모델 목록을 조회하면 인증 여부를 확인할 수 있습니다. 아래 예제는 같은 조회를 curl, OpenAI SDK, Anthropic SDK로 실행합니다. sk-... 자리에는 API 키 화면에서 발급한 키를 넣으세요.

curl로 조회할 때는 두 규격 모두 /v1/models까지 전체 경로를 지정합니다. 첫 번째 명령은 OpenAI 호환 경로에 X-API-Key 헤더를, 두 번째 명령은 Anthropic 호환 경로에 Authorization 헤더를 사용합니다.

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"

OpenAI SDK는 base_url에 /v1까지 포함한 주소를 지정합니다.

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)

Anthropic SDK는 base_url을 /v1 앞에서 끝나는 주소로 지정합니다.
인증에는 SDK가 보내는 x-api-key 헤더를 그대로 사용합니다.

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)

어느 예제든 응답이 200이면 인증에 성공한 것이며, 응답의 data에 이 키로 호출할 수 있는 모델 목록이 담깁니다. 401이면 다음 절의 순서로 원인을 확인하세요.

인증 실패

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

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

401을 받으면 다음 순서로 확인하세요.

1. API 키 화면에서 키 상태를 확인하세요. 만료되었거나 폐기된 키면 새로 발급하세요.
2. 헤더 이름이 X-API-Key 또는 Authorization인지 확인하세요.
3. OpenAI 호환 경로에서 Authorization 헤더를 사용한다면 Bearer 접두사가 있는지 확인하세요.

수정한 뒤 인증 확인 절의 모델 목록 조회를 다시 실행해 200이 오는지 확인하세요.

함께 쓰는 헤더

다음 헤더는 모두 선택 사항입니다. 문제를 추적할 수 있도록 X-Request-Id는 지정해 두기를 권장합니다.

5xx가 반복되면 도움말과 문의로 X-Request-Id와 함께 알려 주세요. 직접 지정한 값이면 클라이언트 기록과 바로 대조할 수 있습니다.