데이터 계층이 붙은 LLM 게이트웨이

엔드포인트는 하나가 아니라 여섯 개입니다

/api/v1 아래는 모두 모델 호출이지만, 모델 종류가 어떤 엔드포인트가 응답할 수 있는지를 정합니다. 응답 형식도 각각 다릅니다.

세 개의 채팅 접점은 네이티브 구현이고 프로토콜 변환 계층이 아닙니다. 각자 자기 프로토콜로 이벤트를 흘리므로, 지금 쓰는 파서를 그대로 쓰면 됩니다.

엔드포인트는 모델 종류로 고르세요. 추측하지 마세요.

카탈로그의 모든 모델에는 model_kind가 붙어 있고, 그 종류가 어떤 엔드포인트로 호출할 수 있는지를 정합니다. 카탈로그 조회는 무료이며 로컬 카탈로그를 읽습니다.

# discover before you call — free, reads the catalog
GET /api/v1/models   # every kind, with channels and rates
GET /api/v1/models/{model_id}  # one model, in detail
GET /api/v1/videos/models     # video_generation only
GET /api/v1/decisions/models  # decisions only

?provider=를 붙이면 한 공급자만, ?exclude_video_and_decisions=true를 붙이면 채팅과 이미지만 봅니다. 등재가 호환 보장은 아닙니다. 동영상 모델은 채팅 요청에 응답하지 않고, 시도하면 model_kind_mismatch가 돌아옵니다.

기본 라우트, 또는 헤더 하나로 공급자 지정

한 모델을 여러 업스트림 채널이 제공할 수 있고, 채널마다 공급자와 공개 요율이 다릅니다. 헤더를 빼면 플랫폼이 하나를 고르고, X-Felo-Channel을 보내면 직접 고릅니다.

# first channel only — no automatic fallback
X-Felo-Channel: claude-cc
X-Felo-Channel: claude-cc,anthropic  # ordered selection, not a retry list

• 값은 공개 채널 코드의 순서 있는 목록이며 모델의 channels[].code에서 가져옵니다. 적은 순서대로 검증됩니다.
• 첫 번째 채널의 공급자 그룹만 제출되고, 요금도 그 채널의 요율로 계산됩니다.
• 자동 폴백은 없습니다. 채널 목록은 선택이지 재시도 정책이 아닙니다—공급자가 죽으면 애플리케이션에서 다른 채널로 다시 보내세요.

X-Felo-Channel은 위 여섯 개 생성 엔드포인트 모두에서 동작합니다. 데이터 API와 Felo APIs에는 적용되지 않습니다. 그쪽은 요청에서 지정한 공급자로 그대로 갑니다.

호출 한 번에 실제로 드는 비용

모델 호출은 입력·출력·캐시 토큰 단위로 과금되고 채널의 할인 계수가 곱해집니다. 요율은 읽기 쉽도록 100만 토큰 기준으로 보여 주지만, 과금은 현재 가격 스냅샷의 토큰 단위 정밀도로 하므로 짧은 요청이 100만 토큰으로 올림되지 않습니다.

• 캐시 요율은 프로토콜 응답이 캐시 사용량을 보고할 때만 적용됩니다. 보고하지 않는 모델은 전부 입력 요율로 과금됩니다.
• 모델 서비스가 실제로 수행하고 보고한 웹 검색은 건당 $0.01입니다.
• 프롬프트 길이로 구간이 나뉘는 모델도 있습니다. Claude Haiku 5.5는 10만 토큰까지 입력 $0.10·출력 $0.50(100만 토큰당)이고, 그를 넘으면 요청 전체가 $0.50·$2.50이 됩니다.
• 첫 충전은 $1부터입니다. 구독도, 좌석 요금도, 최소 약정도 없습니다—쓰지 않는 키에는 비용이 들지 않습니다.

데이터 API 호출과 Felo 워크플로도 같은 잔액에서, 각자의 공개 기준(성공한 요청 단위, 반환 항목 단위, 실제 사용량)으로 과금됩니다.

닮았지만 전혀 다른 두 가지 한도

잔액이 없으면 402 INSUFFICIENT_CREDITS, 너무 빠르면 429 RATE_LIMITED입니다. 기다리면 두 번째는 풀리고, 첫 번째는 절대 풀리지 않습니다.

현재 강제 레이트 리밋을 문서화한 곳은 /v2/chat뿐입니다. 모델 호출도 업스트림에서 제한될 수 있고, 그때는 429로 나타납니다—숫자를 하드코딩하지 말고 X-RateLimit-*와 Retry-After를 읽으세요. 모든 응답에는 request_id가 붙고, 보낸 X-Request-Id는 그대로 돌아오므로 양쪽 로그를 맞출 수 있습니다.

이미지와 동영상은 백그라운드에서 끝납니다

두 생성 엔드포인트는 결과 대신 task_id를 돌려줍니다. 제출하고, 폴링하고, 받아오세요—작업이 만들어진 뒤의 실패는 대부분 HTTP 오류가 아니라 200에 종료 상태로 담겨 옵니다.

# submit, then poll the task
POST /api/v1/images/generations       → task_id
GET  /api/v1/images/generations/{id}  → status, result
POST /api/v1/videos/generations       → task_id
GET  /api/v1/videos/generations/{id}  → status, result

결과보다 상태를 먼저 보세요. failed와 interrupted도 답이고, 이유는 error.message에 있습니다. 제출 시점에 402가 났다면 작업은 만들어지지 않았습니다. SuperAgent는 다릅니다—stream_key를 돌려주고 SSE로 이벤트를 밀어 주므로 폴링할 것이 없습니다.

베이스 URL만 바꾸고 클라이언트는 그대로

베이스 URL을 이쪽으로 돌리면 두 SDK 모두 수정 없이 동작합니다. npx feloapi-cli setup이 Claude Code와 Codex에 같은 설정을 써 줍니다.

# OpenAI SDK
base_url = "https://openapi.felo.ai/api/v1"

# Anthropic SDK — one level up; the SDK appends /v1/messages
base_url = "https://openapi.felo.ai/api"

# pin a provider (optional)
default_headers = {"X-Felo-Channel": "claude-cc"}

모델 ID는 공급자마다 같지 않습니다. 베이스 URL을 바꾸기 전에 카탈로그에서 모델을 고르세요. 그러지 않으면 첫 호출이 404입니다.

게이트웨이가 보통 넘겨주는 나머지 절반

LLM 게이트웨이는 모델 호출을 중계합니다. 여기서는 같은 키로 ⁦5,000+⁩ 규모의 API 카탈로그까지 닿습니다—에이전트 안의 검색, 그것이 만든 슬라이드, 다시 읽어 들인 문서가 모두 같은 잔액에서 빠지고, 벤더 세 곳을 더 붙일 필요가 없습니다.

• Search
• PPT Task
• SuperAgent
• Web Fetch
• X Search
• Mindmap
• Landing Page Task
• LiveDoc
• YouTube Subtitling

데이터 API는 /v1/beta 아래에서 Tavily, Exa, Apollo 등 카탈로그의 각 공급자에 각자의 공개 기준으로 과금됩니다.

LLM 게이트웨이에 대해 자주 받는 여섯 가지 질문