How to add GigaChat to a project in 3 steps. Guide and open-source tool

Recently, more and more developers are experimenting with large language models. GigaChat from Sber is one of the most accessible and powerful models on the Russian market. It has a detailed REST API that allows you to integrate the neural network into any product: from Telegram bots to complex enterprise systems.

However, as with any serious API, direct integration requires solving several routine but important tasks: you need to manage authentication, handle token lifecycle, and configure retries. All of this is standard boilerplate code that distracts from the main goal — the logic of the application itself.

I faced these tasks and, to make life easier for myself and other Go developers, I wrote gigago — a lightweight and idiomatic SDK. Its goal is to take care of all the "dirty work" and let you add GigaChat to your project in just a few minutes.

In this article, I will show you how to do this in 3 simple steps.

If you're interested in the process and want to follow further materials, I would appreciate a subscription to my Telegram channel. There, I publish useful development materials, breakdowns of complex concepts, productivity tips, and of course, handpicked memes: https://t.me/nullPointerDotEXE.

What is usually hidden "under the hood" when working with an API?

Before we move on to the guide, let's briefly look at the tasks that the SDK solves. If we were writing the integration from scratch, we would have to implement:

1. OAuth authentication process. According to the official documentation, to get a token, you need to send a POST request to https://ngw.devices.sberbank.ru:9443/api/v2/oauth, passing the Base64 encoded Client ID and Client Secret in the Authorization header.

2. Token lifecycle management. The access token only lasts for 30 minutes. This means the application needs a mechanism that will preemptively refresh it to avoid errors and downtime.

3. Retry logic. What if the token expires during the request? The API will return a 401 Unauthorized error. The correct behavior is to intercept this error, immediately request a new token, and repeat the original request.

4. HTTP client configuration. Setting timeouts, passing custom parameters, working with certificates — all of this requires additional code.

All of this are absolutely solvable tasks, but they take time. gigago does all of this for you "out of the box".

Step 1: Install the library

Let's start with the simplest part. To install gigago, just run one command in your terminal:

go get github.com/Role1776/gigago

Step 2: Initialize the client

Now for the interesting part. Let's create a gigago client. This is the heart of our integration. At this point, the SDK will automatically make the OAuth request, get the access token, and launch a goroutine in the background to refresh it automatically.

All you need is your authorization key, which you can get in your personal account.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Role1776/gigago"
)

func main() {
	ctx := context.Background()

	// Creating a client with your authorization key.
	// At this point, the SDK automatically obtains an access token.
	// For local development, you might need to disable certificate validation.
    	client, err := gigago.NewClient(ctx, "YOUR_API_KEY", gigago.WithCustomInsecureSkipVerify(true))
	if err != nil {
		log.Fatalf("Error creating client: %v", err)
	}
	// Important! Close the client to stop the background token update process.
	defer client.Close()

    // ... rest of the code
}

Note the defer client.Close() call. This is necessary to properly finish the background process that updates the token.

Step 3: Sending a Request and Receiving a Response

The client is ready, the token has been obtained and will update automatically. Now we just need to send a message to the model.

// ... continuing from the main function

// Get the model we will work with.
model := client.GenerativeModel("GigaChat")

// (Optional) Configure model parameters.
// You can set a system prompt, temperature, and other parameters.
model.SystemInstruction = "You are an experienced travel guide. Answer concisely and to the point."
model.Temperature = 0.7

// Create a message to send.
messages := []gigago.Message{
    {Role: gigago.RoleUser, Content: "What is the capital of France?"},
}

// Send the request and receive the response.
resp, err := model.Generate(ctx, messages)
if err != nil {
    log.Fatalf("Error generating response: %v", err)
}

// Print the response from the model.
fmt.Println(resp.Choices[0].Message.Content)

Run the code and get the result:

Paris.

That's it! We have successfully integrated GigaChat without writing any authentication or token management code.

Flexible Configuration for Advanced Tasks

Of course, real-world projects often require more fine-tuning. gigago supports this through functional options when creating the client.

For example, if you are a corporate client and need a different scope for the token:

client, err := gigago.NewClient(
    ctx,
    "YOUR_API_KEY",
    gigago.WithCustomScope("GIGACHAT_API_CORP"), // Specify scope for corporations
)

Available options:

• WithCustomURLAI(url string): Set the URL for the generation API.

• WithCustomURLOauth(url string): Set the URL for the OAuth service.

• WithCustomClient(client http.Client): Use a customhttp.Client

• WithCustomTimeout(timeout time.Duration): Set the timeout for HTTP requests.

• WithCustomScope(scope string): Specify scope for the token (GIGACHAT_API_PERS, GIGACHAT_API_B2B, GIGACHAT_API_CORP).

• WithCustomInsecureSkipVerify(bool): Disable TLS certificate validation.

Conclusion

My goal was to create a tool that helps developers get started with GigaChat in their Go projects more quickly and easily, following the best practices of the language. gigago takes care of the routine, allowing you to focus on the more interesting part—creating smart and useful applications.

I hope this guide and the library will be helpful to you.

The project is completely open-source and available on GitHub in version v1.0.0-rc.1. I would be very happy to receive your stars, questions, and, of course, Pull Requests. Let's develop the ecosystem of tools around GigaChat together!

Repository link: github.com/Role1776/gigago

As usual, I look forward to your comments. Good luck!