AI Gateway 시작하기

AI Gateway에서는 여러 AI 공급사의 모델을 하나의 API 키로 호출합니다. 키 발급, 비용 한도, 사용량을 한 자리에서 관리하므로, 공급사마다 따로 키를 관리하거나 비용을 합산하지 않아도 됩니다.

등장 배경

AI 기능을 붙이다 보면 OpenAI, Anthropic, Google처럼 공급사가 늘어납니다. 공급사마다 키를 따로 발급받고, 한도를 따로 관리하고, 청구서를 따로 합산해야 합니다. 모델을 바꾸거나 도구를 추가할 때마다 같은 작업을 반복합니다.

AI Gateway는 이 관리 지점을 하나로 모읍니다. Gateway에서 키를 발급하고 한도를 적용하고 비용은 응답마다 바로 확인할 수 있습니다. 새 공급사나 새 모델, 새 외부 도구가 들어와도 Gateway를 통해 바로 적용할 수 있습니다.

핵심 개념

자세한 내용은 한도 개요와 에러 코드를 참고합니다.

Base URL과 엔드포인트

API 요청 주소는 base URL과 엔드포인트 경로 두 부분으로 나뉩니다. base URL은 요청을 어디로 보낼지를, 엔드포인트 경로는 무엇을 할지(채팅·임베딩·이미지 같은 작업 종류)를 정합니다. 둘을 이으면 실제로 요청이 가는 전체 주소가 됩니다.

엔드포인트 경로는 보통 SDK가 알아서 붙입니다. 그래서 직접 바꾸는 값은 base URL 하나뿐입니다. 예를 들어 기존 OpenAI SDK는 https://api.openai.com/v1로 요청을 보내는데, 이 base URL만 https://gw.letsur.ai/v1로 바꾸면 같은 코드가 Gateway를 거칩니다. 인증·한도·사용량 집계는 Gateway가 대신 처리합니다.

Gateway는 채팅 외에도 여러 작업을 엔드포인트로 제공합니다. 자주 쓰는 경로는 다음과 같습니다.

전체 목록과 엔드포인트별 응답 형식은 지원 엔드포인트에서 확인합니다.

OpenAI 호환

OpenAI 호환 경로는 요청·응답 형식이 OpenAI API와 같은 스키마를 따릅니다. 그래서 기존 OpenAI SDK나 외부 도구에서 위 base URL과 키만 바꾸면 대부분의 모델이 그대로 동작합니다. 일부 모델은 공급사 라우트에 따라 동작이 달라지니 에셋 카탈로그의 라우팅 갭을 참고합니다.

다음 코드는 OpenAI SDK에서 두 줄만 바꾼 예시입니다.

from openai import OpenAI
 
# 변경하는 것은 두 줄뿐
client = OpenAI(
    api_key="<API_KEY>",
    base_url="https://gw.letsur.ai/v1",
)

지원하는 엔드포인트는 지원 엔드포인트에서 확인합니다.

Gateway 활성화 (Admin)

Admin은 토글을 켜서 Space에 AI Gateway를 활성화합니다.

준비물

• 본인이 Space의 Admin 권한을 가진 계정 (역할)
• AI Gateway 개요를 한 번 본 상태 (위 Gateway 개요)

Space의 Admin과 Member 모두가 AI Gateway에 진입할 수 있는 상태입니다.

멤버에게 알리기

활성화 직후 왼쪽 메뉴에 AI Gateway가 멤버 전원에게 자동으로 나타납니다. 별도 안내 메일은 보내지 않습니다.

멤버에게 안내할 때 다음을 함께 전달합니다.

• 본인 키 발급 위치 (왼쪽 메뉴 → AI Gateway → 키 탭)
• 키별 한도와 한도 초과 시 동작 (한도를 설정한 경우)
• 외부 도구(Claude Code 등) 연동이 가능하다는 점 (Integrations)

활성화 이후 다음 작업은 목적에 따라 갈라집니다.

• 한도 정책을 먼저 잡습니다 — 한도 개요
• 멤버에게 활성화 사실을 알립니다 — Gateway 멤버 관리
• 본인이 직접 첫 호출을 시도합니다 — 아래 첫 API 호출하기

자주 막히는 곳

비활성화와 재활성화

같은 토글을 OFF로 전환하면 비활성화됩니다. 비활성화하면 다음과 같이 동작합니다.

• Space 멤버 전원에게 왼쪽 메뉴의 AI Gateway 항목이 즉시 사라집니다.
• 활성 키들은 사용 불가 상태가 되어 모든 호출이 거부됩니다.

재활성화하려면 토글을 다시 ON으로 켭니다. 보존된 키들이 다시 사용 가능한 상태가 됩니다. 키 값은 그대로 유지되므로 외부 도구 설정을 다시 바꾸지 않아도 됩니다.

첫 API 호출하기

준비물

• Space에서 활성화된 AI Gateway (위 Gateway 활성화)
• 터미널에서 curl(명령줄에서 서버에 API 요청을 보내는 도구)을 쓸 수 있는 환경, 또는 Python·TypeScript

curl https://gw.letsur.ai/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "안녕"}]
  }'

from openai import OpenAI
 
client = OpenAI(
    api_key="<API_KEY>",
    base_url="https://gw.letsur.ai/v1",
)
 
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "안녕"}],
)
 
print(response.choices[0].message.content)
print(response.usage)

다음 단계

OpenAI 호환 외부 도구(Cursor·Codex 등)는 base URL을 https://gw.letsur.ai/v1로 설정하면 같은 키로 동작합니다. Claude Code 같은 Anthropic native 클라이언트는 Messages로 들어옵니다. 도구별 설정은 Integrations에서 확인합니다.

이번 달 본인 사용량은 왼쪽 메뉴에서 AI Gateway → 사용량 탭에서 확인합니다 (사용량 분석).

막혔을 때

관련 문서