Integrate Kandinsky for Image Generation with Russian Text
Client from e-commerce: need to generate product images with Russian text on banners. English models (SDXL, DALL-E) produce gibberish — Cyrillic turns into hieroglyphs. Even after fine-tuning on Russian data, Western models often mix up letters or generate unreadable text. Kandinsky from Sber solves this natively: its CLIP model is trained on Russian-language texts, so prompts like 'red felt boot with patterns' are processed without translation. The model understands cultural contexts — from 'Pushkin's fairy tales' to 'Soviet mosaics'. We integrate Kandinsky in two ways: via Sber's cloud API (FusionBrain) or by deploying the model on your GPUs using PyTorch and diffusers. You get data sovereignty in the self-hosted option and savings on GPU-hours under high loads.
To be clear: if your project targets a Russian-speaking audience, choosing Kandinsky gives you an edge in speed and quality. Western models require additional prompt preprocessing — translation, style adaptation. Kandinsky works out of the box. Meanwhile, the self-hosted version ensures data sovereignty: images never leave your perimeter, critical for banks, retail, and government sectors.
Why Kandinsky Beats Western Models for Russian-Language Projects
Kandinsky wins due to native Russian support: no meaning loss in prompt translation, cultural references (fairy tales, toponyms, Soviet design) are recognized correctly. The self-hosted version ensures full data sovereignty — images never leave your perimeter. And for specifically Russian concepts, generation quality is higher than with English-centric models, even after fine-tuning.
What Integration Options Exist for Kandinsky?
The choice depends on load, latency requirements, and budget. Below is a comparison of key parameters.
| Parameter | Sber API | Self-hosted (Kandinsky 2.2/3) |
|---|---|---|
| Latency (p99) | ~5-10 sec | ~1-3 sec (on GPU A100) |
| Max resolution | 1536×1536 | 1024×1024 (Kandinsky 3) |
| Cost | Depends on plan | GPU + electricity |
| Data control | Processed on Sber servers | Full control, on-premise |
| Integration time | 1-2 days | 1-2 weeks |
| Russian prompt support | Yes | Yes |
Kandinsky 2.2: stable version, optimized for inference. Kandinsky 3: improved quality, supports 1024x1024, but needs more VRAM. We recommend version 3 for new projects if hardware allows.
Sber API
We use the official FusionBrain API. Below is a working Python client with async polling logic.
import httpx
import base64
import asyncio
class KandinskyClient:
def __init__(self, api_key: str, secret_key: str):
self.api_key = api_key
self.secret_key = secret_key
self.base_url = "https://api-key.fusionbrain.ai/key/api/v1"
async def generate(
self,
prompt: str,
width: int = 1024,
height: int = 1024,
num_images: int = 1,
style: str = "DEFAULT" # DEFAULT, KANDINSKY, UHD, ANIME, DIGITAL_ART
) -> list[bytes]:
# Get the list of models
async with httpx.AsyncClient() as client:
models_resp = await client.get(
f"{self.base_url}/models",
headers={"X-Key": f"Key {self.api_key}", "X-Secret": f"Secret {self.secret_key}"}
)
model_id = models_resp.json()[0]["id"]
# Start generation
params = {
"type": "GENERATE",
"numImages": num_images,
"width": width,
"height": height,
"generateParams": {"query": prompt},
"style": style
}
gen_resp = await client.post(
f"{self.base_url}/text2image/run",
headers={"X-Key": f"Key {self.api_key}", "X-Secret": f"Secret {self.secret_key}"},
data={"model_id": str(model_id), "params": json.dumps(params)}
)
uuid = gen_resp.json()["uuid"]
# Poll for result
return await self.poll_result(client, uuid)
async def poll_result(self, client, uuid: str, max_attempts: int = 30) -> list[bytes]:
headers = {"X-Key": f"Key {self.api_key}", "X-Secret": f"Secret {self.secret_key}"}
for _ in range(max_attempts):
await asyncio.sleep(2)
resp = await client.get(f"{self.base_url}/text2image/status/{uuid}", headers=headers)
data = resp.json()
if data["status"] == "DONE":
return [base64.b64decode(img) for img in data["images"]]
raise TimeoutError("Generation timeout")
Self-hosted via Hugging Face
We deploy Kandinsky 2.2 on your GPU server. Suitable if you need to generate hundreds of images per minute and keep data inside the perimeter. In production, we use Triton Inference Server for optimized inference, vLLM for memory management, and MLflow for metric logging.
from diffusers import KandinskyV22Pipeline, KandinskyV22PriorPipeline
import torch
prior = KandinskyV22PriorPipeline.from_pretrained(
"kandinsky-community/kandinsky-2-2-prior",
torch_dtype=torch.float16
).to("cuda")
pipeline = KandinskyV22Pipeline.from_pretrained(
"kandinsky-community/kandinsky-2-2-decoder",
torch_dtype=torch.float16
).to("cuda")
def generate_kandinsky(prompt: str, negative_prompt: str = "") -> bytes:
# Prior: text -> embeddings
image_embeds, negative_image_embeds = prior(
prompt, negative_prompt=negative_prompt
).to_tuple()
# Decoder: embeddings -> image
image = pipeline(
image_embeds=image_embeds,
negative_image_embeds=negative_image_embeds,
height=768,
width=768,
num_inference_steps=25
).images[0]
import io
buf = io.BytesIO()
image.save(buf, format="PNG")
return buf.getvalue()
How We Do It: A Real Case
On one project for a large retailer, we migrated from the Sber API to self-hosted Kandinsky 2.2 on an NVIDIA A100. The result: generation latency dropped from 8 seconds to 1.2 seconds (p99). The client was generating 1,500 product banners per hour with Russian text, and the API's rate limit was causing bottlenecks. By deploying self-hosted, we eliminated queuing and reduced costs by 40% compared to API consumption at that volume. We used the diffusers library with FP16, Triton Inference Server for batching, and integrated via RabbitMQ for async job distribution.
How to Choose Between API and Self-hosted
If you need to quickly test a hypothesis or the load is low — the Sber API takes 1-2 days to get started. For production with high generation volumes (500+ images per hour) and strict latency requirements, choose self-hosted. Self-hosted requires a GPU with 16+ GB VRAM (e.g., NVIDIA A10G or A100). Deployment costs are calculated individually, but the savings on GPU-hours at high volumes can be substantial compared to cloud API. Not sure? Contact us, we'll help you decide.
Turnkey Work Process
Our engineers have experience implementing Kandinsky in production — over 10 successful projects. Integration follows a standard pipeline:
- Analysis: study your scenarios (sizes, styles, load).
- Design: choose the option (API/self-hosted), design the architecture.
- Implementation: write integration code, adapt generation parameters.
- Testing: verify quality on real cases, measure latency.
- Deployment: deploy into your infrastructure, set up monitoring.
What's Included in the Work
- API setup or self-hosted model deployment.
- Writing a Python client library.
- Integration with your backend (CI/CD, queues, caching).
- Documentation (OpenAPI, README).
- Team training (1-2 sessions).
- Technical support for 1 month.
Integration Timelines
| Stage | API | Self-hosted |
|---|---|---|
| Analysis + Design | 1 day | 2-3 days |
| Implementation + Testing | 1 day | 5-7 days |
| Deployment + Documentation | 1 day | 2-3 days |
| TOTAL | 3 days | 10-14 days |
Typical Mistakes When Working with Kandinsky
- Wrong style parameter: if not specified, the model uses DEFAULT, which may not suit your tasks. For photorealistic images, use UHD.
- Large sizes via API: size greater than 1536 results in a 400 error. Use client-side resizing.
- Self-hosted: incompatible diffusers versions. Kandinsky 2.2 requires diffusers >= 0.21.0. Check the version in requirements.txt.
- Request limit: the API has a rate limit (default 10 requests/sec). Set up a queue or switch to self-hosted.
If you've encountered these issues — contact us, we'll help resolve them.
We take on the full cycle: from model selection to handing over a ready service. In the end, you get a working endpoint, documentation, and a trained team. We guarantee generation quality — we compare results with your references before signing off.
Contact us — we'll assess your project in 1 day. Over 5 years of experience integrating neural networks into production. Get a consultation on Kandinsky integration.