GigaChat Python SDK

Python SDK for the GigaChat REST API — a large language model.

This library is part of GigaChain and powers langchain-gigachat, the official LangChain integration for GigaChat.

Table of Contents

• Features
• Installation
• Quick Start
• Usage Examples
  • Basic Chat
  • Streaming
  • Async
  • Embeddings
  • Function Calling
  • More Examples
• Configuration
  • Constructor Parameters
  • Environment Variables
• Authentication
• SSL Certificates
• Error Handling
• Advanced Features
• API Reference
• Related Projects
• Contributing
• License

Features

• ✅ Chat completions — synchronous and asynchronous
• ✅ Streaming responses — real-time token generation
• ✅ Embeddings — text vectorization
• ✅ Function calling — tool use for building agents
• ✅ Vision — image understanding (multimodal)
• ✅ File operations — upload, retrieve, and delete files
• ✅ Token counting — estimate token usage before requests
• ✅ Multiple auth methods — OAuth credentials, password, TLS certificates, access tokens
• ✅ Automatic retry — configurable exponential backoff for transient errors
• ✅ Fully typed — Pydantic V2 models with
  py.typed
  marker for IDE support

Installation

Requirements: Python 3.8 — 3.13

Note: In production, keep TLS verification enabled (default). See SSL Certificates for setup instructions.

Quick Start

Get your GigaChat authorization key

For detailed instructions, see the official documentation.

Configure gigachat package to use TLS certificate

TLS certificate: follow the OS-specific installation steps on Gosuslugi (see SSL Certificates for how to configure

/

ca_bundle_file

if needed).

Development-only (not recommended):

set

or pass

verify_ssl_certs=False

to

GigaChat(...)

.

Usage Examples

The examples below assume authentication is configured via environment variables (for example,

GIGACHAT_CREDENTIALS

). See Authentication.

Basic Chat

Streaming

Receive tokens as they are generated:

Async

Use async/await for non-blocking operations:

Embeddings

Generate vector representations of text:

Note: The

model

parameter must be passed directly to the

embeddings()

method (default:

"Embeddings"

). The

model

set in the

GigaChat()

constructor does not affect embeddings.

Function Calling

Enable the model to call functions (tools):

More examples

See the examples/ folder for complete working examples including chat, functions, context variables, AI detection, and vision.

Configuration

Constructor Parameters

API Scopes:

Environment Variables

All parameters can be configured via environment variables with the

prefix:

Then create a client without any parameters:

Authentication

The library supports four authentication methods:

Authentication priority (when multiple are configured)

If multiple auth inputs are provided at the same time, the SDK applies this priority:

1. custom_headers_cvar["Authorization"]
   (if set) — overrides any other auth source.
2. authorization_cvar
   (if set) — overrides any other auth source and disables automatic token fetching/refresh (you manage the header value and its lifecycle).
3. Explicit
   access_token
   (constructor parameter /
   GIGACHAT_ACCESS_TOKEN
   ) — used as-is. If it fails with 401 and OAuth credentials or user/password are also configured, the SDK will fall back to fetching a new token.
4. OAuth
   credentials
   (constructor parameter /
   GIGACHAT_CREDENTIALS
   ) — used to obtain/refresh a token.
5. Username/password (
   user
   +
   password
   ) — used to obtain/refresh a token from the
   /token
   endpoint.

When both OAuth

and username/password are provided, OAuth credentials take precedence for token refresh.

1. Authorization Key (Recommended)

For detailed instructions, see the official documentation.

The authorization key encodes your API scope. If using the B2B or CORP API, specify the scope explicitly:

2. Username and Password

Authenticate with a username and password:

3. TLS Certificates (mTLS)

Authenticate using client certificates for mutual TLS:

4. Access Token

Use a pre-obtained access token (JWT):

Note: Access tokens expire after 30 minutes. Use this method when you manage token lifecycle externally.

Pre-authentication

By default, the library obtains an access token on the first API request. To authenticate immediately:

SSL Certificates

GigaChat endpoints use a certificate chain issued by the Russian Ministry of Digital Development. This section explains how to configure the GigaChat SDK to use the required certificates.

Quick Reference

• What you need: The "Russian Trusted Root CA" certificate file from Gosuslugi
• How to configure: Set
  GIGACHAT_CA_BUNDLE_FILE
  environment variable or pass
  ca_bundle_file
  argument to
  GigaChat()
• Why: Python HTTP clients typically use their own CA bundle (e.g.,
  certifi
  ) instead of the OS trust store

Configuration

Environment variable (recommended):

Or as argument:

OS-Specific Notes

Download the "Russian Trusted Root CA" certificate from Gosuslugi and configure

to point to the downloaded file:

• Windows: Downloaded as
  .cer
  file (e.g.,
  Russian Trusted Root CA.cer
  )
• macOS/Linux: Downloaded as
  .crt
  file (e.g.,
  Russian_Trusted_Root_CA.crt
  )

Example paths:

Development-only: Disable TLS verification (not recommended)

• Environment variable:
  GIGACHAT_VERIFY_SSL_CERTS=false
• Or pass
  verify_ssl_certs=False
  to
  GigaChat(...)

⚠️ Warning: Disabling certificate verification reduces security and is not recommended for production environments.

Error Handling

The library raises specific exceptions for different error conditions:

Exception Reference

Advanced Features

Context Variables

Track requests with custom headers for logging and debugging:

Available context variables:

Header precedence (when multiple sources set the same header):

• Explicit
  access_token
  passed by the SDK (or your code) sets
  Authorization: Bearer ...
  first.
• authorization_cvar
  overrides that
  Authorization
  header if it is set.
• custom_headers_cvar
  is applied last and overrides both (including
  Authorization
  ), as well as any other header.

Retry Configuration

Configure automatic retry with exponential backoff for transient errors:

Avoid “double retry” (important): If you use

gigachat

through a higher-level library that also retries (for example,

langchain-gigachat

/ LangChain), enable retries in only one layer. Otherwise, the effective number of attempts multiplies (e.g., 3 SDK retries × 3 framework retries).

Recommended defaults:

• Keep
  gigachat
  retries disabled (default
  max_retries=0
  ) when the outer framework retries.
• Or disable retries in the outer framework and configure retries here (recommended if you want one consistent retry policy).

Deprecations

• Messages.data_for_context
  : deprecated by the upstream API. Do not use it in new code.
  • Use instead: include the relevant information directly in the message
    content
    , or attach files via
    attachments
    (file IDs) when you need to provide additional context.
  • Timeline: the SDK will keep accepting
    data_for_context
    through the
    0.x
    line, but it may be removed in
    1.0.0
    (or earlier if the upstream API removes it).

Token Counting

Estimate token usage before sending requests:

Available Models

List available models and their capabilities:

File Operations

Upload and manage files:

Balance Check

Check your remaining token balance (prepaid accounts only):

API Reference

• GigaChat API Documentation
• Available Models
• Early Access Models
• Pricing

Related Projects

• GigaChain — A set of solutions for developing Russian-language LLM applications and multi-agent systems, with support for LangChain, LangGraph, LangChain4j, as well as GigaChat and other available LLMs. GigaChain covers the full development lifecycle: from prototyping and research to production deployment and ongoing support.
• langchain-gigachat — Official LangChain integration package for GigaChat

Versioning and stability

This project follows SemVer with additional clarity for pre-

releases:

• Patch releases (
  0.x.Y
  ): Backwards compatible bug fixes and internal changes.
• Minor releases (
  0.X.0
  ): May include backwards-incompatible changes. Any breaking changes must be called out in the GitHub Release notes.

Stable release gate

To ship a release marked Production/Stable, the following must be true:

• CI is green on
  main
  (lint, mypy, unit tests, integration replay).
• Local checks are green (
  make all
  ).
• Packaging is sane: sdist+wheel build and install from artifacts works (no missing files).
• Integration cassettes are current: re-recorded with real credentials and reviewed for scrubbing.

Contributing

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and code contributions!

Quick Start:

For detailed contributing guidelines, please see CONTRIBUTING.md.

This guide covers:

• Development setup and workflow
• Code quality standards and testing
• Commit message guidelines
• Pull request process
• Issue reporting guidelines
• Project architecture

All contributions are licensed under the MIT License.

License

This project is licensed under the MIT License.

Copyright © 2026 GigaChain