본문으로 건너뛰기
인증

인증

모든 요청은 헤더에 API 키를 담아 보냅니다. 계정당 키 하나로 모든 엔드포인트와 모든 모델을 사용할 수 있으며, 두 가지 헤더 형식 중 어느 쪽이든 됩니다.

헤더 · OpenAI SDK
Authorization: Bearer YOUR_API_KEY
헤더 · Anthropic SDK
x-api-key: YOUR_API_KEY

허용되는 헤더

두 헤더 모두 엔드포인트가 사용하는 형식에 상관없이 모든 /v1 엔드포인트에서 읽습니다. 둘 중 하나를 보내세요.

헤더 설명
Authorization: Bearer <key> 가장 먼저 확인합니다. Bearer는 대문자 B로 쓰고 키 앞에 공백 하나를 두세요. OpenAI SDK가 이 헤더를 보냅니다.
x-api-key: <key> 요청에 Authorization: Bearer 헤더가 없을 때 읽습니다. Anthropic SDK가 이 헤더를 보냅니다.

OpenAI SDK에서는 키와 base URL을 설정하세요. SDK가 Authorization: Bearer를 보냅니다.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print(response.choices[0].message.content)

Anthropic SDK에서는 키와 /v1 없는 base URL을 설정하세요. SDK가 x-api-key를 보냅니다.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com"
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print("".join(block.text for block in message.content if block.type == "text"))

키가 필요한 엔드포인트

엔드포인트 키
POST /v1/chat/completions 필수
POST /v1/messages 필수
POST /v1/responses 필수
POST /v1/tokenize 필수
POST /v1/messages/count_tokens 필수
GET /v1/models 필요 없음

내 키

  • 키는 sk- 뒤에 A–Z, a–z, 0–9, -, _ 중 43자가 붙은 형태로, 총 46자입니다.
  • 모든 계정에는 키가 정확히 하나 있습니다. Keys & usage를 처음 열 때 생성됩니다.
  • 이 키는 계정의 API에 대한 전체 접근 권한을 줍니다. 모든 엔드포인트, 모든 모델, 잔액 전체가 해당됩니다.
  • 키에는 만료일이 없습니다. 교체하거나 폐기할 때까지 작동합니다.

교체와 폐기

키 교체와 폐기는 Keys & usage 페이지에서 합니다. Keys & usage

작업 결과
교체 새 키가 발급되고 이전 키는 작동을 멈춥니다. 새 키는 즉시 작동합니다.
폐기 키가 작동을 멈추며 새 키는 발급되지 않습니다. 작동하는 키를 다시 받으려면 키를 교체하세요.
  • 둘 다 즉시 적용됩니다. 이전 키를 사용한 다음 요청은 401로 응답됩니다. 이전 키가 모든 곳에서 거부되기까지 최대 60초로 보세요.
  • 계정의 모든 클라이언트가 같은 키를 사용하므로 키를 교체하면 모두 영향을 받습니다. 교체 직후 클라이언트에 새 키를 넣으세요.
  • 잔액, 사용량, 플러드 보호는 키가 아니라 계정에 속합니다. 새 키는 같은 잔액과, 현재 분의 같은 요청 횟수를 이어받습니다.

오류

모든 인증 실패는 상태 401, 유형 authentication_error입니다. 메시지로 경우를 구분합니다.

상태 유형 메시지 시점
401 authentication_error Missing authentication 요청에 Authorization: Bearer 헤더도, sk-로 시작하는 x-api-key 헤더도 없습니다. 소문자 bearer나 Bearer 없는 Authorization 값에 대한 응답도 이것입니다.
401 authentication_error Invalid API key 계정의 현재 키가 아닙니다. 잘못 입력했거나, 폐기되었거나, 교체로 대체되었습니다.
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
  • /v1/messages를 제외한 모든 경로에서는 error 객체에 code: "invalid_api_key"와 param: null도 들어 있으며, 키가 없는 경우에도 마찬가지입니다.
  • 키는 본문을 읽기 전에 확인합니다. 유효한 키가 없는 요청은 본문이 잘못되었거나 너무 커도 401을 받습니다.
  • sk-로 시작하지 않는 Authorization: Bearer 값은 API 키로 취급하지 않습니다. 토큰이 유효하지 않거나 만료되었다는 메시지와 함께 401을 받습니다.

브라우저와 CORS

  • API는 고정된 origin 목록에 대해서만 교차 출처 브라우저 요청에 응답합니다. 다른 origin의 페이지에 있는 JavaScript는 /v1 응답을 읽을 수 없습니다.
  • API는 서버에서 호출하고, 페이지는 사용자의 서버와 통신하게 하세요. 이렇게 하면 키가 페이지 소스에 노출되지 않습니다.
  • 서버 측 코드와 명령줄 도구는 영향을 받지 않습니다. 이 규칙은 브라우저에서만 적용됩니다.
  • shannon-ai.com에 로그인했다고 해서 /v1 요청이 인증되지는 않습니다. 쿠키는 읽지 않으며, 키가 유일한 자격 증명입니다.
  • 허용된 origin에서는 브라우저가 content-type, authorization, x-api-key, anthropic-version, anthropic-beta, openai-beta, x-request-id를 보낼 수 있고 응답 헤더 x-request-id를 읽을 수 있습니다.

키를 안전하게 보관하기

  • 키는 서버에 보관하세요. 웹 페이지, 모바일 앱, 공개 저장소에 넣지 마세요. 키를 가진 사람은 누구나 잔액 전체를 쓸 수 있습니다.
  • 키를 코드에 쓰지 말고 환경 변수나 시크릿 저장소에서 불러오세요.
  • 키가 유출되었을 수 있다면 Keys & usage에서 교체하세요. 이전 키는 즉시 작동을 멈춥니다.
  • 유출이 있었다면 Keys & usage의 요청 목록을 확인하세요. 최근 30일간 키로 보낸 모든 요청이 표시됩니다.