New API
여러 프로바이더를 한 채널로 묶는 셀프호스트 게이트웨이
docker run --name new-api -d --restart always -p 3000:3000 -v ./data:/data calciumion/new-api:latest여러 모델 프로바이더를 하나의 OpenAI 호환 엔드포인트로 묶는 셀프호스트 게이트웨이입니다. 채널별 키 풀과 사용량 집계, 과금 관리 화면을 갖췄습니다. Docker 한 줄로 띄우고 관리 UI 에서 채널을 붙입니다.
판단
이럴 때 씁니다
- 여러 프로바이더 키를 한 엔드포인트 뒤로 숨기고 팀에 나눠 줘야 할 때
- 사용자별 사용량과 비용을 집계해 한도를 걸어야 할 때
- 키 하나가 막혔을 때 다른 채널로 자동 전환되게 하고 싶을 때
- 관리 화면이 있는 셀프호스트 게이트웨이가 필요할 때
이럴 땐 쓰지 마세요
- 개인이 키 하나만 쓰는 경우. 게이트웨이가 주는 이득보다 운영 부담이 큽니다
- AGPL 라이선스가 조직 정책과 맞지 않을 때
- 코드에 라이브러리로 끼워 넣는 방식을 원할 때
차별점
- 채널과 키 풀, 과금, 사용자 관리를 갖춘 관리 화면을 함께 제공합니다.
- Go 단일 바이너리와 Docker 이미지로 배포가 단순합니다.
- 모델 매핑으로 공개 이름과 실제 모델을 분리해 둘 수 있습니다.
- 포크가 1만 개를 넘을 만큼 자체 변형해 쓰는 사례가 많습니다.
워크플로
- 01Docker 로 컨테이너를 띄우고 데이터 디렉터리를 볼륨으로 붙입니다.
- 02관리 화면에서 프로바이더별 채널을 등록하고 모델 목록과 가격을 설정합니다.
- 03팀원에게는 게이트웨이가 발급한 토큰만 주고 원본 키는 노출하지 않습니다.
- 04사용량 화면에서 채널별 성공률과 비용을 보고 한도를 조정합니다.
주요 명령
| 명령 | 설명 |
|---|---|
docker run --name new-api -d --restart always -p 3000:3000 -v ./data:/data calciumion/new-api:latest | SQLite 기반으로 간단히 띄웁니다. |
함정
설치 전에 확인하세요
- 현재 버전이 1.0.0-rc 계열입니다. rc.27 부터 들어간 플러그인 시스템은 아직 실험 단계라고 저장소가 명시합니다.
- rc.26 이전에서 올라오면 영상 모델 가격을 전부 다시 설정해야 합니다.
- OpenRouter 채널에서 -thinking 으로 끝나는 모델명을 사고 모드 별칭으로 해석하던 동작이 제거됐습니다. 그 동작에 기대던 설정은 고쳐야 합니다.
- AGPL-3.0 이라 수정본을 서비스로 제공하면 소스 공개 의무가 따릅니다.
비교
LiteLLM 이 라이브러리와 프록시를 함께 제공하는 개발자 도구라면, New API 는 운영 화면을 갖춘 관리 시스템 쪽에 가깝습니다. 키를 나눠 주고 사용량을 정산해야 하는 상황에 맞습니다. 반대로 애플리케이션 코드 안에서 프로바이더를 추상화하는 것이 목적이면 게이트웨이는 과합니다.
최근 변경
v1.0.0-rc.32 는 OpenRouter 채널이 -thinking 으로 끝나는 모델명을 전부 사고 모드 별칭으로 해석하던 동작을 제거했습니다. 이전 동작에 기대던 설정은 모델명에 thinking 스위치를 명시하거나 채널 모델 매핑으로 공개 이름을 유지하도록 바꿔야 합니다. rc.31 에서 들어온 토큰 카운트 엔드포인트는 이번 버전에서 일시 비활성화됐습니다.