인증
모든 요청은 헤더에 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) import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com/v1'
});
const response = await client.chat.completions.create({
model: 'shannon-3',
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
]
});
console.log(response.choices[0].message.content); curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
]
}' 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")) import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com'
});
const message = await client.messages.create({
model: 'shannon-3',
max_tokens: 1024,
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
]
});
console.log(message.content.filter((block) => block.type === 'text').map((block) => block.text).join('')); curl -X POST "https://api.shannon-ai.com/v1/messages" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
]
}' 키가 필요한 엔드포인트
| 엔드포인트 | 키 |
|---|---|
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
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} /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일간 키로 보낸 모든 요청이 표시됩니다.