Эта статья — техническое руководство для разработчиков, которые хотят подключить ChatGPT API (OpenAI API) в Беларуси. Здесь не будет рассуждений о том, зачем вам AI — если вы читаете это, вы уже знаете зачем. Вместо этого: конкретные примеры кода на Python, JavaScript и cURL, настройка SDK, streaming, function calling, vision API, JSON mode, обработка ошибок, миграция существующих проектов и оптимизация расходов.
OpenAI API недоступен из Беларуси напрямую — блокировка по IP, отсутствие поддержки белорусских платёжных средств, риск бана при использовании VPN. AIAI.BY — OpenAI-совместимый API-прокси для Беларуси с overhead менее 50 мс, оплатой в BYN и полной поддержкой всех функций OpenAI SDK. Подробнее о том, почему ChatGPT заблокирован в Беларуси и какие альтернативы доступа существуют, мы написали в отдельной статье «ChatGPT в Беларуси без VPN».
Ниже — полная техническая инструкция: от первого запроса до продакшн-интеграции с мониторингом и отказоустойчивостью.
Быстрый старт: первый запрос за 5 минут
Шаг 1: Зарегистрируйтесь на aiai.by и получите API-ключ в личном кабинете. Процесс занимает 2 минуты — нужен только email. Шаг 2: Пополните баланс через ЕРИП, банковский перевод или карту. Минимальный депозит — 10 BYN, этого хватит на несколько тысяч запросов к GPT-5-mini. Шаг 3: Отправьте первый запрос любым удобным способом — Python, JavaScript или cURL.
Python. Установите библиотеку: pip install openai. Затем: from openai import OpenAI; client = OpenAI(base_url="https://api.aiai.by/v1", api_key="ваш-ключ-aiai-by"); response = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": "Привет! Расскажи о себе."}]); print(response.choices[0].message.content). Это всё — ровно два параметра (base_url и api_key) отличают ваш код от прямого обращения к OpenAI. Все параметры — temperature, max_tokens, top_p, tools, response_format, structured output — работают идентично.
JavaScript / Node.js. Установите: npm install openai. Код: import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.aiai.by/v1', apiKey: 'ваш-ключ-aiai-by' }); const response = await client.chat.completions.create({ model: 'gpt-5', messages: [{ role: 'user', content: 'Привет!' }] }); console.log(response.choices[0].message.content);. Для CommonJS замените import на const OpenAI = require('openai').
cURL (для тестирования и отладки). Отправьте запрос из терминала: curl -X POST https://api.aiai.by/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer ваш-ключ-aiai-by" -d '{"model": "gpt-5", "messages": [{"role": "user", "content": "Привет!"}]}'. Ответ вернётся в формате JSON. Это удобно для быстрой проверки работоспособности ключа и отладки без написания кода.
Если всё настроено правильно, вы получите ответ от GPT-5 через 1–3 секунды. В личном кабинете AIAI.BY вы увидите лог запроса с деталями: модель, количество токенов, стоимость, латентность.
Streaming: потоковая передача ответа
Если вы делаете чат-бот или любой интерактивный интерфейс — без streaming будет плохо. Пользователь ждёт полный ответ 1–5 секунд и думает, что всё зависло. Со streaming текст появляется по мере генерации, первый токен приходит через 200–500 мс. При миграции клиентов с прямого OpenAI мы удивились, как многие не используют streaming — это бесплатно и заметно улучшает впечатление от продукта.
Python с streaming: from openai import OpenAI; client = OpenAI(base_url="https://api.aiai.by/v1", api_key="ключ"); stream = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": "Напиши бизнес-план кофейни в Минске"}], stream=True); for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end=""). Каждый chunk содержит фрагмент ответа (обычно 1–3 токена). Вы можете обрабатывать их в реальном времени — передавать в WebSocket, писать в SSE-поток или обновлять UI.
JavaScript с streaming: const stream = await client.chat.completions.create({ model: 'gpt-5', messages: [{ role: 'user', content: 'Напиши бизнес-план' }], stream: true }); for await (const chunk of stream) { const content = chunk.choices[0]?.delta?.content || ''; process.stdout.write(content); }. Для веб-приложений на Next.js или Express используйте Server-Sent Events (SSE) для передачи потока в браузер.
Важный нюанс: при использовании streaming через AIAI.BY overhead составляет те же 38–50 мс, но только на первый chunk. Все последующие фрагменты передаются без дополнительной задержки — мы не буферизуем поток, а проксируем его в реальном времени.
Function Calling: подключение AI к вашим системам
Function calling (вызов функций) позволяет AI вызывать ваш код — и через AIAI.BY это работает полностью. Суть: вы описываете модели набор доступных функций (инструментов), и модель решает, когда и какую функцию вызвать, формируя структурированные аргументы. Это позволяет AI взаимодействовать с вашими базами данных, внешними API, CRM, 1С — чем угодно.
Пример на Python — чат-бот, который умеет проверять статус заказа: tools = [{"type": "function", "function": {"name": "get_order_status", "description": "Проверяет статус заказа по номеру", "parameters": {"type": "object", "properties": {"order_id": {"type": "string", "description": "Номер заказа"}}, "required": ["order_id"]}}}]; response = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": "Где мой заказ BY-2026-1234?"}], tools=tools). Модель вернёт tool_calls с именем функции и аргументами, вы выполняете вызов на своей стороне и отправляете результат обратно в диалог.
При миграции клиентов с прямого OpenAI мы заметили распространённую ошибку: разработчики отправляют результат function call без роли tool, используя role: "assistant". Правильный формат: {"role": "tool", "tool_call_id": "call_abc123", "content": "Заказ BY-2026-1234: отправлен, трек BL123456789"}. Если tool_call_id не совпадает или роль указана неверно, API вернёт ошибку 400.
Function calling поддерживает параллельные вызовы — модель может запросить несколько функций одновременно (например, проверить статус заказа и получить данные клиента). Через AIAI.BY также работает параметр tool_choice: "auto" (модель решает сама), "required" (обязательно вызвать функцию), "none" (запрет вызовов), или конкретное имя функции для принудительного вызова.
Vision API: работа с изображениями
GPT-5 и GPT-4o поддерживают мультимодальный ввод — вы можете отправлять изображения вместе с текстом. На практике это значит: анализ фотографий продукции, распознавание документов, извлечение данных из скриншотов, проверка качества товаров по фото.
Пример на Python — отправка изображения по URL: response = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": [{"type": "text", "text": "Что на этом изображении? Извлеки все данные из документа."}, {"type": "image_url", "image_url": {"url": "https://example.com/document.jpg"}}]}]). Для отправки локального файла используйте base64-кодирование: import base64; image_data = base64.b64encode(open("photo.jpg", "rb").read()).decode(); затем передайте URL в формате data:image/jpeg;base64,{image_data}.
Практические применения для белорусского бизнеса: автоматическое распознавание накладных и ТТН (извлечение поставщика, суммы, перечня товаров из скана), контроль качества товаров на складе (фото -> отчёт о дефектах), анализ конкурентных материалов (скриншоты сайтов -> структурированное сравнение). Один наш клиент — логистическая компания из Бреста — обрабатывает через Vision API около 300 накладных в день с точностью 96%.
Важно учитывать стоимость: обработка изображений тарифицируется по количеству токенов, которые занимает изображение. Изображение 1024x1024 — около 765 токенов, высокого разрешения (до 2048x2048) — до 1500 токенов. Для массовой обработки документов рекомендуем уменьшать разрешение до минимально необходимого — это снижает стоимость в 2–3 раза без заметной потери качества распознавания.
JSON Mode и Structured Output: гарантированный формат ответа
Когда AI отвечает в свободной форме, ваш парсер ломается. Поэтому нужен предсказуемый формат ответа. OpenAI предлагает два механизма: JSON Mode (модель всегда возвращает валидный JSON) и Structured Output (модель возвращает JSON строго по вашей JSON Schema). Оба работают через AIAI.BY без ограничений.
JSON Mode включается параметром response_format: response = client.chat.completions.create(model="gpt-5", messages=[{"role": "system", "content": "Отвечай в формате JSON с полями: summary, sentiment, confidence"}, {"role": "user", "content": "Проанализируй отзыв: Отличный сервис, быстрая доставка!"}], response_format={"type": "json_object"}). Модель гарантированно вернёт валидный JSON, но структура может варьироваться.
Structured Output — более строгий вариант, появившийся в 2025 году. Вы передаёте JSON Schema, и модель обязана ей следовать: response_format={"type": "json_schema", "json_schema": {"name": "review_analysis", "schema": {"type": "object", "properties": {"summary": {"type": "string"}, "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]}, "confidence": {"type": "number"}}, "required": ["summary", "sentiment", "confidence"]}}}. Это гарантирует 100% совместимость с вашим парсером — никаких сюрпризов в продакшне.
При миграции клиентов мы рекомендуем переходить с JSON Mode на Structured Output для всех продакшн-систем. По нашей статистике, Structured Output снижает количество ошибок парсинга с 2–3% до нуля, а также ускоряет генерацию на 10–15%, потому что модель не тратит токены на «выдумывание» структуры.
Batch API: массовая обработка со скидкой 50%
Если вам не нужен ответ в реальном времени — используйте Batch API. Вы отправляете пакет запросов (до 50 000 за раз), и OpenAI обрабатывает их в течение 24 часов со скидкой 50% от стандартной цены. Через AIAI.BY Batch API работает полностью — мы проксируем запросы с сохранением скидки.
Типичные сценарии для Batch API: ночная обработка документов, генерация описаний для каталога товаров, массовая классификация обращений, перевод большого объёма текстов. Один из наших клиентов — маркетплейс — еженощно обрабатывает через Batch API 15 000 карточек товаров (генерация SEO-описаний и категоризация), экономя около 400 BYN в месяц по сравнению с real-time API.
Пример использования: создайте JSONL-файл с запросами, загрузите его через API файлов, запустите batch-задачу и получите результаты по готовности. Через Python: batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch"); batch = client.batches.create(input_file_id=batch_file.id, endpoint="/v1/chat/completions", completion_window="24h"). Статус проверяйте через client.batches.retrieve(batch.id).
Обработка ошибок и отладка: полный справочник
В демо-проекте ошибки можно игнорировать. В продакшне — нет. Вот что ломается чаще всего при работе с ChatGPT API через AIAI.BY и как это чинить.
HTTP 401 (Unauthorized) — неправильный API-ключ. Проверьте: используете ли вы ключ из личного кабинета AIAI.BY (не ключ OpenAI напрямую), не содержит ли ключ лишних пробелов, не истёк ли он. HTTP 402 (Payment Required) — недостаточно средств на балансе AIAI.BY. Пополните через ЕРИП (зачисление мгновенное) или картой. HTTP 429 (Too Many Requests) — превышен rate limit. Стандартный лимит — 60 RPM (запросов в минуту) и 100 000 TPM (токенов в минуту). Для увеличения лимитов обратитесь в поддержку — мы повышаем их бесплатно для активных клиентов.
HTTP 400 (Bad Request) — ошибка в формате запроса. Самые частые причины: неправильная структура messages (забыли role или content), некорректный tool_call_id в ответе на function call, превышение контекстного окна модели (128K токенов для GPT-5). HTTP 500 / 502 / 503 — временная ошибка на стороне OpenAI. Решение — экспоненциальный retry: import time; for attempt in range(3): try: response = client.chat.completions.create(...); break; except Exception as e: if attempt < 2: time.sleep(2 ** attempt); else: raise.
Ошибка «Connection refused» или таймаут — проверьте, что base_url указан как https://api.aiai.by/v1 (с https, без слеша в конце). Для длинных генераций (более 4000 токенов) увеличьте timeout: client = OpenAI(base_url="https://api.aiai.by/v1", api_key="ключ", timeout=120.0, max_retries=3). Параметр max_retries включает автоматические повторные попытки для временных ошибок (429, 500, 502, 503) — OpenAI SDK обрабатывает их из коробки.
Совет для отладки: включите логирование HTTP-запросов. В Python: import logging; logging.basicConfig(level=logging.DEBUG). Это покажет полные заголовки запроса и ответа, включая x-request-id — его нужно сообщать в поддержку AIAI.BY при обращении по конкретному запросу.
Миграция существующих проектов с прямого OpenAI API
Если у вас уже есть продакшн-система, работающая с OpenAI API через VPN или зарубежный аккаунт, миграция на AIAI.BY занимает от 5 до 30 минут в зависимости от архитектуры. Мы провели более 120 таких миграций за последний год и выработали чёткий чеклист.
Шаг 1: Замените переменные окружения. Вместо OPENAI_API_KEY и OPENAI_BASE_URL (или OPENAI_API_BASE в старых SDK) установите: OPENAI_BASE_URL=https://api.aiai.by/v1 и OPENAI_API_KEY=ваш-ключ-aiai-by. Если ваш код использует OpenAI() без явных параметров, SDK автоматически подхватит новые переменные — менять код не нужно вообще.
Шаг 2: Проверьте названия моделей. AIAI.BY поддерживает те же идентификаторы моделей, что и OpenAI: gpt-5, gpt-4o, gpt-4o-mini, gpt-5-mini, o4-mini. Если в вашем коде модель указана строкой — всё заработает сразу. Если вы использовали устаревшие названия (gpt-4-turbo, gpt-3.5-turbo) — замените на актуальные. Полный список доступных моделей — в документации aiai.by/docs.
Шаг 3: Протестируйте все эндпоинты. Помимо /chat/completions проверьте: /embeddings (если используете для RAG или поиска), /audio/transcriptions и /audio/translations (Whisper), /images/generations (DALL-E), /files и /batches (Batch API). Все они поддерживаются. При миграции клиентов мы заметили, что около 15% проектов используют нестандартные эндпоинты (assistants, threads) — они тоже работают.
Шаг 4: Отключите VPN. После переключения на AIAI.BY VPN больше не нужен — запросы идут напрямую с ваших серверов на api.aiai.by без каких-либо гео-ограничений. Это упрощает инфраструктуру и убирает единую точку отказа. Один клиент из Гомеля после миграции сократил среднюю латентность запросов с 2.1 секунды до 1.4 секунды — просто потому, что убрал лишний hop через VPN.
Частая ситуация: проект использует несколько API-ключей OpenAI (например, разные ключи для dev и prod, или ключи для разных команд). На AIAI.BY вы тоже можете создать несколько ключей с раздельной статистикой и лимитами — это удобно для контроля расходов по проектам.
Мониторинг и оптимизация расходов
По статистике AIAI.BY, 60% клиентов переплачивают за AI в первые месяцы использования — не из-за высоких цен, а из-за неоптимального выбора моделей и параметров. Ниже — конкретные техники экономии, проверенные на реальных проектах.
Выбор модели под задачу. GPT-5 (3.60/10.80 BYN за 1M токенов) нужен для сложных задач: анализ длинных документов, генерация кода, многошаговое рассуждение. GPT-4o (0.84/3.36 BYN) — для 70% типовых задач: чат-боты, суммаризация, классификация. GPT-5-mini (0.50/2.00 BYN) — для массовых операций: фильтрация обращений, генерация коротких ответов, извлечение сущностей. Переключение между моделями — замена одной строки model="..." в запросе. Тестируйте бюджетные модели на ваших задачах — в 80% случаев разница с GPT-5 незаметна для конечного пользователя.
Бюджетные лимиты. В личном кабинете AIAI.BY установите месячный лимит расходов — API автоматически перестанет принимать запросы при достижении порога. Это защита от неприятных сюрпризов: бесконечный цикл в коде, DDoS-атака на ваш чат-бот, или просто неожиданный рост трафика. Рекомендуем устанавливать лимит в 150% от ожидаемого бюджета.
Оптимизация промптов. System prompt отправляется с каждым запросом и оплачивается каждый раз. Если ваш system prompt содержит 2000 токенов и вы делаете 10 000 запросов в месяц — это 20M входных токенов только на системные инструкции. Сократите system prompt до минимально необходимого (обычно 200–500 токенов достаточно). Используйте параметр max_tokens для ограничения длины ответа — если вам нужно 2–3 предложения, установите max_tokens=200 вместо значения по умолчанию.
Кэширование. Если одинаковые вопросы задаются часто (типичный FAQ-бот), кэшируйте ответы на вашей стороне. Redis с TTL 1 час для top-100 вопросов может сократить расходы на API на 30–50%. Для Claude также доступно prompt caching на уровне API — AIAI.BY поддерживает его прозрачно.
Мониторинг в реальном времени. В личном кабинете AIAI.BY доступна детальная аналитика: расход по моделям, по дням, по API-ключам, средняя стоимость запроса, распределение входных и выходных токенов. Если вы видите, что средний ответ содержит 800 токенов, а вам нужно 200 — это сигнал оптимизировать промпт или добавить max_tokens. По нашему опыту, 15 минут анализа дашборда раз в неделю экономят 20–30% бюджета.
Продакшн-чеклист: 10 пунктов перед запуском
Мы составили этот чеклист на основе 120+ миграций и внедрений. Каждый пункт — реальная проблема, с которой сталкивались наши клиенты в продакшне.
1. API-ключ хранится в переменных окружения, а не в коде (никогда не коммитьте ключи в git). 2. Установлен timeout (рекомендуем 60–120 секунд) и max_retries (рекомендуем 3). 3. Реализована обработка всех HTTP-ошибок (401, 402, 429, 500) с логированием. 4. Для интерактивных интерфейсов включён streaming. 5. Установлен max_tokens для ограничения стоимости одного запроса.
6. Настроен budget limit в личном кабинете AIAI.BY. 7. System prompt оптимизирован по длине (не более 500 токенов для типовых задач). 8. Для ответов, требующих парсинга, используется Structured Output (JSON Schema). 9. Реализовано кэширование для повторяющихся запросов. 10. Настроен мониторинг: алерты при ошибках 402 (закончился баланс) и 429 (превышен rate limit).
Прохождение этого чеклиста занимает 1–2 часа, но защищает от проблем, которые в продакшне стоят дни простоя и тысячи рублей.
Вопросы, которые задают разработчики
«Будут ли работать Assistants API и Threads?» — Да, AIAI.BY полностью проксирует Assistants API, включая создание ассистентов, потоки сообщений, code interpreter и file search. Используйте те же методы SDK: client.beta.assistants.create(), client.beta.threads.create(), client.beta.threads.runs.create().
«Поддерживается ли Whisper (Speech-to-Text)?» — Да. Эндпоинт /audio/transcriptions работает. Отправляйте аудиофайлы (mp3, wav, m4a, до 25 MB) через client.audio.transcriptions.create(model="whisper-1", file=audio_file). Результат — текстовая транскрипция с опциональными timestamps.
«Могу ли я использовать один API-ключ AIAI.BY для доступа к моделям Claude, Gemini и DeepSeek?» — Да, это одно из ключевых преимуществ. Через тот же base_url и api_key вы можете обращаться к 50+ моделям, просто меняя параметр model: «claude-sonnet-4-5», «gemini-3-pro», «deepseek-v3-2». Формат запроса для всех моделей одинаковый — OpenAI-совместимый.
«Какой SLA у AIAI.BY?» — Uptime за последние 12 месяцев — 99.93%. Мы не кэшируем и не модифицируем ответы моделей. Для enterprise-клиентов доступен выделенный endpoint с гарантированным SLA 99.95% и приоритетным rate limit.