«Sber AI API»는 마치 하나의 엔드포인트 (endpoint) 이름처럼 들리지만, 사실 그렇지 않습니다. 코드를 작성할 때 이 문구를 그대로 넣을 수는 없으며, 오직 검증을 시작할 때만 사용할 수 있습니다. 검색창에 «sber ai api»를 입력하면 기본 주소와 몇 줄의 인증 정보가 담긴 단일 링크를 기대하게 되지만, 실제로는 서로 다른 키를 사용하는 다양한 제품들이 모여 있는 브랜드명을 마주하게 됩니다. Sber의 문서에는 이 이름으로 된 단일 제품 페이지가 존재하지 않습니다. developer-портал developers.sber.ru의 2026년 7월 18일 데이터에 따르면, GigaChat API와 SaluteSpeech는 각각 별도의 개요, 빠른 시작(quick start), API 레퍼런스 섹션을 가진 두 개의 별도로 문서화된 제품입니다.

이는 단순히 표현 방식에 대한 불평이 아닙니다. 이러한 오류는 바로 아키텍처 (architecture) 단계에서 큰 비용을 초래합니다. 하나의 인증 방식과 하나의 기본 URL을 설정해 두었는데, 일주일 뒤에 음성 합성 (speech synthesis)은 다른 프로젝트에 있고, 이미지 생성은 아예 다른 도메인에 있으며, 채팅 모델의 키는 거기서 통용되지 않는다는 사실을 알게 될 수 있기 때문입니다. 통합 (integration)의 첫 번째 줄을 작성하기 전에 파악하는 것이 나중에 액세스 계층 (access layer)을 다시 작성하는 것보다 훨씬 저렴합니다.

접근 방식의 차이를 비교한다면, provod.ai (OpenRouter의 러시아 유사 서비스)와 같은 별도의 호환 카탈로그처럼 하나의 키로 여러 모델을 동시에 사용하는 반대 모델을 염두에 두는 것이 유용합니다. 이것은 독립적인 서비스이며 Sber AI의 표면이 아니므로, 이 둘을 혼동해서는 안 됩니다.

왜 플랫폼 브랜드가 하나의 API 이름처럼 보일까요?

대부분의 오류가 시작되는 논란의 여지가 있는 가정은 다음과 같습니다: «Sber AI»가 하나의 통합 엔드포인트 (integration endpoint)를 충분히 정확하게 가리킨다는 생각입니다. 이름은 건물 위의 간판처럼 작동하지만, 내부에는 각자의 자물쇠를 가진 서로 다른 임차인들이 일하고 있습니다. 개발자는 «Sber AI 플랫폼»을 읽고, 머릿속으로 «그렇다면 하나의 계정, 하나의 키, 하나의 문서가 있겠군»이라고 추측하며 이 가정을 코드에 반영하게 됩니다.

이를 확인하는 방법은 간단합니다. 단일 API라면 반드시 일치해야 하는 세 가지 요소, 즉 도메인(Domain), 키 메커니즘(Key mechanism), 그리고 인증 공간(Authorization space)을 살펴보면 됩니다. Sber AI 브랜드 아래의 서비스들은 이 요소들이 일치하지 않습니다. GigaChat와 SaluteSpeech는 developers.sber.ru 포털을 공유하지만, 계정 정보(Credentials)를 공유하지는 않습니다. Kandinsky는 아예 다른 도메인으로 분리되어 있습니다. 또한 브랜드와 연관되어 보이는 것 중 일부는 유료 API가 전혀 없는 연구용 릴리스(Research releases)들입니다.

브랜드가 하나의 운영사와 동일하지 않은 이유를 설명해 주는 기업 측면의 세부 사항도 있습니다. 2023년 1월 CNews의 보도에 따르면, GigaChat 개발을 담당하는 팀인 SberDevices(법인명 ООО «СалютДевайсы»)는 Sberbank가 지분을 매각한 후 별도의 회사가 되었으며, Sberbank는 전략적 기술 파트너로 남았습니다. 저는 이를 통해 제품의 현재 상태를 결론짓는 것이 아니라, «Sber»/«Sber AI»가 위에 나열된 모든 서비스를 운영하는 단일 법인이 아니라 옴니버스형 브랜드(Umbrella brand)라는 사실을 기록하고자 합니다.

GigaChat 키는 실제로 어떻게 발급받나요?

가장 상업적으로 성숙한 서비스부터 시작하겠습니다. developers.sber.ru의 GigaChat API 제품 페이지(2026년 7월 18일 확인 기준)에 따르면, 이는 세 가지 모델 수준(Lite, Pro, MAX)을 갖춘 공개 상업 서비스로, 연간 1,000,000 토큰의 무료 개인 한도와 별도의 비즈니스 패키지를 제공합니다. 무료 한도 수치는 출시 날짜에 맞춰 다시 확인해야 합니다. Sber는 요금제와 용량을 정기적으로 변경하므로, 여기에 기재된 모든 숫자는 특정 시점의 스냅샷일 뿐입니다.

키를 얻는 과정은 다음과 같습니다. developers.sber.ru의 퀵 스타트(Quick start) 섹션에 따른 절차입니다:

1. Studio 개인 계정에 접속하여 프로젝트를 생성합니다.
2. «API 설정(API Settings)»을 엽니다.
3. «키 받기(Get key)»를 클릭하면 일회용 인증 키(Authorization key)를 받게 됩니다. 이는 Client ID와 Client Secret 쌍을 Base64로 인코딩한 것입니다.
4. 프로젝트 참여자 중 Owner 또는 Administrator 역할을 가진 사용자만 키를 가져올 수 있습니다.

그리고 여기서 브랜드가 숨기고 있는 첫 번째 갈림길이 나타납니다. 온보딩 (onboarding) 경로가 계정 유형에 따라 나뉩니다. 개인(Physical persons)과 개인사업자/법인(IP/legal entities)에게는 별도의 퀵 스타트 (quick start) 지침이 적용됩니다. 즉, 단일 GigaChat 내부에서도 키 발급은 단일한 플랫폼 절차가 아니며, 서류상 귀하가 누구인지에 따라 달라집니다.

그다음 키는 개념적으로 대략 다음과 같이 사용됩니다 (실제적인 비밀은 없습니다):

# Authorization key = Base64(Client ID:Client Secret), Studio에서 발급됨
curl -X POST "https://gigachat.devices.sberbank.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer <access_token>" \
...

여기서 중요한 단어는 바로 "이 키"입니다. 이는 GigaChat에 관한 것이며 오직 GigaChat에만 해당됩니다. 그 이유는 다음과 같습니다.

SaluteSpeech와 FusionBrain은 GigaChat과 무엇이 다른가?

SaluteSpeech (음성 합성 및 인식)는 GigaChat과는 별개의 제품으로 문서화되어 있습니다. developers.sber.ru의 개요 (overview) 및 퀵 스타트 섹션에 따르면: 등록은 Studio 내의 Sber ID를 통해 진행되며, 별도의 전용 프로젝트가 필요하고, API 접근은 자체적인 액세스 토큰 (Access Token)으로 제한됩니다. 인증되지 않은 요청은 명확하게 거부됩니다. 게다가 SaluteSpeech는 GigaChat의 어떤 인증 범위 (authorization scope)와도 분리된 개인용 인증 범위인 SALUTE_SPEECH_PERS를 별도로 정의합니다. 이는 두 제품이 자격 증명(credentials)이나 키의 네임스페이스 (namespace)를 공유하지 않는다는 직접적인 증거입니다.

Kandinsky (이미지 및 비디오 생성)는 여기서 한 걸음 더 나아갑니다. fusionbrain.ai의 문서에 따르면, Kandinsky 모델은 별도의 계정 시스템을 가진 FusionBrain 플랫폼을 통해 별도의 도메인에서 사용할 수 있습니다. API 접근에는 fusionbrain.ai의 별도 패널에서 생성되어 X-Key/X-Secret 헤더를 통해 전달되는 Key/Secret 쌍이 필요하며, 이는 GigaChat 및 SaluteSpeech에 사용되는 developers.sber.ru 계정과는 독립적입니다. 솔직히 말씀드리면, 이번 세션에서 fusionbrain.ai 페이지를 직접적인 자동 요청으로 가져오는 데 실패했습니다 (네트워크 제한으로 보임). 따라서 내용은 공식 문서의 인덱싱된 스니펫(snippet)을 통해 확인했습니다. 헤더 이름이나 제한 사항(limits)에 대한 정확성이 매우 중요하다면, 통합하기 전에 이 항목을 수동으로 다시 확인하십시오.

그리고 브랜드가 API에 섞어 놓았지만, 엄밀히 말해 API는 아닌 네 번째 카테고리가 있습니다. developers.sber.ru는 RuGPT-3, SBERT, Golos, Kandinsky 3D 등 오픈 소스(open-source) 아티팩트 카탈로그를 게시합니다. 이는 GigaChat 및 SaluteSpeech에 있는 키와 SLA(서비스 수준 협약)를 포함한 유료 API 래퍼(wrapper)가 없는 저장소(repository) 및 모델들입니다. 이 카탈로그에 모델이 존재한다고 해서 해당 모델에 준비된 관리형 엔드포인트(managed endpoint)가 있다는 의미는 아닙니다. "Sber AI"라는 우산은 상업용 API와 관련 없는 연구용 릴리스를 동시에 아우르고 있습니다.

GigaChat, SaluteSpeech 및 FusionBrain의 문서를 통해 제가 내린 결론은 원문의 직접적인 인용이 아닌 종합적인 분석 결과입니다. 즉, 하나의 브랜드 아래 최소 세 개의 별도로 인증되는 통합 접점(integration surfaces)이 공존하고 있다는 것입니다. 소스들은 각 제품을 개별적으로 설명하고 있으며, 이것들이 서로 다른 접점이라는 결론은 제가 직접 도출한 것입니다.

검증 가능한 서비스 지도는 어떤 모습인가요?

단일 엔드포인트(endpoint)에 대한 가정이 아키텍처에 그대로 반영되지 않도록, 저는 각 서비스를 서비스, API, 키(key), 문서(documentation), 상태(status)라는 다섯 가지 필수 필드로 분류합니다. 검토 날짜 기준으로 원본 문서(primary document)를 통해 이 다섯 가지가 모두 확인된 경우에만 통합 옵션 카탈로그에 등록됩니다. 원본 문서가 없다면 해당 항목은 "기본적으로 사용 가능"한 것이 아니라 "검증되지 않음" 상태가 됩니다. 키를 획득하는 방법이 확인되지 않은 경우도 마찬가지이며, API 상태가 명시되지 않은 경우도 동일합니다.

이 지도는 전시용이 아니라 필터로서 작동합니다. 이 지도의 목적은 모든 멋진 것을 보여주는 것이 아니라, 다른 제품에 속한 기능이 아키텍처에 들어오는 것을 방지하는 것입니다. 여기서 예외적인 도메인은 다음과 같습니다: 플랫폼의 한 서비스에 특정 기능이 존재한다고 해서 다른 서비스에서도 해당 기능을 사용할 수 있다는 것을 증명하지는 않습니다. 만약 음성 합성(speech synthesis) 기능이 정확히 필요하다면, GigaChat 기록은 도움이 되지 않습니다. GigaChat은 다른 키와 다른 프로젝트를 사용하기 때문입니다.

무엇을 재검토해야 하는지에 대해 별도로 언급하자면, 상태, 키, 문서에는 유효 기간이 있습니다. Studio 포털은 요금제, 무료 한도, 퀵스타트(quickstart) URL을 자주 업데이트하므로, 이 지도는 대조 날짜 기준으로만 유효하며 매번 새로운 통합을 진행하기 전에 다시 작성되어야 합니다. 2026년 7월 18일이라는 날짜는 영원한 진리가 아니라 검토 시점으로 유지하는 것입니다.

실무에서 어디서 문제가 발생하는가?

첫 번째 실패 모드는 키(key)를 이전할 때 발생합니다. 개발자가 GigaChat을 위한 Authorization key(인증 키)를 받고, SaluteSpeech 인터페이스에서 익숙한 Studio를 보게 되면 동일한 키를 사용하려고 시도합니다. 하지만 SaluteSpeech는 별도의 Access Token(액세스 토큰)과 고유한 SALUTE_SPEECH_PERS 범위를 가지기 때문에 요청이 거부됩니다. 증상은 "인증이 깨졌다"처럼 보이지만, 실제 원인은 존재하지 않는 공통 키 공간을 가정했기 때문입니다.

두 번째 오류는 도메인(domain)과 관련이 있습니다. 팀이 "동일한 통합 환경 내에서" 이미지 생성을 계획하며 기본 도메인인 developers.sber.ru를 설정합니다. 하지만 Kandinsky는 그곳에서 응답하지 않습니다. Kandinsky는 fusionbrain.ai에서 작동하며, 별도의 Key/Secret(키/비밀키)과 X-Key/X-Secret 헤더를 사용합니다. 이는 액세스 권한의 버그가 아니라, 다른 도메인에 있는 다른 제품인 것입니다.

세 번째 오류는 카탈로그와 API를 혼동하는 것입니다. 오픈 소스(open-source) 릴리스 목록에서 예를 들어 SBERT를 선택하고, 요금제가 적용된 관리형 엔드포인트(endpoint)를 기대합니다. 하지만 그런 것은 없습니다. 그것은 유료 API 래퍼(wrapper)가 없는 저장소(repository)일 뿐입니다. 기능은 "존재"하지만, 키를 통해 호출할 수 있는 형태는 아닙니다.

어떻게 서비스를 선택하고 아키텍처 설계 오류를 피할 수 있는가?

해결책은 간단하고 단 하나입니다. 플랫폼 브랜드가 아니라, 특정 서비스와 해당 서비스의 문서(documentation)를 기준으로 API를 선택하십시오. 실무적으로 이는 첫 번째 코드 라인을 작성하기 전에 5가지 필드로 구성된 기록을 수집하고, 확인 날짜 기준으로 각 항목이 1차 문서(primary document)에 의해 확인되었는지 반드시 점검하는 것을 의미합니다.

제가 사용하는 작업 절차는 다음과 같습니다. 먼저, 서비스를 단순히 "Sber AI"라고 부르는 대신 GigaChat, SaluteSpeech 또는 FusionBrain/Kandinsky와 같이 서비스의 실제 명칭을 부릅니다. 그다음, 해당 서비스의 자체 문서(documentation) 섹션을 열어 도메인(domain)과 인증 방식(authorization method)을 기록합니다. 이어서 본인의 계정 유형에 맞는 키(key) 발급 절차를 진행합니다. 예를 들어 GigaChat의 경우 개인(физлиц)을 위한 지침과 개인 사업자/법인(ИП/юрлиц)을 위한 지침이 다르며, 이는 단순한 서식의 차이가 아니라 서로 다른 플로우(flow)입니다. 그 후 상태를 기록합니다: 상용 GA(General Availability), 별도 프로젝트, 또는 SLA가 없는 오픈 소스(open-source) 등입니다. 이렇게 다섯 가지 필드가 모두 채워진 기록만이 통합(integration) 가능한 목록에 포함됩니다.

이 접근 방식의 비용은 정직합니다. 아키텍처(architecture)를 선택하기 전, 각 서비스에 대해 1차 문서(primary documents)를 수동으로 대조해야 하기 때문입니다. 대신 이 방식은 가장 비용이 많이 드는 오류 유형을 배제합니다. 즉, 액세스 계층(access layer)은 하나의 가상 엔드포인트(endpoint)를 기준으로 설계되었는데, 실제로는 세 개의 서로 다른 엔드포인트로 구성되어 있는 경우를 방지합니다. 여기서 논쟁의 여지가 있는 교환 조건은 확인 작업에 시간이 소요된다는 점이지만, 이는 코드 재작성(rewriting)을 방지해 줍니다. 저는 단일 호출(call) 이상의 복잡성을 가진 모든 통합 작업에서 이 교환이 이득이라고 생각합니다.

이 지도가 해결하지 못하는 것