인증과 요청 헤더

API 형식에 맞는 base URL과 인증 헤더를 정확히 설정하세요.

OpenAI 호환 API와 Anthropic 네이티브 Messages의 기본 URL, 인증 헤더, 키 보관과 실패 대응을 다룹니다.

API 형식별 인증

두 API 형식 모두 Letsur AI 게이트웨이 API 키를 사용하지만 base URL과 헤더 형식이 다릅니다.

경로	base URL	인증
OpenAI 호환	`https://gw.letsur.ai/v1`	`Authorization: Bearer <API_KEY>`
Messages	`https://gw.letsur.ai`	`x-api-key: <API_KEY>` 권장, `Authorization`도 가능

base URL은 경로마다 다릅니다. OpenAI 호환은 /v1까지 포함하지만, Anthropic 네이티브는 /v1 없이 루트(https://gw.letsur.ai)만 씁니다. Anthropic SDK가 /v1/messages를 내부에서 붙이므로, base URL에 /v1을 또 넣으면 /v1/v1/messages가 되어 호출이 실패합니다.

OpenAI 호환 API 인증

가장 많이 쓰는 방식입니다. Authorization 헤더에 키를 Bearer <API_KEY> 형태로 담아 보냅니다.

아래 cURL 예제는 요청을 보내고 SDK 예제는 인증된 클라이언트를 초기화합니다. 모두 서버 측 환경 변수 LETSUR_API_KEY를 읽으며, 키 값은 코드나 명령어에 직접 넣지 않습니다.

cURL 요청


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/chat/completions \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

Python SDK


import os
 
from openai import OpenAI
 
api_key = os.environ.get("LETSUR_API_KEY")
if not api_key:
    raise RuntimeError("LETSUR_API_KEY가 필요합니다.")
 
client = OpenAI(api_key=api_key, base_url="https://gw.letsur.ai/v1")

TypeScript SDK


import OpenAI from 'openai'
 
const apiKey = process.env.LETSUR_API_KEY
if (!apiKey) throw new Error('LETSUR_API_KEY가 필요합니다.')
 
const client = new OpenAI({ apiKey, baseURL: 'https://gw.letsur.ai/v1' })

Anthropic Messages 인증

/v1/messages 경로는 Anthropic 표준 헤더를 씁니다. Letsur AI 게이트웨이 API 키를 쓸 때는 x-api-key를 권장하며, anthropic-version에 API 버전을 담아 보냅니다.

아래 cURL 예제는 요청을 보내고 SDK 예제는 인증된 클라이언트를 초기화합니다. 모두 같은 LETSUR_API_KEY 환경 변수를 사용합니다.

cURL 요청


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/messages \
    --header @- \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }' <<EOF
x-api-key: ${LETSUR_API_KEY}
EOF
)

Python SDK


import os
 
from anthropic import Anthropic
 
api_key = os.environ.get("LETSUR_API_KEY")
if not api_key:
    raise RuntimeError("LETSUR_API_KEY가 필요합니다.")
 
client = Anthropic(api_key=api_key, base_url="https://gw.letsur.ai")

TypeScript SDK


import Anthropic from '@anthropic-ai/sdk'
 
const apiKey = process.env.LETSUR_API_KEY
if (!apiKey) throw new Error('LETSUR_API_KEY가 필요합니다.')
 
const client = new Anthropic({ apiKey, baseURL: 'https://gw.letsur.ai' })

SDK를 쓰면 x-api-key와 anthropic-version 헤더가 자동으로 붙습니다. curl로 직접 호출할 때만 두 헤더를 명시합니다.

키 보관

AI 게이트웨이 API 키는 환경변수나 비밀 관리 도구에 보관합니다. 키가 없다면 AI 게이트웨이 > API 키에서 자신의 키를 만듭니다. 키 보관과 만료일은 API 키, 키별 월 한도는 한도에서 확인합니다.

키를 코드나 깃 저장소 또는 클라이언트(브라우저, 모바일 앱)에 그대로 넣지 않습니다. 키가 노출되면 누구나 호출할 수 있으므로 노출된 API 키 대응에 따라 해당 키를 즉시 삭제하고 새 키로 사용처를 복구합니다. 다른 사용자의 키라면 스페이스 Admin에게 즉시 알립니다.

인증 실패

인증에 실패하면 401 응답의 type, detail, error_ref를 확인합니다. 재시도와 문의 기준은 에러 코드를 따릅니다.

`type`	먼저 확인할 것
`missing_credentials`	선택한 API 형식에 맞는 인증 헤더를 요청에 포함했는지 확인합니다
`invalid_credentials`	헤더 형식과 AI 게이트웨이 API 키 값이 정확한지 확인합니다
`api_key_expired`	키의 만료일과 현재 사용할 수 있는 키를 확인합니다