Sber 모델에 대한 첫 번째 요청이 실패할 때, 사람들은 엉뚱한 곳에서 수정을 시작하곤 합니다. 개발자는 문구를 바꾸고, 시스템 프롬프트(system prompt)를 추가하고, 온도(temperature)를 조절하지만, 서버는 침묵하거나 401 에러를 반환합니다. 원인은 거의 항상 그보다 낮은 계층에 있습니다. 즉, 요청이 모델에 도달조차 하지 못한 것이며, 여기서 프롬프트는 아무런 상관이 없습니다.

이 경로의 핵심 논지는 검증 가능합니다. 경로를 네 개의 독립적인 지점(개인 계정 및 키, 토큰 획득, 엔드포인트(endpoint), 페이로드(payload))으로 나누고 이를 개별적으로 확인하면, 모든 파라미터를 동시에 변경할 때보다 첫 번째 오류를 더 정확하게 찾아낼 수 있습니다. 이는 Sber Developers의 권장 사항이 아니라 이 경로를 작성한 저자의 공학적 해결책입니다. 따라서 이후 내용은 문서의 사실과 저자의 가설을 구분하겠습니다. 주장이 출처에 기반한 경우 옆에 링크가 표시되며, 저자의 방법론인 경우 직접적으로 명시하겠습니다.

아래의 모든 URL, 헤더(header), 값 및 제한 사항은 2026-07-18 기준 Sber Developers의 공식 문서와 대조되었습니다. 이 날짜와 읽는 시점 사이에 계약 내용이 변경될 수 있으므로, 최종적인 진실의 원천은 본 기사가 아닌 최신 문서 페이지입니다.

왜 하나의 요청이 아니라 네 개의 지점인가

솔직히 말해야 할 논쟁적인 기본 관념이 있습니다. 바로 "GigaChat API에 대한 첫 번째 실패한 요청은 프롬프트로 수정해야 한다"는 것입니다. 이는 잘못된 순서입니다. 하위 계층이 확인되지 않은 상태에서는 메시지의 내용이 결과에 영향을 미치지 않습니다. 메시지가 모델에 도달하지 못하기 때문입니다. 간단히 말해, GigaChat API는 인터페이스에서 보이는 채팅 제품 자체가 아니라, 모델 위에 구축된 REST 인터페이스입니다.

경로는 네 개의 체크포인트로 분해됩니다. 첫 번째: 개인 계정 및 인증 키, 즉 접근 권한이 실제로 부여되었는지 여부입니다. 두 번째: 토큰, 즉 키가 액세스 토큰(access token)으로 교환되는지 여부입니다. 세 번째: 엔드포인트(endpoint), 즉 요청이 올바른 헤더와 함께 올바른 URL로 전송되는지 여부입니다. 네 번째: 페이로드(payload), 즉 요청 본문(body)과 프롬프트 자체입니다.

분할의 의미는 각 지점이 고유한 오류 유형을 반환한다는 것입니다. 인증서 오류는 401 오류와 다르며, 401 오류는 "모델이 질문을 이해하지 못함"과도 다릅니다. 마지막으로 확인된 단계는 탐색 범위를 좁혀줍니다. 즉, 토큰은 발급되었으나 엔드포인트 (endpoint)로의 요청이 실패한다면, 문제는 프롬프트 (prompt)가 아니라 그 사이의 과정에 있다는 것입니다.

개인 계정 및 키: 액세스의 시작

"GigaChat API를 어떻게 얻나요"라는 질문은 실질적으로 개인 계정(personal account) 작업으로 귀결됩니다. 공식 Sber Developers 퀵스타트 가이드에 따르면, 개인 사용자는 먼저 Studio 계정에서 프로젝트를 등록한 다음, 프로젝트 설정에서 인증 키를 받습니다. 이 키는 Client ID와 Client Secret을 결합하여 생성된 Base64 문자열입니다. 이는 개인 계정의 비밀번호가 아니라, 오직 API만을 위해 존재하는 별개의 개체입니다.

"GigaChat API 받기"와 "GigaChat API 키 받기"라는 표현은 사실상 동일한 단계를 설명하며, 이 단계 없이는 다른 모든 것을 확인하는 것이 무의미합니다. 주의할 점은 GigaChat API 키가 생성 시 단 한 번만 표시된다는 것입니다. 생성 시 저장하지 않았다면 다시 발급해야 합니다. 따라서 프로젝트 생성 후 가장 먼저 해야 할 합리적인 행동은 코드를 짜는 것이 아니라, 환경 변수 (environment variable)를 설정하거나 비밀 관리자 (secrets manager)를 사용하는 것입니다.

이 비밀 키는 다양한 이름으로 검색됩니다: gigachat api key, api key gigachat, api key giga chat, giga chat api key 등. 모든 검색어에 대한 답은 동일합니다. 이는 두 부분으로 구성된 Base64 문자열이며, 그 역할상 일반적인 비밀번호보다는 다른 서비스에서 말하는 API 키 (API key)에 더 가깝습니다.

제품명 자체도 다양하게 표기되는데, 이는 오타라기보다 입력 습관의 차이입니다. "GigaChat API", 그 반대인 "API GigaChat", 혼합형인 "GigaChat API", 그리고 끝에 라틴 문자를 붙인 "GigaChat api"는 기술적으로 모두 동일합니다. 즉, Studio 계정 내 프로젝트에 대한 액세스를 의미합니다. 별도로 혼동을 주는 것은 "api giga chat", "giga chat api", "giga chat api"와 같이 두 단어로 띄어 쓰는 경우입니다. 브랜드는 마케팅 자료나 검색 제안에서 이처럼 표기되기도 하지만, 기술 문서에서는 붙여 쓰는 GigaChat으로 고정되어 있습니다.

«sber»라는 접두사 또한 우연이 아닙니다. 누군가는 gigachat sber api라고 쓰고, 누군가는 sber гига чат апи 또는 sber гига чат api라고 쓰며, 또 누군가는 gigachat ai api라는 영어 검색어로 동일한 제품을 찾기도 합니다. 이 모든 변형에는 하나의 동기가 있습니다. 바로 이것이 외부 클론이 아니라 Sberbank의 제품임을 명확히 하려는 것입니다. «гигачат от сбера api» 또는 «гига чат от сбера api»와 같은 표현은 GitHub의 포크(fork)가 아닌 공식적인 접속 경로를 찾으려는 의도를 더해줍니다. 이러한 접두사 뒤에는 보통 실질적인 질문이 따릅니다. 즉, 토큰 교환 시 어떤 스코프(scope)를 지정해야 하는가 하는 문제입니다. 개인을 위한 GIGACHAT_API_PERS를 사용할 것인지, 아니면 조직을 위한 GIGACHAT_API_B2B 및 GIGACHAT_API_CORP를 사용할 것인지에 대한 질문입니다.

«gigachat api бесплатно»(gigachat api 무료)라는 질문은 여기서 의도적으로 다루지 않겠습니다. 이 글은 요금제를 비교하는 글이 아니라, 첫 번째 요청을 위한 기록이기 때문입니다.

일부 개발자들은 문서 주소를 수동으로 추측하려고 시도합니다. 누군가는 브라우저에 http gigachat sber ru를 입력하고, 누군가는 developers sber ru portal products gigachat api와 같은 포털 경로를 입력해 보기도 합니다. 올바른 주소는 단 하나, developers.sber.ru이며, 바로 이곳에 GigaChat API 문서(영어 인터페이스 버전에서는 gigachat api docs)와 REST 레퍼런스가 위치해 있습니다. 형식적으로 이것이 바로 제품으로서의 sber gigachat api이며, 랜딩 페이지에서 «gigachat от сбера официальный сайт api»(sber의 gigachat 공식 사이트 api)로 소개되는 바로 그것입니다.

[

토큰을 받는 방법: oauth를 위한 별도의 POST 요청

인증 키 자체는 모델로 직접 요청을 보내지 않습니다. 인증 키는 액세스 토큰(access-token)을 받기 위해 필요하며, 이는 독립적인 라우트 제어 지점(control point)입니다. post-token 레퍼런스에 따르면, 토큰은 https://ngw.devices.sberbank.ru:9443/api/v2/oauth로 보내는 별도의 POST 요청을 통해 발급됩니다.

헤더는 다음과 같이 고정되어 있습니다: Content-Type: application/x-www-form-urlencoded, Authorization: Basic <auth_key> 및 최신 UUID4를 포함한 RqUID. 본문(body)에는 scope 파라미터가 전달됩니다. 개인의 경우 GIGACHAT_API_PERS(검색 시 이 설정은 종종 gigachat api pers로 표기됨)를 사용하며, 조직의 경우 GIGACHAT_API_B2B 또는 GIGACHAT_API_CORP를 사용합니다.

import uuid
import requests

...

문서에는 이 엔드포인트(endpoint)의 전체 수명 주기를 결정하는 두 가지 숫자가 명시되어 있습니다. 발급된 GigaChat API 토큰은 정확히 30분 동안 유효하며, 그 이후에는 새로운 교환이 필요합니다. 또한 별도의 제한 사항이 지정되어 있습니다: 토큰 획득을 위한 요청은 초당 10회를 초과할 수 없습니다. 확인 시점 기준, 사용 가능한 문서 조각 내에서 JSON 응답의 모든 필드에 대한 정확한 이름은 확인되지 않았으므로, 코드 내 토큰 추출 부분은 사실로 간주되지 않고 "문서와 대조할 것"으로 표시되었습니다.

이 엔드포인트의 진단적 가치는 프롬프트(prompt)와 관계없이 자체적인 코드로 응답한다는 점에 있습니다. 상태 코드 200과 비어 있지 않은 토큰이 반환되면: 레이어를 통과한 것입니다. 동일한 요청에서 인증서 오류가 발생하면: 키의 문제가 아니라 환경의 문제입니다(아래에서 상세 설명). 401 응답: 유효하지 않은 자격 증명입니다. 여기서 200이 나오지 않는다면, 모델 엔드포인트(endpoint)로 진행하는 것은 무의미합니다.

요청이 향하는 곳: 엔드포인트(endpoint) 및 Bearer

토큰을 획득하면 주소와 인증 방식이 모두 바뀝니다. GigaChat API REST 참조 문서에 따른 모델 호출을 위한 기본 GigaChat API URL은 https://api.giga.chat이며, 응답 생성을 위한 엔드포인트(endpoint)는 /v1/chat/completions입니다. 구형 도메인인 gigachat.devices.sberbank.ru는 확인 시점 기준으로 여전히 응답하지만, 공식적으로는 사용 중단(deprecated) 예정이므로 이를 기본 경로로 사용하는 것은 권장하지 않습니다.

인증(Authorization) 또한 별도의 계층으로 존재합니다. 모델 엔드포인트(endpoint)로 전달되는 헤더는 Basic이나 요청 본문(body)이 아닌 Authorization: Bearer <access_token> 형태입니다. Basic 키는 토큰에 접근할 수 있게 해주며, Bearer 토큰은 모델에 접근할 수 있게 해줍니다. 이 둘을 혼동하기 쉬운데, 이러한 혼동은 프롬프트(prompt)를 아무리 수정해도 해결되지 않는 바로 그 401 오류를 발생시킵니다.

resp = requests.post(
    "https://api.giga.chat/v1/chat/completions",
    headers={"Authorization": f"Bearer {access_token}"},
...

이것이 바로 requests 라이브러리를 통한 GigaChat API 호출 방식입니다. SDK 래퍼(wrapper) 없이 requests 라이브러리를 통해 직접 HTTPS 호출을 수행합니다. 이는 진단(diagnostics) 용도로 매우 유용합니다. 순수한 REST 방식을 사용하면 각 계층을 개별적으로 확인할 수 있기 때문입니다. 특정 시점에 어떤 GigaChat API 모델을 사용할 수 있는지는 본문이 아닌 최신 문서 카탈로그를 확인해야 합니다. 목록은 이러한 글이 발행되는 속도보다 더 빠르게 변경됩니다.

러시아 디지털개발부(Минцифры) 인증서 및 Python SDK

결과적으로 GigaChat API에 대한 접근은 네 개가 아닌 다섯 개의 계층으로 유지됩니다. 페이로드(payload)와 엔드포인트(endpoint) 이전에 가장 눈에 띄지 않는 계층이 하나 더 있습니다. 직접적인 요청이든 SDK를 통한 방식이든, GigaChat API를 사용하려면 러시아 디지털개발부(Минцифры) 국가 인증 센터(НУЦ)의 루트 인증서(root certificate)가 설치되어 있어야 합니다. 이 인증서가 없으면 /api/v2/oauth에 대한 요청이나 클라이언트 초기화 단계에서 인증서 검증 오류가 발생하며, 이는 키(key)나 토큰(token), 혹은 프롬프트(prompt)의 문제가 아닙니다. 인증서 관련 섹션에서는 python -m certifi를 통한 자동 설치 방법을 문서화하고 있습니다. 특정 운영체제(OS)에 따른 세부 사항은 해당 문서에서 확인해야 하며, 이는 플랫폼에 따라 다릅니다.

다음으로, 공식 라이브러리를 통해 GigaChat API를 연결하는 방법입니다. 패키지 이름은 gigachat이며, pip install gigachat 명령어로 설치할 수 있습니다. PyPI에 게시되어 있으며, 주요 리포지토리는 Sber의 구조를 따르는 GitHub의 ai-forever에서 관리합니다. 이것이 바로 일반적으로 완성된 예제를 찾게 되는 바로 그 GigaChat SDK입니다. SDK 가이드와 Python 클라이언트 참조 문서에 최소한의 초기화 방법이 설명되어 있습니다.

Python용 GigaChat API의 경우 다음과 같습니다:

from gigachat import GigaChat

with GigaChat(credentials="<base64_인증_키>") as client:
...

이 경로에서 매우 중요한 세부 사항은, 라이브러리가 chat.create 내부에서 키를 액세스 토큰(access-token)으로 직접 교환한다는 점입니다. 즉, SDK가 토큰 단계와 요청 단계를 하나의 호출로 결합합니다. Python용 GigaChat API 예제(example)로서는 편리하지만, 진단 측면에서는 불리합니다. 문제가 발생했을 때 두 계층 중 어느 곳에서 발생했는지 알 수 없기 때문입니다. SDK에서 토큰과 요청을 분리하여 확인한다는 것은 두 개의 서로 다른 메서드를 의미하는 것이 아니라, 로깅(logging) 및 가로채기(interception) 수준에서의 분리를 의미합니다.

클라이언트에는 우리가 다루는 장애 지점과 직접적으로 관련된 매개변수들이 있습니다: 기본값인 scope는 GIGACHAT_API_PERS이며, verify_ssl_certs는 기본적으로 True입니다. 또한 러시아 디지털 발전부(Минцифры) 인증서에 대한 명시적 경로를 지정하기 위한 ca_bundle_file이 있습니다. 별도의 오류 클래스인 AuthenticationError도 존재하는데, 이는 자격 증명이 유효하지 않거나 만료되었을 때, 즉 HTTP 401 오류가 발생할 때 라이브러리가 던지는 오류입니다. 이는 페이로드(payload) 및 모델 오류와 구별되며, 이것이 바로 우리가 이 경로를 구축하는 목적이자 분리 기준입니다.

여러 모델을 위한 다른 호환 경로

지금까지는 단일 벤더와 해당 벤더의 자체 인증에 대해 이야기했습니다. 흔히 발생하는 다음 과제는 다음과 같습니다: GigaChat 외에도 Claude, GPT, Gemini 또는 DeepSeek가 추가로 필요한 상황에서, 다섯 가지의 서로 다른 토큰, 도메인 및 인증서 체계를 구축하고 싶지는 않을 것입니다.

여기서 GigaChat 경로가 끝나고 다른 종류의 도구가 시작됩니다. provod.ai가 작동하는 방식은 다음과 같습니다. OpenAI 프로토콜을 이미 지원하는 클라이언트의 경우, 요청 로직을 다시 작성할 필요 없이 base_url과 키(key)를 교체하는 것만으로 연결할 수 있습니다. provod.ai의 단일 API를 통해 사용할 수 있는 모델 카탈로그는 통합 수준에서 이러한 요구 사항을 해결해 주지만, 위에서 다룬 내용을 무효화하지는 않습니다. 즉, provod.ai의 GigaChat가 기존 방식을 대체하는 것은 아니며, api.giga.chat으로 향하는 OAuth 체인은 어떤 경우에도 이 글에서 설명한 단계를 거쳐야 합니다.

from openai import OpenAI

client = OpenAI(
...

진단 포인트 지도