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

pip install gigachat

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 GIGACHAT_CA_BUNDLE_FILE / ca_bundle_file if needed).

Development-only (not recommended):

set GIGACHAT_VERIFY_SSL_CERTS=false or pass verify_ssl_certs=False to GigaChat(...).

Usage Examples

The examples below assume authentication and the model are configured via environment variables (for example, GIGACHAT_CREDENTIALS and GIGACHAT_MODEL). See Authentication.

Migration Note

client.chat and client.achat now expose the primary chat/completions surface:

• client.chat.create(...)
• client.chat.stream(...)
• client.chat.parse(...)
• await client.achat.create(...)
• client.achat.stream(...)
• await client.achat.parse(...)

The previous contract remains available through root compatibility methods:

• client.chat(...)
• client.stream(...)
• client.chat_parse(...)
• await client.achat(...)
• client.astream(...)
• await client.achat_parse(...)

Root compatibility shims such as client.chat(...), client.stream(...), client.chat_parse(...), client.achat(...), client.astream(...), and client.achat_parse(...) still work for the old chat contract. They are not deprecated and do not emit DeprecationWarning.

During the migration, old gigachat.models.Chat*, Messages*, Function*, and Usage imports still resolve to legacy compatibility aliases. Use ChatCompletionRequest, ChatCompletionResponse, ChatMessage, and related Chat* primary models for the new contract.

For a step-by-step checklist and import mapping, see MIGRATION_GUIDE.md

Upgrading to 0.2.4a1 also changes v1 function-schema defaults and nested property access, and moves several advanced v2 fields to untyped extras. Review the release compatibility notes even if you continue using the v1 methods.

Basic Chat

from gigachat import GigaChat

with GigaChat(credentials="<your_authorization_key>", model="GigaChat-2") as client:
    response = client.chat.create("Hello, GigaChat!")
    print(response.messages[0].content[0].text)

There is no default model: specify one via model= in the request payload, the GigaChat(model=...) constructor, or the GIGACHAT_MODEL environment variable. Otherwise the SDK raises ModelNotSpecifiedError. Use client.get_models() to list available models.

Streaming

Receive tokens as they are generated:

from gigachat import GigaChat

with GigaChat() as client:
    for chunk in client.chat.stream("Write a short poem about programming"):
        if chunk.messages and chunk.messages[0].content:
            print(chunk.messages[0].content[0].text or "", end="", flush=True)
    print()  # Newline at the end

Async

Use async/await for non-blocking operations:

import asyncio
from gigachat import GigaChat

async def main():
    async with GigaChat() as client:
        # Async chat
        response = await client.achat.create("Explain quantum computing in simple terms")
        print(response.messages[0].content[0].text)

        # Async streaming
        print("Streaming response:")
        async for chunk in client.achat.stream("Tell me a joke"):
            if chunk.messages and chunk.messages[0].content:
                print(chunk.messages[0].content[0].text or "", end="", flush=True)
        print()

asyncio.run(main())

Embeddings

Generate vector representations of text:

from gigachat import GigaChat

with GigaChat() as client:
    result = client.embeddings(
        ["Hello, world!", "Machine learning is fascinating"],
        model="Embeddings",
    )

    for i, item in enumerate(result.data):
        print(f"Text {i + 1}: {len(item.embedding)} dimensions")

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):

from typing import Optional

from gigachat import GigaChat
from gigachat.models import (
    ChatCompletionRequest,
    ChatFunctionSpecification,
    ChatMessage,
    ChatRankerOptions,
    ChatTool,
    PrimaryChatFunctionCall,
)


def extract_function_call(message: ChatMessage) -> Optional[PrimaryChatFunctionCall]:
    if message.function_call is not None:
        return message.function_call

    for part in message.content or []:
        if part.function_call is not None:
            return part.function_call

    return None


weather_function = ChatFunctionSpecification(
    name="get_weather",
    description="Get current weather for a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name, e.g., Tokyo",
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit",
            },
        },
        "required": ["location"],
    },
)

chat = ChatCompletionRequest(
    messages=[ChatMessage(role="user", content="What's the weather in Tokyo?")],
    tools=[ChatTool(functions={"specifications": [weather_function]})],
)

with GigaChat() as client:
    response = client.chat.create(chat)
    message = response.messages[0]
    function_call = extract_function_call(message)

    if function_call is not None:
        print(f"Function: {function_call.name}")
        print(f"Arguments: {function_call.arguments}")

Note: By default, ranker_options is not sent.

Enable function/tool ranking explicitly and limit the number of ranked functions:

chat = ChatCompletionRequest(
    messages=[ChatMessage(role="user", content="What's the weather in Tokyo?")],
    tools=[ChatTool(functions={"specifications": [weather_function]})],
    ranker_options=ChatRankerOptions(enabled=True, top_n=3),
)

Structured Output (JSON Schema) — Beta

Note: This feature is in beta. It may not work correctly with all model versions.

Get structured JSON responses validated against a schema:

from typing import List
from pydantic import BaseModel
from gigachat import GigaChat

class MathAnswer(BaseModel):
    steps: List[str]
    final_answer: str

with GigaChat() as client:
    completion, parsed = client.chat.parse(
        "Solve 8x + 7 = -23 step by step",
        response_format=MathAnswer,
        strict=True,
    )

print(completion.messages[0].content[0].text)
print(parsed.steps)
print(parsed.final_answer)

client.chat.parse() / client.achat.parse() may raise:

• LengthFinishReasonError if the response ended with finish_reason="length" and was truncated
• json.JSONDecodeError if the model returned invalid JSON
• pydantic.ValidationError if the JSON is valid but does not match the schema

The old-contract helpers remain available at client.chat_parse() / client.achat_parse().

See examples/example_structured_output.ipynb for more approaches (raw dict schema, Pydantic model schema, and the old-contract parse helper).

More examples

See the example index for runnable modules and configuration. Examples for the updated contracts include:

• Parallel function roundtrip: execute calls concurrently and return results with matching IDs.
• Any function selection: tool_config.mode="any" and a normal follow-up answer.
• Reasoning budgets: reasoning and total generation limits for v1/v2.
• Additional request fields: extra options at their API wire locations.
• Session headers and thread storage: request sessions and server-side conversation history.
• Response metadata: stream metadata and readable error handling.

Configuration

Constructor Parameters

API Scopes:

Environment Variables

All parameters can be configured via environment variables with the GIGACHAT_ prefix:

# Authentication
export GIGACHAT_CREDENTIALS="<your_authorization_key>"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"

# Connection
export GIGACHAT_BASE_URL="https://api.giga.chat/v1"
export GIGACHAT_TIMEOUT="60.0"
export GIGACHAT_VERIFY_SSL_CERTS="true"
# TLS: path to a CA bundle file (typically required - Python HTTP clients often don't use OS trust store by default)
export GIGACHAT_CA_BUNDLE_FILE="<your_ca_bundle_file>"

# Model (required unless passed per request - the SDK has no default model)
export GIGACHAT_MODEL="GigaChat-2"

# Optional default session identifier
export GIGACHAT_SESSION_ID="conversation-123"

# Retry
export GIGACHAT_MAX_RETRIES="3"
export GIGACHAT_RETRY_BACKOFF_FACTOR="0.5"

Then create a client without any parameters:

from gigachat import GigaChat

# Configuration loaded from environment variables
with GigaChat() as client:
    response = client.chat.create("Hello!")
    print(response.messages[0].content[0].text)

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 credentials and username/password are provided, OAuth credentials take precedence for token refresh.

1. Authorization Key (Recommended)

For detailed instructions, see the official documentation.

from gigachat import GigaChat

client = GigaChat(credentials="<your_authorization_key>")

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

client = GigaChat(
    credentials="<your_authorization_key>",
    scope="GIGACHAT_API_B2B",  # or GIGACHAT_API_CORP
)

2. Username and Password

Authenticate with a username and password. The default host (api.giga.chat) does not expose the /token endpoint, so this method requires an explicit base_url that supports password authentication:

from gigachat import GigaChat

client = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    user="<username>",
    password="<password>",
)

3. TLS Certificates (mTLS)

Authenticate using client certificates for mutual TLS:

from gigachat import GigaChat

client = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    cert_file="certs/client.pem",         # Client certificate
    key_file="certs/client.key",          # Client private key
    key_file_password="<key_password>",   # Optional: password for encrypted key
)

4. Access Token

Use a pre-obtained access token (JWT):

from gigachat import GigaChat

client = GigaChat(access_token="<your_access_token>")

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:

from gigachat import GigaChat

client = GigaChat(credentials="<your_authorization_key>")
token = client.get_token()  # Authenticate now
print(f"Token expires at: {token.expires_at}")

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):

export GIGACHAT_CA_BUNDLE_FILE="<path_to_root_ca_file>"

Or as argument:

from gigachat import GigaChat

with GigaChat(ca_bundle_file="<path_to_root_ca_file>") as client:
    response = client.chat.create("Hello!")
    print(response.messages[0].content[0].text)

OS-Specific Notes

Download the "Russian Trusted Root CA" certificate from Gosuslugi and configure GIGACHAT_CA_BUNDLE_FILE 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:

# Windows
set GIGACHAT_CA_BUNDLE_FILE=C:\path\to\Russian_Trusted_Root_CA.cer

# macOS/Linux
export GIGACHAT_CA_BUNDLE_FILE="/path/to/Russian_Trusted_Root_CA.crt"

Development-only: Disable TLS verification (not recommended)

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

from gigachat import GigaChat

client = GigaChat(verify_ssl_certs=False)

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

Error Handling

The library raises specific exceptions for different error conditions:

from gigachat import GigaChat
from gigachat.exceptions import (
    GigaChatException,
    AuthenticationError,
    RateLimitError,
    BadRequestError,
    ForbiddenError,
    NotFoundError,
    RequestEntityTooLargeError,
    UnprocessableEntityError,
    ServerError,
)

try:
    with GigaChat() as client:
        response = client.chat.create("Hello!")
        print(response.messages[0].content[0].text)
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except BadRequestError as e:
    print(f"Invalid request: {e}")
except ForbiddenError as e:
    print(f"Access denied: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except RequestEntityTooLargeError as e:
    print(f"Request payload too large: {e}")
except UnprocessableEntityError as e:
    print(f"Request validation failed: {e}")
except ServerError as e:
    print(f"Server error: {e}")
except GigaChatException as e:
    print(f"GigaChat error: {e}")

Exception Reference

Advanced Features

Context Variables

Set a default session identifier on a client with GigaChat(session_id="conversation-123") or GIGACHAT_SESSION_ID. Reuse it for requests belonging to the same conversation. The SDK sends it as X-Session-ID on API requests; it does not guarantee a cache hit. session_id_cvar overrides the client default, and custom_headers_cvar has the highest priority.

Track individual requests with context headers for logging and debugging:

from gigachat import GigaChat, session_id_cvar, request_id_cvar, custom_headers_cvar
import uuid

# Set session and request identifiers
session_id_cvar.set("user-session-12345")
request_id_cvar.set(str(uuid.uuid4()))

# Or add custom headers
custom_headers_cvar.set({"X-Custom-Header": "custom-value"})

with GigaChat() as client:
    response = client.chat.create("Hello!")

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:

from gigachat import GigaChat

client = GigaChat(
    max_retries=3,                          # Retry up to 3 times
    retry_backoff_factor=0.5,               # Delays: 0.5s, 1s, 2s
    retry_on_status_codes=(429, 500, 502, 503, 504),
)

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:

from gigachat import GigaChat

with GigaChat() as client:
    counts = client.tokens_count(["Hello, world!", "How are you today?"])
    for count in counts:
        print(f"Tokens: {count.tokens}, Characters: {count.characters}")

Available Models

List available models and their capabilities:

from gigachat import GigaChat

with GigaChat() as client:
    models = client.get_models()
    for model in models.data:
        print(f"{model.id_} (owned_by={model.owned_by})")

File Operations

Upload and manage files:

from gigachat import GigaChat

with GigaChat() as client:
    # Upload a file
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Uploaded: {uploaded.id}")

    # List files
    files = client.get_files()
    for file in files.data:
        print(f"{file.id}: {file.filename}")

    # Delete a file
    client.delete_file(uploaded.id)

Balance Check

Check your remaining token balance (prepaid accounts only):

from gigachat import GigaChat

with GigaChat(scope="GIGACHAT_API_B2B") as client:
    balance = client.get_balance()
    for entry in balance.balance:
        print(f"{entry.usage}: {entry.value}")

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-1.0.0 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:

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/gigachat.git
cd gigachat

# Install dependencies and pre-commit hooks
make install

# Run all checks
make all

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