Справочник API

Перевод версии 3.29.2. Основная версия документации — английская (переключатель EN вверху страницы). Если данные в переводе и в английской версии расходятся, верна английская.

Модели ChatGPT (16.10.2026): 12 новых ID chatgpt-* для POST /v1/chat/completions — семейства GPT-6, GPT-5.6, GPT-5.3 со встроенным веб-поиском. Добавьте -search к базовому ID (например, chatgpt-gpt-6-mini-search) для включения веб-поиска. Цены соответствуют официальным ставкам OpenAI API. chatgpt-research — автономный deep research. Подробнее в разделе GPT ниже.

Claude 5.5 — совместимость API (18.10.2026): claude-opus-5-5 и claude-sonnet-5-5 сохраняют ID, тарифы и клиентские скидки. Эти модели поддерживают текст, изображения на входе, стриминг и полный цикл автоматических вызовов функций, включая параллельные. thinking_level: low, medium, high (по умолчанию High). Заявленный контекст — 1M токенов, выход — до 128K; фактическая проверка контекста выполнена на 38K входных токенов. Реальные попадания в кэш возвращаются в usage.prompt_tokens_details.cached_tokens и учитываются в стоимости. На текущих активных маршрутах Claude 5.5 гарантированный JSON object/schema недоступен: response_format возвращает 400 до генерации и списания. Просьба вернуть JSON в обычном тексте не гарантирует соблюдение схемы. Принудительный выбор функции на текущих маршрутах Claude 5.5 недоступен и возвращает 400. Параметры не упрощаются молча. API429 не добавляет системный промпт агента или его инструменты.

Gemini 4 Argon (15.10.2026): ID gemini-4-argon, метод POST /v1/chat/completions, обычный ответ и стриминг. Параметр thinking_level: low, medium или high (по умолчанию). Поддерживаются текст, анализ изображений, функции, исполняемые клиентом, и response_format (json_object / json_schema). JSON-стриминг буферизуется до полной проверки JSON и схемы, затем выдаётся в формате OpenAI SSE. Невалидный или обрезанный JSON возвращает 502 без списания API429; невалидная схема — 400 до генерации. Разрешены локальные ссылки в схеме; внешние ссылки и ресурсы $id отклоняются. Встроенные инструменты, видео и сочетание функций с JSON response_format в одном запросе недоступны. Доступ проверяйте своим ключом через GET /v1/models. Токены рассуждения входят в completion_tokens и оплачиваются как выходные. Актуальные цены и скидки — в каталоге API429.

Версия: 3.29.2 | Последнее обновление: 2026-10-18 | Редакция документации: 2026-10-24

Дополнительные текстовые модели (2026-10-13): gemini-3.1-flash-lite, gemini-2.5-flash-thinking и gpt-oss-120b-medium поддерживают чат и стриминг. Проверяйте доступность и разрешения своего ключа через GET /v1/models, используя точные ID. Тарифы и скидки доступны в актуальном каталоге. Скрытые части рассуждений GPT-OSS не добавляются в текст итогового ответа.

Названия моделей изображений: в документации и на сайте каждая модель изображений указана один раз — по техническому ID, а понятное название приведено в скобках. Названия Nano Banana — это алиасы для совместимости, а не отдельные модели. Существующие вызовы API и записи для совместимости в /v1/models для аутентифицированных пользователей не изменились.

GPT-6 Astra: gpt-6-astra поддерживает текст и изображения, стриминг, reasoning и строгий JSON. Для инструментов, которые выполняются на стороне клиента, включая асинхронные вызовы функций, используйте /v1/responses. Хостинговые инструменты OpenAI, управление через WebSocket и режимы Fast/Flex на этом маршруте не включены. Подробнее — в разделе о GPT ниже.

GPT-6.1 Sol (2026-09-30): используйте gpt-6.1-sol; короткий gpt-6.1 — его псевдоним. Из GPT-6.1 доступен только уровень Sol: gpt-6.1-luna, gpt-6.1-astra и gpt-6.1-terra недоступны. Уровень рассуждения — от low до max (без none); для инструментов используйте /v1/responses.

GPT-6 Sol и Luna (2026-09-23): используйте точные ID gpt-6-sol и gpt-6-luna. Перед использованием проверьте GET /v1/models для своего токена. Опубликованного ID gpt-6-terra нет; gpt-5.6-terra по-прежнему доступна.

Уточнение о ценах (2026-09-06): числовые таблицы здесь — базовые и конфигурационные ориентиры API429, а не актуальная официальная цена поставщика и не персональная розничная цена. Стандартные розничные цены API429, условия и тарифы кеша берутся из каталога в рантайме. Базовые тарифы GPT-5.6 не изменились; текущие промоцены OpenAI на Sol/Terra ниже. Не рассчитывайте на универсальную экономию 70% относительно сегодняшней цены поставщика.

Актуальные модели Gemini Flash (2026-09-03): gemini-3.8-flash — последняя стабильная модель Flash, опубликованная API429. gemini-3.7-flash по-прежнему поддерживается. Примечания к релизам ниже описывают прошлые релизы, а не доступ конкретного токена.

Проверяйте доступ с тем же ключом и эндпоинтом: публичный каталог на сайте общий для всей платформы; GET /v1/models фильтруется по токену, с которым выполнен запрос, и по доступным сейчас маршрутам обслуживания. У старого токена может быть явный allowlist моделей, в который новые модели не добавляются автоматически. Отсутствие модели в каталоге токена само по себе не повод повышать тариф. Попросите поддержку проверить права токена на модели, а затем обновите каталог.

Если модель из списка возвращает not supported: повторите проверку каталога с тем же токеном и базовым URL, что и при генерации, и используйте точный канонический ID модели. Эта ошибка также может означать, что allowlist токена не включает модель. Отправьте в поддержку ID модели, эндпоинт, время запроса и trace_id (или только последние четыре символа токена) — никогда не отправляйте токен целиком. Не повторяйте запросы при постоянном ограничении доступа и не рассчитывайте, что смена тарифа его снимет.

Что нового в 3.26.0

• Новые модели Gemini TTS: gemini-3.8-flash-tts, gemini-3.8-flash-lite-tts и gemini-2.5-flash-preview-tts доступны на POST /v1/audio/speech вместе с gemini-3.1-flash-tts-preview. См. «Синтез речи».
• Распознавание речи: новый OpenAI-совместимый POST /v1/audio/transcriptions с моделью gemini-3.5-transcribe — форматы json, text, verbose_json (сегменты с метками спикеров, таймкоды слов), srt и vtt. См. «Распознавание речи».

Что нового в 3.25.0

• Eleven v4 и v4 Turbo: eleven_v4 и eleven_v4_turbo, новейшие речевые модели ElevenLabs (вышли 2026-09-28, 90+ языков), доступны на POST /v1/audio/speech и выводятся в GET /v1/models. eleven_v3 по-прежнему доступна без изменений. См. «Модели ElevenLabs».

Что нового в 3.24.0

• Расширенный текстовый каталог: Kimi (kimi-k3, kimi-k2.7-code), Qwen (qwen-3.8-max, qwen-3.8-flash), GLM (glm-5.3, glm-5.3-flash, glm-5.2, glm-5-turbo), DeepSeek (deepseek-v4-pro, deepseek-v4.1-flash), MiMo (mimo-v2.5-pro, mimo-v2.5), minimax-m3, hy4-preview и composer-2.5-fast на POST /v1/chat/completions. См. «Расширенные текстовые модели».
• Новые ID Claude, Gemini и Grok: claude-fable-5.1, gemini-3.6-flash и grok-4.5.
• Эти модели принимают только текстовый ввод.

Что нового в 3.23.0

• GPT Image 2.5: gpt-image-2.5-flare (быстрый режим) и gpt-image-2.5-sunburst (режим thinking) доступны на POST /v1/images/generations по фиксированной цене за изображение: $0.053 и $0.211 официально, $0.0159 и $0.0633 по стандартной цене API429. См. «GPT Image 2.5».
• Горизонтальные и вертикальные размеры сохраняют пропорции: на /v1/images/generations значения size:"1536x1024" и size:"1024x1536" теперь дают изображения 3:2 и 2:3 вместо квадратных, а любое другое WIDTHxHEIGHT использует ближайшее поддерживаемое соотношение сторон. Размеры DALL·E и gpt-image-2 не изменились.

Что нового в 3.22.1

• GPT-5.4 / 5.3 / 5.2 выведены из эксплуатации у поставщика: 2026-09-08 OpenAI перестала обслуживать gpt-5.4, gpt-5.4-mini, gpt-5.3-codex и gpt-5.2 через API429. Эти ID по-прежнему принимаются как алиасы для совместимости: gpt-5.4-mini (и gpt-5-mini) разрешаются в gpt-5.6-luna, остальные — в gpt-5.6-terra. Каждый запрос тарифицируется по ставке итоговой модели. Явно перейдите на ID GPT-5.6.
• Доступна gpt-5.6-luna: облегчённый уровень GPT-5.6 теперь работает в Chat Completions и Responses по цене $1.00 / $0.10 / $1.25 / $6.00 за 1M (ввод / кешированный ввод / запись в кеш / вывод).

Релиз GPT-6.1 Sol (2026-09-30)

• gpt-6.1-sol добавлен в публичный каталог; gpt-6.1 — его псевдоним. Цены: $2.00 / $0.10 / $2.50 / $10.00 за 1M (вход / кэш / запись в кэш / выход); при входе свыше 272K — $4 / $0.20 / $5 / $15.
• Остальные уровни GPT-6.1 на этом маршруте отвечают «not supported» и не публикуются.

Релиз GPT-6 Sol/Luna (2026-09-23)

• Канонические gpt-6-sol и gpt-6-luna добавлены в публичный каталог. gpt-6-terra не является доступным ID модели.
• Существующие allowlist токенов не изменились.

Что нового в 3.20.3

• Изображения в Chat Completions: message.images и реальный usage: модель изображений на /v1/chat/completions теперь возвращает картинки в message.images как части image_url (такой формат используют OpenRouter и Vercel AI SDK) в дополнение к markdown data URI, который остаётся в content. usage больше не равен {0, 0, 0}: в нём указаны текстовые токены промпта плюс 1290 за каждое референсное изображение, 1290 за каждое сгенерированное изображение (completion_tokens_details.image_tokens) и image_count. При стриминге отправляются одно событие с изображением, финальный чанк и, если задан stream_options.include_usage, чанк с usage перед [DONE]. Тарификация не изменилась: за каждое сгенерированное изображение. См. «Модели изображений в Chat Completions».
• gemini-2.5-flash-image на /v1/chat/completions снова генерирует изображения: модель теперь работает через путь генерации изображений, как и остальные модели изображений Gemini. Текстовый промпт возвращает сгенерированное изображение, части image_url в последнем сообщении пользователя используются как исходник для редактирования, а запрос тарифицируется по ставке для изображений. Раньше вызов мог вернуть пустой контент (только reasoning-токены) и тарифицироваться как текстовый.
• Без оплаты, если модель изображений не вернула изображение: если модель изображений Gemini отвечает на чат-запрос без изображения и без видимого текста, шлюз возвращает 502 с сообщением The image model returned no image; the request was not billed. вместо платного пустого 200.
• capabilities в GET /v1/models: каждый элемент модели теперь содержит список capabilities (например, ["chat", "image_editing", "image_generation", "vision"]) — те же значения, что публикует публичный каталог. Чтобы выбрать модель для /v1/images/edits, ориентируйтесь на image_editing, а не проверяйте модели платными вызовами. Стандартные поля OpenAI не изменились.
• Алиасы изображений в списке моделей: nano-banana и nano-banana-pro снова отображаются в GET /v1/models (Google обслуживает их как gemini-2.5-flash-image / gemini-3-pro-image). nana-bana-pro и выведенные из эксплуатации gemini-3-pro-image-preview / gemini-3.1-flash-image-preview по-прежнему принимаются как алиасы для совместимости, но в списке не отображаются.
• Совместимость Gemini 3.5 Flash: gemini-3.5-flash-low, -medium и -high остаются алиасами gemini-3.5-flash по той же цене. Для управления рассуждением используйте thinking_level (low / medium / high). gemini-3.5-flash-low больше не выводится в GET /v1/models.
• Уведомления о недоступности модели: ответ, содержащий только уведомление о снятии модели, считается ошибкой и не оплачивается.

Что нового в 3.20.2

• Доступ к музыке для клиентов: новые активные токены external_customer по умолчанию получают асинхронные скоупы video и audio. Существующие клиентские и проектные токены обновляются, только если у них сохранена управляемая политика API429.
• Доступ к музыке: чтобы токен с ограниченным allowlist моделей мог генерировать музыку, в allowlist должна входить lyria-3-pro-preview.

Что нового в 3.20.0

• Генерация музыки Lyria 3 Pro: добавлена lyria-3-pro-preview через надёжный асинхронный API POST /v1/music/generations.
• Песни и инструментальные треки: в промпте можно указать жанр, настроение, аранжировку и структуру; при необходимости передайте текст песни или запросите только инструментальную версию. Результат — MP3, доступный по HTTPS URL.
• Безопасные платные запросы: Idempotency-Key обязателен, задания никогда не перезапускаются автоматически после неопределённого результата у поставщика, а каждая готовая песня стоит $0.08.

Что нового в 3.19.0

• Gemini 3.8 Flash GA: добавлен точный канонический ID модели gemini-3.8-flash, общедоступной с 2026-09-02. API429 предоставляет её как с аутентификацией по клиентскому токену, так и через Service Account.
• Контекст и reasoning: окно ввода 1,048,576 токенов, лимит вывода 65,536 токенов и уровни reasoning low / medium / high, по умолчанию medium.
• Только канонические запросы: не добавляйте к ID модели -non-thinking или суффиксы уровня усилий. Пользовательские temperature, top_p, top_k и n / нативный candidateCount не поддерживаются.
• Строгая валидация запросов: генерация должна заканчиваться непустым текстовым сообщением пользователя; сообщения с предзаполнением ответа модели отклоняются. Нативным частям FunctionResponse нужны и ID вызова, и имя функции.
• Промоцены: $0.75 за ввод, $0.075 за кешированный ввод и $3.75 за вывод (включая thought-токены) за 1M токенов до 2026-12-31. В 2027 году цены удвоятся до $1.50 / $0.15 / $7.50, и до 2027-01-01 потребуется обновить цены.

Что нового в 3.18.0

• Gemini Omni 1.1 Flash: используйте стабильный клиентский ID модели gemini-omni-1.1-flash. Выведенный из эксплуатации gemini-omni-flash-preview и короткое написание gemini-omni-flash остаются алиасами для совместимости, которые принимаются только во входящих запросах.
• Новые параметры Omni: к 720p добавлены 360p, 1080p и 4k, интерполяция по первому и последнему кадру и продление исходного видео.
• Тарификация видео с учётом разрешения: для резервирования и fallback-расчёта usage в Omni используется опубликованный Google тариф за токены для запрошенного разрешения; если поставщик возвращает нативный usage, приоритет у него.
• Безопасный доступ к видео по умолчанию: активные токены внешних клиентов по умолчанию получают только асинхронный скоуп video. Асинхронные скоупы для текста, изображений и аудио по-прежнему включает администратор явно.
• Единая тарификация нативного TTS: речевые запросы Gemini generateContent, включая запросы с несколькими спикерами, теперь используют ту же предварительную проверку баланса по символам и однократное списание за успешный запрос, что и /v1/audio/speech.

Что нового в 3.17.0

• Исправлен контракт Gemini TTS: gemini-3.1-flash-tts-preview — актуальная речевая модель Gemini в обоих TTS-интерфейсах API429. ID моделей Cloud TTS больше не представлены как модели Gemini generateContent.
• Медиа без потерь при обмене: принимаются стандартный и URL-safe base64; шлюз возвращает канонический стандартный base64 с паддингом.
• Контракт ответа для изображений: response_format:"url" всегда возвращает url (с fallback на data URI), фактический MIME ответа сохраняется.
• Уточнена тарификация по разрешению: точные цены Gemini Flash и Pro указаны для 1K, 2K и 4K, включая стандартные цены API429 со скидкой.

Что нового в 3.16.0

• Фирменный эндпоинт: API теперь опубликован по адресу https://gateway.api429.com. Прежний адрес продолжает работать; миграция не требуется.

Что нового в 3.16.0

• Клонирование голоса: загрузите запись в POST /v1/audio/voices и передайте полученный id как voice в POST /v1/audio/speech. Голос доступен только ключу, который его создал. Тарифицируется посимвольно, как любой другой синтез; регистрация голоса бесплатна.
• Каталог голосов: GET /v1/audio/voices возвращает публичные голоса, которые принимает модель, с фильтрацией по language и q. Добавьте scope=mine, чтобы получить свои клонированные голоса.
• voice обязателен для fish-s2.1-pro: значения по умолчанию нет. Если параметр не передан или вместо 32-символьного id передано имя голоса, возвращается 400 — неверный голос никогда не подменяется молча.

Что нового в 3.15.0

• Дополнительный каталог медиа: отдельный набор моделей для изображений, редактирования и видео, которые включаются для аккаунта по запросу, а не доступны по умолчанию: Midjourney, FLUX.1, Qwen Images, Sora Images, DALL·E 3, замена одежды и видео (Veo, Kling, Pika, замена лица, апскейл). Цены по запросу.
• Пакеты Midjourney: генерация по умолчанию возвращает все 4 изображения задания (оплата взимается за задание, а не за каждое возвращённое изображение); чтобы получить меньше, явно передайте n. Параметры size/aspect_ratio на уровне запроса игнорируются — используйте --ar внутри prompt.
• Модификации Midjourney: каждое сгенерированное изображение возвращает id; передайте его как source_image_id вместе с mj-upscale, mj-upscale-creative, mj-outpaint-*, mj-variations-subtle, mj-variations-strong или mj-remix, чтобы обработать это изображение.

Что нового в 3.14.0

• Fish Audio TTS: новая fish-s2.1-pro на POST /v1/audio/speech — более 80 языков, большая публичная библиотека голосов, $0.015 / 1K символов официально ($0.0045 после стандартной скидки 70%).
• Форматы вывода: fish-s2.1-pro учитывает response_format — mp3 (по умолчанию), wav, pcm, opus. Используйте wav, если потребителю нужен RIFF/WAVE.
• Длинное озвучивание: длинный текст разбивается по границам предложений, синтезируется параллельно и возвращается одним склеенным клипом. Час речи синтезируется примерно за три минуты; opus склеить нельзя, поэтому для длинного текста он возвращает 400.
• Выдача по ссылке: передайте "delivery": "url" в /v1/audio/speech, чтобы получить JSON-дескриптор со ссылкой на CDN вместо байтов аудио. Если параметр не передан, ответ с сырыми байтами не меняется.

Что нового в 3.13.0

• Grok 4.6: добавлен точный канонический ID модели xAI grok-4.6 после того, как проверки в продакшене подтвердили работу текста, vision, reasoning, function calling, структурированного вывода, Chat Completions и Responses API.
• Reasoning: reasoning_effort принимает low, medium, high или xhigh; если параметр не передан, используется значение xAI по умолчанию high. Отключить reasoning нельзя.
• Точный usage и тарификация: кешированный ввод и reasoning-токены сохраняются и оплачиваются один раз. Официальные стандартные тарифы: $2 за ввод / $0.50 за кешированный ввод / $6 за вывод за 1M при вводе меньше 200K токенов и $4 / $1 / $12 начиная с 200K токенов ввода — до скидок API429.
• Инструменты с закрытым по умолчанию доступом: локальные function tools поддерживаются. Отдельно тарифицируемые инструменты xAI для веб-поиска, X и выполнения кода не предоставляются, пока не появится учёт по каждому вызову.

Что нового в 3.12.0

• Gemini 3.7 Flash: добавлена стабильная модель gemini-3.7-flash с окном ввода 1,048,576 токенов, лимитом вывода 65,536 токенов, мультимодальным вводом и текстовым выводом. О последней опубликованной модели Flash см. примечание об актуальных моделях выше.
• Подтверждённая доступность: проверка в продакшене подтвердила канонический ID. API429 публикует только gemini-3.7-flash; суффиксы уровня усилий, специфичные для поставщика, не входят в публичный API.
• Текущие промоцены: $0.75 за ввод, $0.075 за кешированный ввод и $3.75 за вывод за 1M токенов до 2026-12-31. Google объявила цены $1.50 / $0.15 / $7.50 с 2027-01-01.
• Параметры для совместимости: клиенты OpenAI могут передавать temperature, top_p, top_k и thinking_budget; API429 удаляет эти неподдерживаемые параметры перед отправкой. Используйте thinking_level или reasoning_effort со значением low, medium или high (по умолчанию medium).

Что нового в 3.11.0

• Nano Banana Pro в GA: используйте канонический ID gemini-3-pro-image. Выведенный из эксплуатации ID gemini-3-pro-image-preview и понятные названия nano-banana-pro / nana-bana-pro по-прежнему принимаются как алиасы для совместимости и заменяются перед запросом к Google.
• Повторный аудит каталога моделей: каждая таблица Available Models (текст, GPT, Claude, изображения, видео, TTS) сверена с актуальными ценами; другие ID и цены не изменились.

Что нового в 3.10.0

• Единая модель ElevenLabs: семейство ElevenLabs теперь представлено одной канонической моделью elevenlabs-gen, которая указана в GET /v1/models по цене $0.100 / 1K символов официально ($0.030 после стандартной скидки 70%). Запросы оплачиваются по тарифу elevenlabs-gen.
• Старые ID по-прежнему принимаются: eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5 и api429-tts продолжают маршрутизироваться для обратной совместимости, но больше не указываются в каталоге; в новых интеграциях используйте elevenlabs-gen.

Что нового в 3.9.0

• Claude Opus 5 и Claude Fable 5: claude-opus-5 и claude-fable-5 доступны для чат-нагрузок Claude. Обе модели указаны в таблице цен Claude ниже и обслуживаются через стандартную цепочку поставщиков Claude.
• Оплата ElevenLabs: запросы оплачиваются по тарифу запрошенной модели.
• Общий алиас ElevenLabs: api429-tts запрашивает синтез речи ElevenLabs без привязки к конкретной модели; он разрешается в текущую модель по умолчанию (eleven_multilingual_v2).
• Исправление по Gemini TTS: прежнее развёртывание нескольких моделей заменено. Актуальная модель Gemini TTS на /v1/audio/speech и в нативном шлюзе Gemini — gemini-3.1-flash-tts-preview.
• Фильтр контента: если текст для TTS отклонён фильтром контента речевого поставщика, теперь возвращается 422 с указанием числа заблокированных фрагментов вместо общей ошибки.
• Варианты Gemini с фиксированным уровнем reasoning: gemini-3.5-flash-low и gemini-3.1-pro-low задокументированы и тарифицируются по ставке базовой модели.
• Очистка каталога: GET /v1/models содержит поддерживаемые публичные ID. Для новых интеграций используйте документированные канонические ID.

Что нового в 3.8.0

• ElevenLabs TTS: добавлены eleven_v3, eleven_multilingual_v2 и eleven_flash_v2_5 на OpenAI-совместимом эндпоинте POST /v1/audio/speech.
• Нативные голоса: передавайте voice_id ElevenLabs через стандартное поле voice; запрошенная модель ElevenLabs сохраняется на всём пути запроса.
• Прозрачные цены: в каталоге указаны официальная цена ElevenLabs за символы и стандартная цена API429 после скидки 70%.

Что нового в 3.7.0

• Видео Gemini Omni Flash: добавлена нативная генерация gemini-omni-flash-preview через асинхронный API /v1/videos/generations. Принимаемый алиас для совместимости — gemini-omni-flash.
• Мультимодальные сценарии для видео: поддерживаются text-to-video, image-to-video, reference-to-video, редактирование исходного видео и последовательное редактирование с сохранением состояния через previous_job_id.
• Usage и тарификация: завершённые задания Omni показывают нативный usage по токенам ввода, вывода и thought-токенам, если Google их предоставляет, а итоговое списание пересчитывает первоначальный резерв по возвращённому usage.
• Целостность модели: запросы Omni не перенаправляются молча на Veo или другую видеомодель. Доступность для своего токена проверяйте в GET /v1/models.

Что нового в 3.6.0

• Семейство GPT-5.6: добавлены gpt-5.6 (алиас gpt-5.6-sol), gpt-5.6-sol и gpt-5.6-terra для Chat Completions и Responses API.
• Reasoning: GPT-5.6 поддерживает none, low, medium, high, xhigh и max; по умолчанию — medium.
• Usage и тарификация: usage по чтению и записи кеша сохраняется, запросы со стримингом тарифицируются по финальному событию usage, а для запросов более 272K токенов ввода действуют опубликованные тарифы для длинного контекста.
• Доступность: gpt-5.6-luna на момент запуска была недоступна; она указана в списке начиная с 3.22.1. Авторитетный каталог для каждого токена — GET /v1/models.

Что нового в 3.5.10

• Nano Banana 2 Lite (gemini-3.1-flash-lite-image / nano-banana-2-lite) теперь доступна на POST /v1/images/generations.
• Цены: генерация изображений Lite тарифицируется по $0.0336 за 1K выходного изображения; пакетные задания с изображениями используют пакетную единицу $0.0168.
• Алиас для совместимости: nano-banana-2-lite принимается как алиас gemini-3.1-flash-lite-image.

Что нового в 3.5.9

• Claude Sonnet 5 (claude-sonnet-5 / claude-sonnet-5.0) теперь доступна для чат-нагрузок Claude через стандартную цепочку поставщиков Claude.
• Цены и контекст: Sonnet 5 указана по цене $2 за ввод / $10 за вывод за 1M токенов в текущий период стартовых цен и поддерживает контекстное окно 1M токенов.
• Примечание о доступности: Sonnet 5 доступна через текущие маршруты Claude в шлюзе; детали маршрутов конкретных поставщиков намеренно не входят в публичный контракт.

Что нового в 3.5.8

• Anthropic-совместимый Messages API: задокументирован POST /v1/messages для клиентов Claude, которые уже используют формат официального Anthropic Messages API. Используйте аутентификацию x-api-key и тот же клиентский токен API429.
• Прозрачный usage Claude: уточнены поля usage.input_tokens / usage.output_tokens в нативных ответах Messages и prompt_tokens / completion_tokens в OpenAI-совместимых ответах.
• Нативный стриминг Claude: задокументирован порядок SSE-событий Anthropic для stream:true на /v1/messages.
• Примечания о кеше и веб-поиске Claude: задокументирован текущий публичный контракт для полей usage prompt cache и сквозной передачи серверных инструментов Anthropic.

Что нового в 3.5.7

• Модели Grok: добавлены текстовые модели xAI Grok — x-ai/grok-4, x-ai/grok-4-reasoning, x-ai/grok-3, x-ai/grok-3-reasoning — на стандартном эндпоинте POST /v1/chat/completions.
• Расширенный текстовый каталог: теперь можно выбрать дополнительные чат-ID с префиксом поставщика — openai/gpt-5, openai/gpt-5-instant, openai/gpt-5-thinking, а также google/gemini-3-pro, google/gemini-2.5-pro, google/gemini-2.5-flash.
• Новые модели изображений: в POST /v1/images/generations добавлены nano-banana-2 (алиас gemini-3.1-flash-image), api429-image, gpt-image-1 и grok-image (xAI Aurora).
• Проверяйте доступность через GET /v1/models с тем же токеном и базовым URL, что и при генерации. Ответ отражает права на модели и доступность обслуживания, а не автоматическое обещание доступа после смены тарифа.

Что нового в 3.5.6

• Видео на входе в чате Gemini: текстовые маршруты Gemini с доступом по токену теперь принимают видео на POST /v1/chat/completions через OpenAI-совместимые части контента сообщения.
• Поддерживаемые форматы видео на входе: input_video с данными в base64 и прямые video_url, которые шлюз временно размещает у себя перед отправкой в Gemini.
• Поддержка стриминга: stream:true работает для чат-запросов с видео на входе и возвращает стандартные OpenAI-совместимые SSE-чанки.

Что нового в 3.5.5

• Генерация видео Veo 3.1: добавлена документация по асинхронной генерации видео для veo-3.1-generate-001, veo-3.1-fast-generate-001 и veo-3.1-lite-generate-001.
• Нативные пути миграции: клиенты могут использовать маршрут в стиле API429/OpenAI /v1/videos/generations или Vertex-совместимые маршруты predictLongRunning / fetchPredictOperation, изменив только базовый URL и токен.
• Тарификация видео: задокументированы посекундные прайс-листовые цены Veo 3.1 и поведение асинхронного опроса.

Что нового в 3.5.4

• Gemini 3.5 Flash (gemini-3.5-flash) теперь входит в публичный текстовый каталог Gemini. Модель поддерживает чат, стриминг, мультимодальный ввод, функции и инструменты, структурированный вывод, grounding через поиск, выполнение кода и thinking. Вывод — только текст.
• Цены: gemini-3.5-flash тарифицируется по текстовому тарифу Google Standard PayGo Global: $1.50 за ввод / $9.00 за вывод за 1M токенов. Для генерации изображений, TTS и эмбеддингов используются отдельные ID моделей.

Что нового в 3.5.3

• Самодостаточная клиентская документация: удалены ссылки на отдельные руководства .md, которые не публикуются. Примеры для GPT Image 2, Claude, TTS, эмбеддингов и мультимодальности теперь находятся в этом справочнике API.
• Очистка публичного контракта Claude: в публичной документации указаны только канонические ID моделей Claude (claude-*).
• Сборник решений для клиентов: добавлены конкретные рекомендации по разбору SSE, редактированию изображений и референсным изображениям, повторам при 429/503, неподдерживаемым полям и несоответствию эндпоинта и модели.

Что нового в 3.5.2

• Аудит публичного каталога моделей: таблицы GPT и Gemini теперь соответствуют текущему каталогу /v1/models, видимому клиентам. Неподдерживаемые устаревшие ID GPT/Codex и preview пользовательских инструментов Gemini с доступом по allowlist больше не указываются как публичные ID моделей.
• Уточнены канонические ID: в новых интеграциях используйте точные ID моделей из этих таблиц. Авторитетным allowlist для каждого токена остаётся GET /v1/models.

Что нового в 3.5.1

• Руководство по GPT Image 2 для клиентов: уточнено, как вызывать gpt-image-2 через эндпоинты Images API429 и как рассчитывается стоимость по текстовому вводу, вводу изображений и выводу изображений.
• Обновление цен GPT Image 2: примечания о тарификации API429 обновлены в соответствии с текущими тарифами OpenAI за токены GPT-Image-2 и официальными примерами калькулятора цены за изображение.

Что нового в 3.5.0

• Обновление каталога Claude: все публичные текстовые модели Anthropic/Claude указаны с каноническими ID моделей, принимаемыми алиасами, контекстными окнами и прайс-листовыми ценами API429.
• Очистка руководства по интеграции Claude: публичная документация теперь описывает только клиентский контракт API (/v1/chat/completions, стриминг и задания).

Что нового в 3.4.0

• GPT Image 2: model:"gpt-image-2" на /v1/images/generations и /v1/images/edits задокументирована как отдельный путь GPT Image, а не как алиас модели изображений Gemini.
• Редактирование и референсные изображения GPT Image: рекомендации для /v1/images/edits и image_generation в Responses теперь охватывают input_image, маски, поддерживаемые параметры вывода, конкретные цены GPT Image 2, а также видимое клиенту поведение повторов и ошибок.

Что нового в 3.3.0

• Обновления стриминга Claude для обычных чат-запросов с stream:true. Текстовые дельты передаются через OpenAI-совместимый SSE. stream:true + tools по-прежнему использует синтетический SSE.

Что нового в 3.2.0

• Необязательные заголовки Claude для длинной генерации в пакетных сценариях для сценаристов и многоходовых диалогах: X-Session-Key для непрерывности диалога и X-Async-Jobs-Optin: true для надёжных заданий при перегрузке. См. «Необязательные заголовки» в разделе о моделях Claude ниже.

Что нового в 3.1.0

• Claude Sonnet 4.5 (claude-sonnet-4-5 / claude-sonnet-4.5) — те же цены, что у 4.6 ($3 / $15 за 1M), контекст 200k, Extended Thinking включён.
• GPT-5.5 (gpt-5.5) — передовая модель OpenAI, $5 / $30 за 1M.
• Gemini 3.1 TTS preview (gemini-3.1-flash-tts-preview) — актуальная речевая модель Gemini в API429.

OpenAI-совместимый шлюз для моделей чата, изображений, синтеза речи и эмбеддингов семейств Gemini, GPT и Claude, а также нативно-совместимые точки входа Gemini и Anthropic для клиентов, которые уже используют эти SDK. Поддерживаются оба формата: Chat Completions и Responses API. Работает с любым клиентом OpenAI SDK (Python, JS, Go, Rust, Ruby, Java, cURL).

Цикл вызова функций Argon

Передавайте OpenAI tools с type: "function". tool_choice поддерживает auto, none, required и стандартный объект с именем объявленной функции. При finish_reason: "tool_calls" ваше приложение исполняет функции. Добавьте в историю полное сообщение assistant, сохранив id и extra_content.google.thought_signature там, где Google её прислал. Затем добавьте для каждого вызова сообщение role: "tool" с соответствующим tool_call_id и результатом функции. Отправьте историю с той же моделью и объявлениями функций, обычно с tool_choice: "auto", чтобы получить итоговый ответ. Стриминг и несколько вызовов в одном ответе поддерживаются: собирайте вызовы по index, сохраняя подписи. API429 сам ваши функции не исполняет. Google может подписать только первый вызов в группе; добавлять подписи самим не нужно.

Для ответа по схеме передавайте, например, {"type":"json_schema","json_schema":{"name":"answer","strict":true,"schema":{"type":"object","properties":{"answer":{"type":"integer","enum":[42]}},"required":["answer"],"additionalProperties":false}}} в response_format. API429 проверяет исходную схему, включая обязательные поля, enum и запрет лишних полей, и убирает целую Markdown-обёртку JSON, если она присутствует в ответе. Повреждённый JSON не исправляется догадками; повторная платная генерация для исправления не запускается. В режиме json_object результат должен быть JSON-объектом.

Studio в браузере и справочник API

Studio — визуальная песочница, а не справочник по эндпоинтам. В ней доступны работа с текстом, генерация одного изображения и TTS с одним спикером с помощью персонального клиентского ключа API429. Список моделей отфильтрован по режимам, которые поддерживает Studio, и по текущему доступу ключа; наличие маршрута в списке не гарантирует его доступность. Генерация видео в интерфейсе Studio пока недоступна. Для произвольных поддерживаемых payload API используйте интерактивный справочник API.

Studio поддерживает elevenlabs-gen с настроенным голосом по умолчанию и выводом в MP3. Выбор голоса Gemini TTS появляется, только если gemini-3.1-flash-tts-preview действительно опубликована и доступна ключу; устаревший пример Gemini этот маршрут не включает.

• Гостевые примеры — это подготовленные демонстрации с явной пометкой; они не вызывают модель и не списывают средства. Голосовое демо объясняет работу плеера, а не воспроизводит выдуманный результат.
• Реальные запуски используют ваш собственный оплаченный баланс. Подключение ключа и получение оценки стоимости бесплатны. Studio не принимает ключ администратора и не предоставляет общий ключ поставщика.
• Перед запуском Studio показывает резерв. Сервер не позволяет превысить показанный максимум, списывает фактическое использование через обычную тарификацию и возвращает неиспользованную сумму. У прямых вызовов API своя тарификация, и лимиты расходов Studio на них не распространяются.
• Лимиты MVP: 2,000 символов в промпте, 1,024 токена вывода для текста, одно изображение 1K, один активный запуск на кошелёк оплаты, 10 допусков в минуту и $5 суммарных резервов в сутки (UTC), не более $1 резерва на запуск. Неудачные допуски не расходуют средства; завершённые неудачные запуски всё равно учитываются в суточной квоте резервов. Ключи проектов делят лимиты кошелька родительского аккаунта. Запросы метаданных дополнительно ограничены для каждого кошелька и процесса.
• Если ответ завершился ошибкой и оплачиваемое использование не зафиксировано, резерв возвращается. При тайм-ауте, обрыве соединения или отсутствии данных учёта запрос откладывается до сверки; это не доказывает, что поставщик прекратил работу. Используйте Проверить запрос и отправьте в поддержку показанный ID запроса. Не запускайте новые генерации и не обновляйте страницу, пока не сохраните этот ID.
• Проверка запроса работает строго в режиме чтения: она не может запустить генерацию, даже если исходный запрос не дошёл до сервера. Неизвестный запрос остаётся неразрешённым, пока вы не проверите его снова или не обратитесь в поддержку. Оценки стоимости используют маршрут цен из каталога для выбранной модели, а интерфейс показывает небольшие списания с точностью до шести знаков после запятой.
• Ваш API-ключ хранится в памяти вкладки и передаётся по HTTPS только в API429 для выполнения запроса; в хранилище браузера он не сохраняется. В Studio нет маркетинговой записи сессий и скриптов аналитики. Тела результатов шифруются на сервере, доступны для повторного просмотра в течение 24 часов, а затем удаляются периодической очисткой. Финансовые записи и ID запросов сохраняются. Обычная обработка на стороне поставщика и журналирование сервиса по-прежнему применяются.

Studio по-русски

Открыть Studio: выберите режим, подключите клиентский ключ из личного кабинета, введите запрос и проверьте резерв перед платным запуском. Технический справочник находится отдельно. Гостевой демопример не обращается к модели. При неопределённом результате используйте «Проверить запрос» и сохраните Trace для поддержки; новый платный запрос автоматически не запускается. Видео пока не включено в интерфейс Studio.

Быстрый старт

Base URL:  https://gateway.api429.com/v1
Auth:      Authorization: Bearer YOUR_API_KEY

Прежний адрес https://hostkey24760.api429.com продолжает работать; в существующих интеграциях ничего менять не нужно. В новых интеграциях используйте https://gateway.api429.com.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Содержание

1. Эндпоинты и матрица аутентификации
2. Аутентификация
3. Текстовые модели (Chat Completions)
4. Responses API
5. Модели GPT
6. Grok и расширенный каталог
7. Модели Claude
8. Модели генерации изображений
9. Эмбеддинги
10. Модели для генерации видео
11. Синтез речи (Text-to-Speech)
12. Практикум по интеграции
13. Files API
14. Использование и баланс клиента
15. Обработка ошибок
16. Ограничения частоты запросов
17. Поддерживаемые SDK

Эндпоинты и матрица аутентификации

Один и тот же базовый хост (https://gateway.api429.com) обслуживает четыре семейства API. Выберите то, которое соответствует вашему SDK.

Эндпоинты со стримингом возвращают text/event-stream (SSE). Payload ошибок приводятся к виду {"error": {"code": ..., "message": ...}}.

Аутентификация

Все OpenAI-совместимые эндпоинты и эндпоинты использования клиента требуют Bearer-токен:

Authorization: Bearer YOUR_API_KEY

Anthropic-совместимый /v1/messages принимает тот же клиентский токен API429 в стандартном заголовке Anthropic:

x-api-key: YOUR_API_KEY

anthropic-version принимается для совместимости с SDK. Шлюз не требует от клиентов закреплять конкретную версию.

Эндпоинты Gemini-native, Vertex Express и Files API принимают заголовок или query-параметр в стиле Google:

x-goog-api-key: YOUR_API_KEY

GET /v1beta/models?key=YOUR_API_KEY

Токены выдаются через панель администратора. Для получения доступа обратитесь к администратору.

Аутентификация через Service Account (SA) также поддерживается для клиентов Google Vertex AI SDK. Инструкции по настройке и примеры см. на отдельной вкладке Руководство по Service Account.

Текстовые модели (Chat Completions)

Доступные модели

Gemini 3.8 Flash вышла в GA. Точный публичный ID — gemini-3.8-flash. Не добавляйте к нему -non-thinking, -low, -medium, -high или другой суффикс уровня reasoning. Входное окно модели — 1,048,576 токенов, лимит вывода — 65,536 токенов. Уровень low, medium или high задается через thinking_level или reasoning_effort; по умолчанию — medium. В Chat/Responses адаптер API429 не поддерживает инструменты для этой модели. Неподдерживаемые инструменты Responses (включая web_search_preview, web_search и file_search) возвращают HTTP 400; такие запросы никогда не обрабатываются молча как чисто текстовые. Для поддерживаемых объявлений функций и URL context используйте нативный Gemini.

Период цен Gemini 3.8. В таблице указаны акционные цены, действующие до 2026-12-31. Кешированный ввод стоит $0.075/1M, а ставка вывода $3.75 включает thought-токены. С 2027-01-01 все три ставки удваиваются: $1.50 за ввод, $0.15 за кешированный ввод и $7.50 за вывод; до этой даты цены нужно обновить.

Параметры запроса Gemini 3.8. Пользовательские temperature, top_p, top_k и n / нативный candidateCount не поддерживаются. Не передавайте их, а не полагайтесь на значение по умолчанию у провайдера. frequency_penalty и presence_penalty по-прежнему допустимы.

Ходы с инструментами в Gemini 3.8. OpenAI-совместимый маршрут отклоняет для этой модели tools, tool_choice, tool_calls в сообщениях assistant и сообщения role:"tool". Если нужен function calling, используйте нативный маршрут Gemini. Нативные запросы поддерживают functionDeclarations, которые выполняет клиент, и urlContext. Search, Maps, File Search, computer use и выполнение кода не входят в текущий контракт API429 для этой модели.

Проверка ходов в Gemini 3.8. Запросы generateContent и OpenAI-совместимые запросы к чату должны заканчиваться ходом пользователя с непробельным текстом; prefill от assistant или model отклоняется. Нативные объекты FunctionResponse должны содержать и идентификатор вызова (call_id или REST-поле id), и name. countTokens принимает историю чата отдельно и учитывает переданные системную инструкцию и объявления функций, а также содержимое сообщений.

Gemini 3.7 Flash остается в GA. Модель принимает на вход текст, изображения, видео, аудио и PDF и возвращает текст. API429 предоставляет только канонический ID gemini-3.7-flash; не добавляйте к нему суффикс уровня reasoning. Более старые записи Gemini 3.0/3.1 в этой таблице по-прежнему являются preview-ID.

Период цен Gemini 3.7. В таблице указаны текущие акционные цены Google для Standard, действующие до 2026-12-31. Кешированный ввод стоит $0.075/1M. Google объявила цены $1.50 за ввод, $0.15 за кешированный ввод и $7.50 за вывод с 2027-01-01.

Параметры запроса Gemini 3.7. Пользовательские temperature, top_p, top_k, n / нативный candidateCount и thinking_budget не передаются провайдеру. Уровень reasoning задается через thinking_level или reasoning_effort в стиле OpenAI: low, medium или high. minimal и отключение thinking не поддерживаются.

Ходы с инструментами в Gemini 3.7. OpenAI-совместимые запросы с tools / tool_choice для этой модели отклоняются: для полного цикла вызова инструмента ей нужны нативные ID вызовов функций и thought signatures. Для function calling используйте нативный маршрут Gemini; обычный чат, структурированный вывод и URL context остаются доступны через OpenAI-совместимый маршрут.

Режим вывода Gemini 3.5 Flash. gemini-3.5-flash принимает на текстовом пути чата текст, изображения, аудио, видео и документы/PDF, но возвращает текст. Для вывода изображений используйте модели изображений, для аудио — TTS-модели, для векторов — модели эмбеддингов.

Цены для длинного контекста. gemini-2.5-pro и gemini-3.1-pro-preview переходят на более высокий тариф, если prompt превышает 200K токенов (примерно 2× базовой ставки и на ввод, и на вывод). Prompt меньше 200K тарифицируется по ставкам из таблицы выше.

Алиасы моделей (краткие имена):

• gemini-3.1-pro → gemini-3.1-pro-preview
• gemini-3-flash → gemini-3-flash-preview

Варианты с фиксированным уровнем reasoning. Эти ID фиксируют бюджет reasoning в момент запроса, а не оставляют выбор модели. Они тарифицируются по ставке базовой модели: суффикс влияет на задержку и глубину, а не на цену.

Варианты с более высоким уровнем (-high, -medium) сейчас недоступны: они не разрешаются у нашего upstream-провайдера. Для полного reasoning запрашивайте gemini-3.5-flash или gemini-3.1-pro-preview либо передайте thinking_level с базовой моделью.

Суффиксы моделей (добавляются к любой совместимой модели):

• -search — включает grounded-поиск в интернете (например, gemini-3.1-pro-search)
• -non-thinking — отключает режим reasoning/thinking (например, gemini-3.1-pro-non-thinking)
• -image-generation — включает вывод изображений inline в моделях, которые умеют генерировать изображения

gemini-3.8-flash и gemini-3.7-flash доступны в API429 только по каноническим ID и отклоняют все эти суффиксы. Чтобы выбрать поддерживаемый уровень thinking для любой из них, используйте thinking_level или reasoning_effort.

Gemini Live API (расширенные возможности)

gemini-3.1-flash-live-preview — двунаправленная аудиомодель со стримингом, которая работает через Live API Google (bidiGenerateContent). Она недоступна через /v1/chat/completions: клиентам нужно использовать нативный протокол Gemini Live. Если вам нужен доступ к Live API, обратитесь к администратору.

Эндпоинт

POST /v1/chat/completions

Тело запроса

Поддержка возможностей по семействам моделей:

Примечания о reasoning:

Для gemini-3.8-flash и gemini-3.7-flash ходы с инструментами поддерживаются только через нативный маршрут Gemini generateContent. OpenAI-совместимый маршрут отклоняет tools, tool_choice и role:"tool", чтобы не терять обязательные для Google ID вызовов функций и thought signatures.

• Поле reasoning_effort (low / medium / high) сопоставляется с нативным бюджетом reasoning каждой модели. В моделях Claude с включенным thinking temperature передавать нельзя — шлюз удаляет этот параметр автоматически.
• Совместимые модели Gemini также поддерживают суффикс -non-thinking в ID модели, который полностью отключает reasoning. Исключения — gemini-3.8-flash и gemini-3.7-flash: их канонические ID принимают только уровни thinking low, medium или high.
• Reasoning-модели GPT принимают суффиксы вроде -high, -low в ID модели как краткую запись reasoning_effort.

Объект сообщения:

{
  "role": "system" | "user" | "assistant",
  "content": "text content"
}

В мультимодальных запросах content может быть массивом частей контента:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this video in one paragraph."},
    {
      "type": "input_video",
      "input_video": {
        "format": "mp4",
        "data": "BASE64_VIDEO_BYTES"
      }
    }
  ]
}

Видео на входе в чате Gemini

Используйте этот вариант, если нужно, чтобы текстовая модель Gemini проанализировала готовое видео и вернула текст. Это не то же самое, что асинхронный раздел Модели генерации видео: там создаются новые видео.

POST /v1/chat/completions

Поддерживается в текстовых моделях Gemini с ID вида gemini-*, доступных для вашего токена, — например, gemini-2.5-flash, gemini-2.5-pro, gemini-3.5-flash, а также в preview-версиях текстовых моделей Gemini, если они отображаются в GET /v1/models для вашего токена.

Поддерживаемые клиентские форматы:

• OpenAI-совместимое расширение чата API429: элемент content[] с type: "video_url" и video_url.url.
• OpenAI-совместимое расширение чата API429: элемент content[] с type: "input_video" и base64 в input_video.data.
• Нативный Gemini: contents[].parts[].fileData.fileUri с mimeType: "video/mp4" или другим поддерживаемым MIME-типом видео.

Клиент использует ту же OpenAI-совместимую структуру запроса, base URL и схему работы с API-ключом. Видео на входе — расширение внутри этой структуры, которое поддерживает API429: API проверяет видео. Некорректные части с видео возвращают 400 с конкретным сообщением об ошибке валидации.

Поддерживаемые OpenAI-совместимые части с видео:

Поддерживаемые форматы: mp4, mov, avi, webm.

Текущие ограничения:

• Максимальный размер исходного видео от клиента — 150 MiB с учетом ограничений конкретного маршрута.
• Максимальное число частей с видео в OpenAI-совместимом запросе: 1.
• Большие видео могут предварительно обрабатываться или сжиматься. Если для обработки нужно несколько частей, запрос отклоняется, а не теряет часть видео молча.
• На совместимом маршруте inline-видео для gemini-3.8-flash исходные видео размером до 30 MB (30,000,000 байт) передаются напрямую как inline-медиа. Сериализованный запрос к модели, включая текст, инструменты и закодированное видео, должен укладываться в 42 MB (42,000,000 байт); иначе шлюз возвращает 413. Это защитные ограничения шлюза, а не лимиты Google.
• Для этой модели файлы большего размера отклоняются. У других видеомоделей свои лимиты.
• По умолчанию обработка inline-видео ограничена лимитом одновременных запросов до завершения ответа или закрытия стрима. Если лимит достигнут, возвращается 429 с Retry-After: 5; используйте ограниченное число повторов с backoff. Действующие лимиты аккаунта и частоты запросов сохраняются.
• Тесты адаптера подтвердили обработку видео примерно 30 MB / 30 секунд со звуком и видео 5 минут / 15.7 MB со звуком в режиме стриминга. Эти синтетические тесты не гарантируют поддержку произвольной длительности, качество звука или задержку; некоторые тесты прямой передачи длились больше двух минут.

Прочее поведение:

• Поддерживаются и stream:false, и stream:true.
• Ответ возвращается текстом. Для вывода видео используйте /v1/videos/generations.
• Эти изменения касаются OpenAI-совместимых входных данных input_video и video_url; нативные ссылки Gemini fileData, переданные клиентом, не переписываются.
• Полные тела видео в base64 удаляются из долговременных логов запросов.

Python (OpenAI SDK, локальное видео)

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

with open("clip.mp4", "rb") as f:
    video_b64 = base64.b64encode(f.read()).decode("ascii")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe what happens in this video."},
            {
                "type": "input_video",
                "input_video": {
                    "format": "mp4",
                    "data": video_b64,
                },
            },
        ],
    }],
    max_tokens=300,
)

print(response.choices[0].message.content)

cURL (прямой URL видео)

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this video in 5 bullets."},
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/videos/clip.mp4",
            "mime_type": "video/mp4"
          }
        }
      ]
    }],
    "max_tokens": 500
  }'

cURL (стриминг)

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this video in one sentence."},
        {
          "type": "input_video",
          "input_video": {
            "format": "mp4",
            "data": "BASE64_VIDEO_BYTES"
          }
        }
      ]
    }]
  }'

Примеры

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in 3 sentences."}
    ],
    temperature=0.7,
    max_tokens=200
)
print(response.choices[0].message.content)

Python (стриминг)

stream = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Write a poem about AI"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Python (мультимодальный ввод в Gemini 3.5 Flash)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize the visual details in this image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
        ],
    }],
    max_tokens=500,
)
print(response.choices[0].message.content)

Python (структурированный вывод в Gemini 3.5 Flash)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "Extract title, date and people from this text."}],
    response_format={"type": "json_object"},
)
print(response.choices[0].message.content)

Python (function calling)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"}
                },
                "required": ["city"]
            }
        }
    }],
    tool_choice="auto"
)

Python (поиск в интернете)

# Append -search to enable grounded web search
response = client.chat.completions.create(
    model="gemini-3.1-pro-search",
    messages=[{"role": "user", "content": "What happened in tech news today?"}]
)

cURL

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

cURL (стриминг)

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.api429.com/v1",
  apiKey: "YOUR_API_KEY",
});

const response = await client.chat.completions.create({
  model: "gemini-3.1-pro",
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 100,
});

console.log(response.choices[0].message.content);

Формат ответа

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gemini-3.1-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Ответ в режиме стриминга (SSE)

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Responses API

POST /v1/responses
POST /openai/v1/responses

OpenAI Responses API — более новая альтернатива Chat Completions. Она возвращает единый объект response, нативно поддерживает инструменты и хранит состояние reasoning. Работает со всеми поддерживаемыми семействами моделей: Gemini, GPT и Claude.

Как это работает для разных семейств моделей

Тело запроса

Формат ввода

Простая строка:

{"model": "gpt-5.3-codex", "input": "Write hello world in Python"}

Многоходовой диалог:

{
  "model": "gpt-5.3-codex",
  "input": [
    {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "What is 2+2?"}]},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "4"}]},
    {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Now multiply by 3"}]}
  ],
  "instructions": "You are a math tutor."
}

С вызовами инструментов:

{
  "model": "gpt-5.3-codex",
  "input": [
    {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Weather in NYC?"}]},
    {"type": "function_call", "name": "get_weather", "call_id": "call_1", "arguments": "{\"city\":\"NYC\"}"},
    {"type": "function_call_output", "call_id": "call_1", "output": "{\"temp\":72,\"condition\":\"sunny\"}"}
  ],
  "tools": [
    {"type": "function", "name": "get_weather", "description": "Get weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}
  ]
}

С изображениями:

{
  "model": "gemini-3.1-pro",
  "input": [
    {"type": "message", "role": "user", "content": [
      {"type": "input_text", "text": "Describe this image"},
      {"type": "input_image", "image_url": "https://example.com/photo.jpg"}
    ]}
  ]
}

Примеры

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

# Simple request
resp = client.responses.create(
    model="gpt-5.3-codex",
    input="Write a Python function to sort a list",
)
print(resp.output_text)

Python (стриминг)

stream = client.responses.create(
    model="gpt-5.3-codex-high",
    input="Explain quantum computing in simple terms",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Python (с инструментами)

resp = client.responses.create(
    model="gemini-3.1-pro",
    input="What is the weather in London?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
        },
    }],
)

for item in resp.output:
    if item.type == "function_call":
        print(f"Call: {item.name}({item.arguments})")

cURL (без стриминга)

curl https://gateway.api429.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "Hello!",
    "stream": false
  }'

cURL (стриминг)

curl -N https://gateway.api429.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "Write a hello world in Rust",
    "stream": true
  }'

Ответ без стриминга

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1712345678,
  "status": "completed",
  "model": "gpt-5.3-codex",
  "output": [
    {
      "id": "msg_def456",
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Here is the code..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 45,
    "total_tokens": 57
  }
}

События стриминга (SSE)

При stream: true сервер отправляет события SSE:

event: response.created
data: {"type":"response.created","response":{"id":"resp_abc","status":"in_progress"},"sequence_number":1}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_1","type":"message","role":"assistant"},"sequence_number":2}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"delta":"Hello","sequence_number":3}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"delta":" world","sequence_number":4}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc","status":"completed","usage":{...}},"sequence_number":10}

data: [DONE]

Типы событий:

Генерация изображений через Responses API

Модели GPT могут генерировать изображения с помощью инструмента image_generation в Responses API. Шлюз выполняет вызов инструмента через отдельный маршрут GPT Image и возвращает изображение в base64.

resp = client.responses.create(
    model="gpt-5.5",
    input="Draw a cute orange cat sitting on a windowsill",
    tools=[{"type": "image_generation"}],
)

for item in resp.output:
    if item.type == "image_generation_call":
        import base64
        with open("cat.png", "wb") as f:
            f.write(base64.b64decode(item.result))

GPT Image 2

Для задач GPT Image используйте model:"gpt-image-2". Модель обслуживается отдельным маршрутом GPT Image на обоих эндпоинтах:

• POST /v1/images/generations
• POST /v1/images/edits

Если вы используете OpenAI SDK, достаточно направить существующие вызовы Images API на базовый URL API429 и оставить model:"gpt-image-2".

Генерация по тексту:

curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a matte black espresso machine",
    "size": "1024x1024",
    "quality": "low",
    "response_format": "b64_json"
  }'

Редактирование изображения или генерация по референсу:

curl https://gateway.api429.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Replace the background with a clean white studio backdrop" \
  -F "image=@product.png;type=image/png" \
  -F "size=1024x1024" \
  -F "quality=low" \
  -F "response_format=b64_json"

Для редактирования можно загружать файлы PNG, JPEG и WebP. Запрос может содержать несколько полей формы image и необязательное изображение mask. Прозрачный фон сейчас не поддерживается. Используйте opaque или auto.

Если вы запрашиваете поддерживаемую модель изображений не из семейства GPT и передаёте mask, API429 направляет редактирование в gpt-image-2. В поле model ответа указана фактически использованная модель, а в api429.requested_model — исходно выбранная. Применяются цены GPT Image 2. JSON-запросы к /v1/images/generations со встроенным исходным изображением image (или images / reference_images) в base64/data URI и с mask идут по тому же маршруту редактирования. Удалённые файлы загружайте через multipart. Маска и первое исходное изображение должны быть корректными PNG одинакового размера, а у маски должен быть альфа-канал. Некорректная маска, недоступность генерации изображений и неподдерживаемая прозрачность приводят к ошибке до списания за успешную генерацию. Запросы с маской никогда не переключаются на Gemini в качестве fallback.

Оба эндпоинта — генерации и редактирования — передают дальше size, quality, background, output_format (png, jpeg, webp) и output_compression (0–100). Запрашиваемая модель инструмента — именно gpt-image-2, а не псевдоним Gemini или GPT Image 2.5. Значения xhigh/max и непроверенные ID моделей изображений отклоняются, а не тарифицируются по старому тарифу auto.

Уровень reasoning effort для изображений по умолчанию — medium.

response_format:"url" сейчас возвращает data URI, а не ссылку на скачивание с внешнего хостинга. MIME-тип определяется по сгенерированным байтам. Для интеграций через SDK, которым нужен чистый base64, используйте b64_json. Необязательные метаданные api429.outputs содержат фактические размеры и формат. Все обнаруженные расхождения с запрошенными параметрами указываются в api429.parameter_mismatches. Результат может иметь изображение другого размера. API429 не меняет размер изображения незаметно для вас.

У всех попыток и всех n изображений общий дедлайн (сейчас 250 секунд). При неоднозначном таймауте возвращается 504 без автоматической повторной отправки и без fallback на Gemini. Если запрос с n>1 уже сгенерировал часть изображений, а следующее завершилось ошибкой, готовые изображения возвращаются и оплачиваются, а в api429.warning.code устанавливается partial_image_batch. Прежде чем решать, что повторить, проверьте failed_images.

Поле с файлом может называться image или image[] (это имя используют официальные OpenAI SDK, когда вы передаёте список файлов). Оба варианта принимают несколько файлов, и их можно сочетать в одном запросе.

Тариф API429 на GPT Image 2 — это оценка, а не прямая передача измеренного расхода токенов изображений OpenAI. Действующие цены не меняются: оценка текстового ввода, фиксированный эквивалент высокой детализации за каждое входное изображение или маску и приведённая ниже таблица цен на вывод с множителями по размеру. Если качество не указано или равно auto, применяется тариф high. Эталонные ставки OpenAI за токены, на основе которых рассчитан тариф:

Для удобства: калькулятор изображений OpenAI даёт такие примерные цены на вывод для распространённых размеров GPT Image 2:

Основа тарификации указана в ответе как api429.billing.basis:"api429_estimate". api429.provider_usage отдельно хранит заявленный расход основной модели Responses и расход инструмента изображений. Отсутствующий расход равен null, а не нулю. Выходные токены основной модели не являются выходными токенами изображений. Не используйте эти счётчики как квитанцию о списании с баланса. Цены и скидки за токены по-прежнему применяет действующая система биллинга. Для smoke-тестов и черновиков используйте quality:"low" и размер класса 1024.

Вызовы image_generation через /v1/responses оплачиваются один раз по тому же тарифу GPT Image 2. В прошлых версиях на этом пути раннего возврата списание за изображение не выполнялось. В этом релизе пробел в учёте закрыт. Старые запросы задним числом не списываются. Неудачные вызовы не создают списания за успешное изображение, а заявленный расход основной модели повторно не тарифицируется как расход на вывод изображений.

GPT Image 2.5

gpt-image-2.5-flare и gpt-image-2.5-sunburst генерируют изображения через POST /v1/images/generations. ID модели задаёт режим рендеринга: Flare — быстрый режим, Sunburst — режим с размышлением. Отдельного переключателя quality нет: запрос всегда рендерится в режиме, указанном в ID.

curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer $API429_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A paper boat on a calm lake at sunset",
    "size": "1536x1024",
    "response_format": "b64_json"
  }'

Эти модели не поддерживают: quality, background, output_format кроме PNG, output_compression, mask, moderation и стриминг. Сейчас эти поля игнорируются, а не отклоняются, и результат всегда возвращается в PNG. /v1/images/edits не принимает эти модели. Чтобы передать референсные изображения, отправьте их в images на /v1/images/generations.

Каждое изображение оплачивается по фиксированной цене независимо от размера: Flare — по ставке OpenAI для среднего качества 1024×1024 для GPT Image 2.5 ($0.053, $0.0159 по стандартному тарифу API429), Sunburst — по ставке для высокого качества ($0.211, $0.0633). Индивидуальный профиль биллинга клиента может изменить скидку.

Пакетная генерация изображений Gemini

Пакеты изображений Gemini — это асинхронные задания не в реальном времени для больших объёмов генерации. Публичный процесс отправки повторяет OpenAI-совместимую схему Files + Batch:

curl https://gateway.api429.com/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F purpose="batch" \
  -F file="@batchinput.jsonl"

curl https://gateway.api429.com/v1/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/responses",
    "completion_window": "24h",
    "metadata": {"job": "nightly-image-generation"}
  }'

Официальные OpenAI-совместимые строки Phase 1 направляются на /v1/responses и запрашивают инструмент image_generation:

{"custom_id":"row-000001","method":"POST","url":"/v1/responses","body":{"model":"gemini-3.1-flash-image","input":"studio product photo of a red ceramic mug","tools":[{"type":"image_generation"}]}}

Референсные изображения (редактирование и композиция) передаются через части контента input_image. Встройте изображение как URI data: (base64) или используйте URI gs://. Внешние URL http(s) отклоняются при отправке, потому что batch-воркеры не могут скачать их во время выполнения:

{"custom_id":"row-000002","method":"POST","url":"/v1/responses","body":{"model":"gemini-3.1-flash-image","input":[{"role":"user","content":[{"type":"input_text","text":"replace the mug logo with the one from the reference"},{"type":"input_image","image_url":"data:image/png;base64,iVBORw0KGgo..."}]}],"tools":[{"type":"image_generation"}]}}

/v1/images/generations в batch JSONL — только расширение API429, это не официальный эндпоинт OpenAI Batch. Если вы используете расширение API429 для редактирования изображений, передавайте входные данные через image_url, удобный для JSONL, а не встроенный base64. Официальный эндпоинт Phase 1 — по-прежнему /v1/responses.

Ограничения и поведение пакетов:

Модели GPT

GPT-6 Astra

Указывайте точный ID gpt-6-astra. В продакшене у провайдера проверены текст, ввод изображений, function calling (включая async: true) и строгая JSON-схема. Рекомендуем Responses API. Chat Completions поддерживает диалоги и JSON, но для инструментов нужен Responses.

{"model":"gpt-6-astra","input":"Explain this code briefly.","reasoning":{"effort":"high"}}

Уровни effort: low, medium (по умолчанию), high, xhigh, max. Значения none и minimal не поддерживаются. Не передавайте temperature, top_p и logprobs. Официальные лимиты модели: контекст 1.05M, вход 922K и выход 128K. Действуют также лимиты аккаунта и шлюза. Полное окно под нагрузкой не тестировалось.

Клиентские function/custom tools выполняются в вашем приложении. Сохраняйте элементы вывода и ID вызовов и возвращайте соответствующий результат инструмента. Этот транспорт не поддерживает hosted-поиск по вебу и файлам, генерацию изображений, контейнеры, shell, computer use, MCP, Skills, управление ходом через WebSocket посреди ответа, configuration_update, фоновый режим, явный TTL кэша и тарифы Fast/Flex/priority. Не рассчитывайте, что неподдерживаемая опция работает, только потому, что она описана в документации OpenAI Platform. Astra не поддерживает нативный вывод аудио и видео. Клиенты должны сами обрабатывать события сбоя и безопасности от upstream — автоматического продолжения нет.

Базовая тарификация за 1M токенов (вход / чтение кэша / запись в кэш / выход): $10 / $1 / $12.50 / $50 при входе до 272K; $20 / $2 / $25 / $75 при входе свыше 272K — для всего запроса. Выход включает reasoning. Кэш не учитывается дважды. Действующие скидки API429 применяются. Официальная страница модели, официальные цены.

Все модели семейства GPT (включая подсемейство Codex) доступны через два эндпоинта:

• POST /v1/chat/completions — стандартный формат Chat Completions
• POST /v1/responses — формат OpenAI Responses API (рекомендуется для reasoning-моделей GPT; обязателен для вызова инструментов в Astra)

Шлюз автоматически выбирает нужный путь по ID модели.

Доступные модели

Ниже указаны базовые ставки API429 до скидок. Не все они совпадают с текущими официальными ценами вендора. Новые ставки GPT-6 Sol/Luna соответствуют опубликованным ставкам OpenAI Standard на 2026-09-23. Базовые ставки GPT-5.6 пока не меняются — решение о новых ценах ещё не принято. Фактические стандартные розничные цены смотрите в каталоге в рантайме.

Модели chatgpt-* предоставляют альтернативный маршрут доступа к моделям OpenAI со встроенным веб-поиском. Добавьте -search к ID модели для включения веб-поиска (например, chatgpt-gpt-6-mini-search). Поисковые варианты тарифицируются по той же ставке плюс $10.00 за 1 000 вызовов поиска. Эти модели поддерживают POST /v1/chat/completions со стримингом. Запись в кэш на этом маршруте недоступна. Проверьте доступ для вашего токена через GET /v1/models.

В новых интеграциях используйте точные ID моделей из таблицы. ID для совместимости. gpt-5.6 указывает на gpt-5.6-sol. OpenAI вывела уровень GPT-5.4 / 5.3 / 5.2 для Codex из эксплуатации 2026-09-08. Поэтому gpt-5.4, gpt-5.3-codex, gpt-5.2 и более старые ID для совместимости gpt-5 и gpt-5.1 по-прежнему принимаются от существующих клиентов, но указывают на gpt-5.6-terra и тарифицируются по ставке gpt-5.6-terra. gpt-5.4-mini и gpt-5-mini указывают на gpt-5.6-luna и тарифицируются по ставке gpt-5.6-luna. Явно перейдите на ID GPT-5.6 (или gpt-5.5). ID для совместимости не публикуются как отдельные модели для выбора. Более старые варианты gpt-5*-codex не являются публичными ID моделей, если их нет в ответе GET /v1/models для вашего токена.

Пресеты reasoning effort — используйте reasoning_effort или добавьте суффикс к ID модели:

Все пресеты тарифицируются по той же ставке за токены, что и базовая модель. GPT-6 Sol/Luna и GPT-5.6 принимают все шесть значений. GPT-6.1 Sol и GPT-6 Astra не принимают none. Более старые модели GPT могут поддерживать только часть значений. Для function calling в GPT-6 Sol/Luna используйте /v1/responses. Обе модели поддерживают вызовы функций на стороне клиента.

Запросы GPT-6.1 Sol с входом свыше 272K токенов целиком оплачиваются по $4 / $0.20 / $5 / $15 за 1M (вход / кэш / запись в кэш / выход) (официальная страница GPT-6.1 Sol).

Для запросов GPT-6 Sol/Luna с входом свыше 272K токенов ко всему запросу применяются ставки 2x для входа и кэша и 1.5x для выхода. Ставки за длинный контекст за 1M токенов (вход / кэшированный вход / запись в кэш / выход): $4 / $0.40 / $5 / $15 для Sol и $0.20 / $0.02 / $0.25 / $0.75 для Luna. Это только ставки за токены. Hosted-инструменты и обработка Fast/Flex на этом маршруте шлюза не включены. Официальная страница Sol, официальная страница Luna.

GPT-5.6: тарификация длинного контекста и кэша

Если usage.input_tokens больше 272,000, ставки за длинный контекст применяются ко всему запросу:

Автоматическое кэширование промптов поддерживается. Responses API возвращает использование кэша в usage.input_tokens_details.cached_tokens и cache_write_tokens. Chat Completions возвращает те же значения в usage.prompt_tokens_details. Явные поля управления кэшем на маршруте шлюза GPT сейчас не принимаются. reasoning.mode: "pro" тоже пока недоступен. Для самого глубокого reasoning используйте reasoning.effort: "max". Текущий маршрут шлюза не применяет max_output_tokens. Если вам нужно более строгое ограничение на выход, останавливайте генерацию на стороне клиента.

В запросах Responses к GPT-5.6 можно использовать встроенный инструмент web_search. Каждый web_search_call стоит $10.00 за 1,000 вызовов ($0.01 за вызов), а токены с результатами поиска, переданные модели, тарифицируются по ставке входных токенов выбранной модели. Массив output в ответе содержит элемент web_search_call для прозрачного учёта запроса.

Для клиентов Instructor поддерживается Mode.MD_JSON (markdown_json_mode) как fallback на стороне клиента: Instructor добавляет схему в промпт и сам разбирает JSON-ответ в markdown-блоке. Не передавайте markdown_json_mode как поле запроса к API. По возможности используйте строгий response_format: {"type":"json_schema", ...}.

Responses API (рекомендуется для GPT-5.x)

Модели GPT-5.x нативно поддерживают OpenAI Responses API. Используйте этот эндпоинт, если вам нужны встроенное состояние reasoning и нативные дескрипторы инструментов.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

# Simple request
resp = client.responses.create(
    model="gpt-5.6",
    input="Write a Python quicksort implementation",
)
print(resp.output_text)

# With reasoning effort
resp = client.responses.create(
    model="gpt-5.6-sol",
    input="Find the bug in this code and explain your reasoning",
    instructions="You are a senior code reviewer.",
    reasoning={"effort": "max"},
)
print(resp.output_text)

# Streaming
stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Explain async/await in Python",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Chat Completions (тоже поддерживается)

Примеры

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY"
)

# GPT-5.6 Sol with high reasoning
response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a senior developer."},
        {"role": "user", "content": "Review this Python function for bugs."}
    ],
    reasoning_effort="high",
)
print(response.choices[0].message.content)

Python (стриминг)

stream = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Write a hello world in Rust"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

cURL

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Grok и расширенный каталог

Модели xAI Grok и расширенный набор чат-моделей с префиксом вендора используют тот же Bearer-токен и ту же настройку OpenAI SDK, что и Gemini, GPT и Claude. Всегда передавайте точный ID модели из ответа GET /v1/models для вашего токена.

Grok (xAI)

grok-4.7 — текущий канонический флагман xAI. Модель доступна через POST /v1/chat/completions и POST /v1/responses, включая стриминг. Она принимает на вход текст и изображения и возвращает текст, вызовы функций или структурированный JSON. В Responses API передавайте полный входной контекст: продолжение через previous_response_id на этом маршруте пока не включено.

Выше указаны официальные ставки xAI Standard до скидок API429 и индивидуальных скидок клиента. Если во входе 200,000 токенов или больше, ко всему запросу применяются ставки за длинный контекст: $4 за вход, $1 за кэшированный вход и $12 за выход за 1M токенов. Токены reasoning тарифицируются как выходные.

Используйте reasoning_effort со значениями low, medium, high или xhigh. Если параметр не указан, xAI по умолчанию использует high. Grok 4.7 не принимает stop, presence_penalty и frequency_penalty. Локальные function tools поддерживаются. Hosted-инструменты xAI для веб-поиска, X-search и выполнения кода API429 пока не предоставляет: у них отдельная тарификация за вызов.

Проверено 2 октября 2026 года. Доступ зависит от разрешений вашего ключа: проверьте GET /v1/models.

Дополнительные ID Grok в каталоге

Следующие ID для совместимости с префиксом вендора — отдельные записи каталога. Префикс x-ai/ входит в ID модели.

Расширенные чат-ID с префиксом вендора

Эти ID дают дополнительные уровни GPT и Gemini в дополнение к нативному каталогу выше. Они тарифицируются по таблице ниже и принимают те же параметры чата.

Доступность каждой модели выше зависит от вашего токена. Актуальный список моделей для выбора и текущие цены всегда смотрите в ответе GET /v1/models для вашего токена.

Пример

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "Explain quantum entanglement in two sentences."}],
    reasoning_effort="high",
)
print(resp.choices[0].message.content)

Расширенные текстовые модели

Дополнительные чат-модели от Moonshot, Alibaba, Zhipu, DeepSeek, Xiaomi, MiniMax, Tencent и Cursor, а также новые ID Claude, Gemini и Grok. Они используют тот же Bearer-токен и ту же настройку OpenAI SDK на POST /v1/chat/completions (включая стриминг) и принимают только текстовый ввод. Передавайте точный ID модели из первого столбца.

Цены — официальные ставки вендоров за 1 миллион токенов до вашей клиентской скидки. Кэшированный вход тарифицируется по ставке кэша, если вендор её публикует, иначе — по ставке входа.

Модели Claude

Модели Claude доступны через два публичных API-интерфейса:

В публичных интеграциях используйте канонические ID моделей claude-* из списка ниже.

Если не указано иное, все перечисленные модели Claude поддерживают чат, стриминг, вызов инструментов, веб-поиск и vision (ввод изображений). Vision означает ввод текста и изображений с текстовым выводом. Эти модели не генерируют изображения.

Доступные модели

В ID моделей используются дефисы. Алиасы с точками принимаются для совместимости, но в новых интеграциях передавайте канонический ID модели из первого столбца. Для контекста 1M используйте канонические ID с -1m из таблицы ниже или алиасы Anthropic в квадратных скобках, например claude-opus-4.8[1m]. Ниже указаны прейскурантные цены API429 за 1 миллион токенов до вашей клиентской скидки.

Чтобы узнать, какие именно модели Claude включены для вашего токена, вызовите GET /v1/models со своим API-ключом.

Messages API, совместимый с Anthropic

Используйте этот эндпоинт, если ваш код уже работает с Anthropic Messages API. Тело запроса и тело ответа соответствуют формату Anthropic Messages.

POST https://gateway.api429.com/v1/messages

Обязательные заголовки:

x-api-key: YOUR_API_KEY
content-type: application/json
anthropic-version: 2023-06-01

anthropic-version принимается для совместимости с SDK, его можно не передавать. Если заголовок не указан, API429 передаёт в upstream 2023-06-01.

cURL

curl -X POST https://gateway.api429.com/v1/messages -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -H "anthropic-version: 2023-06-01" --data @payload.json

payload.json:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": "You are a concise technical assistant.",
  "messages": [
    {"role": "user", "content": "Explain Mutex vs RwLock in Rust."}
  ]
}

Ответ

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "..."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 23,
    "output_tokens": 87
  }
}

Нативный стриминг

Передайте "stream": true в /v1/messages, чтобы получать SSE-события в формате Anthropic:

curl -N -X POST https://gateway.api429.com/v1/messages -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -H "anthropic-version: 2023-06-01" --data @payload.json

payload.json:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "stream": true,
  "messages": [
    {"role": "user", "content": "Write a haiku about Rust."}
  ]
}

События приходят в порядке Anthropic:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop

Между событиями с контентом Anthropic может отправлять события ping. Данные об использовании распределены по потоку: message_start содержит использование входа, а message_delta — итоговое использование выхода.

Нативные поля запроса

Нативное использование и тарификация

Нативные ответы возвращают данные об использовании в формате Anthropic:

{
  "usage": {
    "input_tokens": 123,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 45
  }
}

Эти значения также попадают в аналитику использования и биллинг API429. Для запросов к Claude тарифицируемые входные токены считаются так:

input_tokens + cache_creation_input_tokens + cache_read_input_tokens

Тарифицируемые выходные токены — output_tokens. В интерфейсе, совместимом с OpenAI, те же значения возвращаются как prompt_tokens, completion_tokens и, если доступно, prompt_tokens_details.

Если upstream возвращает поля кэша промптов, например cache_creation_input_tokens или cache_read_input_tokens, API429 передаёт их в нативном usage и учитывает в аналитике. Если этих полей нет, клиентам следует тарифицировать и показывать полученные значения input_tokens / output_tokens, а итоговую списанную сумму брать из клиентских эндпоинтов использования.

Веб-поиск для моделей Claude

Модели Claude на этом шлюзе принимают стабильный серверный инструмент Anthropic web_search_20250305. В интерфейсе /v1/messages, совместимом с Anthropic, это нативный контракт tool use Anthropic: модель может вернуть stop_reason: "tool_use" с блоком content типа tool_use, а клиент продолжает цикл инструмента в следующем запросе.

Объявите его так:

{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "Latest Anthropic news?"}],
  "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]
}

Для удобства балансировщик также принимает два неканонических варианта входных данных и автоматически их преобразует:

Шлюз передаёт это объявление серверного инструмента в маршрут Claude. В интерфейсе, совместимом с OpenAI, итоговый ответ по-прежнему имеет формат Chat Completions, а структурированные метаданные цитирования не возвращаются. В интерфейсе Messages, совместимом с Anthropic, проверяйте возвращённые блоки контента tool_use и продолжайте нативный цикл инструмента, когда модель останавливается с stop_reason: "tool_use".

Изменение поведения (2026-04-25): до этого релиза запросы с web_search_preview молча отбрасывались балансировщиком (модель отвечала «I have no real-time access»). Теперь они запускают настоящий веб- поиск, и текст ответа меняется соответственно. Клиентам, которые передавали web_search_preview «на всякий случай», стоит убрать его, если поиск им на самом деле не нужен.

Примеры

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the difference between TCP and UDP."},
    ],
)
print(response.choices[0].message.content)

cURL (vision / ввод изображений)

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image in one sentence."},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,BASE64_IMAGE"}}
      ]
    }],
    "max_tokens": 256
  }'

Python (стриминг, frontier-модель)

stream = client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Write a Python async web scraper"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

cURL (самый быстрый и дешёвый вариант — снапшот Haiku)

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 256
  }'

Необязательные заголовки для пакетных и длительных сценариев с Claude

Два необязательных заголовка полезны для длительных интеграций с Claude. Клиенты, которые их не передают, получают обычное синхронное поведение.

Рекомендуемая комбинация для пакетных клиентов-сценаристов:

curl https://gateway.api429.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-Key: scenario/iceberg/run-001/scene-3" \
  -H "X-Async-Jobs-Optin: true" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Draft scene 3 of the iceberg scenario."}]
  }'

Примечание о стриминге: обычный stream:true для Claude — это SSE с постепенной выдачей токенов. Ответы Jobs API никогда не стримятся. Для надёжности используйте опрос.

Модели генерации изображений

Запросы Nano Banana 2 в нативном API

Для gemini-3.1-flash-image и алиаса -preview обычные запросы generateContent с одним сообщением пользователя и IMAGE в responseModalities возвращают JSON Gemini: candidates[].content.parts[].inlineData. Для одной картинки используйте поддерживаемые размеры и inline-референсы PNG, JPEG или WebP с явным соотношением сторон: до 10 референсов, не более 5 МиБ каждый. Число токенов может быть оценочным; стоимость определяется количеством доставленных картинок и запрошенным разрешением. После неопределённой отправки или принятой задачи API429 не создаёт автоматически вторую платную картинку. При временной недоступности учитывайте HTTP-статус и заголовок Retry-After при повторе.

Доступные модели

В новых интеграциях используйте технические ID из таблицы. Запросы с nano-banana, nano-banana-2, nano-banana-2-lite и nano-banana-pro по-прежнему принимаются для совместимости; это не отдельные модели. Выведенные из оборота ID с -preview и устаревшие варианты написания тоже принимаются там, где они поддерживаются. Публичный сайт скрывает дублирующие алиасы, только если опубликована каноническая модель. Актуальную доступность смотрите в каталоге рантайма. api429-image (api429 image) поддерживает генерацию и редактирование изображений.

Цены Gemini в зависимости от разрешения:

* Стандартные цены API429 учитывают стандартную клиентскую скидку 70%. Индивидуальный профиль тарификации клиента может переопределить эту скидку.

Все модели изображений доступны через один эндпоинт /v1/images/generations. На стороне клиента дополнительные учётные данные не нужны. Для model:"gpt-image-2" запрос идёт по отдельному маршруту GPT Image, а не через семейство моделей изображений Gemini.

Уровни разрешения. Цены в основной таблице моделей указаны для 1K, если в строке не сказано иное. Gemini Flash стоит $0.067 / $0.101 / $0.151 при 1K / 2K / 4K. Gemini Pro — $0.134 / $0.134 / $0.240. У imagen-4 есть уровни Fast / Standard / Ultra ($0.02 / $0.04 / $0.06). FLUX.2-pro тарифицируется по мегапикселям Azure FLUX: первый сгенерированный MP — $0.030, каждый следующий сгенерированный MP — $0.015, каждый MP референса — $0.015. xAI grok-imagine-image стоит $0.020 и при 1K, и при 2K; grok-imagine-image-quality стоит $0.050 при 1K и $0.070 при 2K. Выбирайте aspect_ratio / size с учётом этого.

Лимиты изображений Grok. При HTTP 429 учитывайте Retry-After и ограничивайте число повторов с backoff.

Пример:

curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer $API429_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "Editorial product photo on a clean studio background",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

API изображений xAI сейчас поддерживает text-to-image в 1K или 2K. Он явно отклоняет 4K, референсы, маски, negative_prompt, style и seed, а не отбрасывает их молча. Если важна точность соответствия референсу, используйте модель, для которой описано редактирование изображений.

Формат вывода: шлюз сохраняет MIME-тип тех байтов, которые фактически вернул провайдер, и не помечает каждое изображение как .png. При response_format:"url" у каждого элемента есть url: обычно это URL хостинга или URL вида data:<actual-mime>;base64,…, если загрузчик недоступен или завершился с ошибкой. При response_format:"b64_json" у каждого элемента в b64_json лежит обычный стандартный base64. Возможны PNG, JPEG и WebP, если их поддерживает провайдер.

Эндпоинт

POST /v1/images/generations

Тело запроса

Параметры изображений Google. outputMimeType и personGeneration можно передать на верхнем уровне или внутри imageConfig. Если запрошенный параметр недоступен, запрос завершается ошибкой HTTP 503, а не молча отбрасывает поле. Эти специфичные для Google параметры в запросах к моделям изображений не от Google возвращают HTTP 400.

Запрос вывода 2K / 4K

Все три варианта эквивалентны:

{"model": "gemini-3-pro-image", "prompt": "...", "resolution": "4K"}

{"model": "gemini-3-pro-image", "prompt": "...", "image_size": "4K"}

{
  "model": "gemini-3-pro-image",
  "prompt": "...",
  "image_config": {"image_size": "4K", "aspect_ratio": "16:9"}
}

Через OpenAI SDK:

client.images.generate(
    model="gemini-3-pro-image",
    prompt="...",
    extra_body={"image_size": "4K"},
)

Поддержка 2K / 4K по моделям:

• Балансировщик передаёт запрошенный уровень выбранной модели изображений. Если модель не поддерживает этот уровень, провайдер может вернуть HTTP 400. Мы не понижаем молча уровень среди тех, что модель поддерживает.
• Модели изображений не от Google могут использовать другие нативные параметры размера; см. оговорки ниже.

Оговорки для провайдеров не от Google:

• FLUX.2-pro принимает либо явный size в пикселях (например, "1024x1024", "2048x2048"), либо уровни resolution / image_size / quality. quality:"standard" соответствует 1K, quality:"hd" — 2K, quality:"ultra" — 4K. aspect_ratio учитывается при вычислении размеров из уровня.
• Другие провайдеры изображений не от Google могут использовать другие нативные параметры размера.

Если вашему сценарию обязательно нужен 4K, зафиксируйте в model одну из моделей с поддержкой 4K из списка выше (gemini-3-pro-image, gemini-3.1-flash-image).

Референсы и тарификация Azure FLUX.2-pro

FLUX.2-pro поддерживает до 8 референсных изображений на JSON-эндпоинте генерации изображений. Референсы можно передать через reference_images или через OpenAI-совместимые поля image / images. Референсы сверх первых 8 игнорируются.

Оплата рассчитывается по мегапикселям с округлением вверх:

• сгенерированное изображение: первый MP — $0.030, каждый следующий MP — $0.015;
• каждое референсное изображение: $0.015 за MP с округлением вверх;
• 1 MP считается равным 1024x1024 пикселям.

Пример с двумя референсами:

{
  "model": "FLUX.2-pro",
  "prompt": "Create a premium studio product image using the references",
  "quality": "hd",
  "aspect_ratio": "16:9",
  "reference_images": [
    {"image_url": "https://cdn.example.com/ref-1.png"},
    {"image_base64": "data:image/jpeg;base64,..."}
  ],
  "n": 1,
  "response_format": "url"
}

Редактирование изображений (референсы + промпт редактирования)

Для редактирования и работы с референсами выбирайте gemini-3-pro-image, если важна визуальная точность соответствия исходному изображению. Модели Flash подходят для новых генераций и недорогих черновиков, но для продакшен-редактирования надёжнее Pro.

Чтобы явно использовать Pro со стороны клиента, зафиксируйте model: "gemini-3-pro-image". Старые имена остаются только входными алиасами.

Формат reference_images

В одном массиве можно передавать как структурированные объекты, так и строки с URL:

{
  "reference_images": [
    "https://cdn.example.com/ref_1.jpg",
    {
      "name": "ref_2",
      "image_base64": "<base64-without-data-uri-prefix>",
      "mime_type": "image/png"
    },
    {
      "image_url": "https://cdn.example.com/ref_3.webp"
    }
  ]
}

• Строка обрабатывается как {"image_url": "<string>"}: сервер загружает URL и кодирует содержимое в base64 перед передачей провайдеру.
• В объекте должно быть хотя бы одно из полей image_base64 / image_url. name и mime_type необязательны.
• Входные данные base64 могут быть в стандартном или URL-safe base64, с дополнением или без. API429 проверяет байты и приводит передаваемый и выходной base64 к стандартному base64 с дополнением (+, /, =), поэтому ответ шлюза можно без изменений отправить в следующем запросе на редактирование.
• Таймаут загрузки image_url по умолчанию — 30s. Если загрузка не удалась, возвращается HTTP 400 с исходным сообщением об ошибке.

Примеры

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY"
)

response = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="A futuristic city at sunset, cyberpunk style",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

Python (FLUX)

response = client.images.generate(
    model="FLUX.2-pro",
    prompt="Product photography of a ceramic teapot, studio light",
    n=1,
    quality="hd",
    extra_body={
        "aspect_ratio": "16:9",
        "reference_images": [
            {"image_url": "https://cdn.example.com/ref-1.png"},
        ],
    },
)
print(response.data[0].url)

Python (ответ в Base64)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cute robot reading a book",
    n=1,
    size="1024x1024",
    response_format="b64_json"
)

import base64
image_data = base64.b64decode(response.data[0].b64_json)
with open("robot.png", "wb") as f:
    f.write(image_data)

cURL

curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "A mountain landscape at sunrise",
    "n": 1,
    "size": "1024x1024"
  }'

Формат ответа

{
  "created": 1712345678,
  "data": [
    {
      "url": "https://storage.googleapis.com/generated/...",
      "revised_prompt": "A futuristic city at sunset, cyberpunk style"
    }
  ]
}

С response_format: "b64_json":

{
  "created": 1712345678,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "revised_prompt": "A futuristic city at sunset"
    }
  ]
}

С response_format: "url" в ответе всегда используется поле url. Если загрузка в объектное хранилище недоступна или не удалась, значением будет корректный data URI с фактически возвращённым MIME-типом; шлюз не переключает поле на b64_json молча.

Дополнительные модели медиа

Отдельный каталог, который включается для конкретного аккаунта, а не доступен по умолчанию. Если вы не видите этих моделей в GET /v1/models, у вашего токена нет к ним доступа — попросите нас его включить.

Цены: по запросу. Эти модели тарифицируются по фактической стоимости каждой задачи, а не по фиксированной цене за изображение, поэтому цена зависит от модели, размера, уровня скорости и — для Midjourney — от числа изображений в задаче. Мы называем цену для каждого аккаунта отдельно; фактическое списание всегда видно в /api/client/usage/daily и в журнале запросов.

Модели изображений в Chat Completions

Любую модель изображений Gemini (gemini-2.5-flash-image, gemini-3.1-flash-image, gemini-3-pro-image, …) можно вызвать через POST /v1/chat/completions. Текст сообщений становится промптом; части image_url в сообщениях используются как исходное изображение для редактирования. Для совместимости сгенерированное изображение возвращается в ответе дважды:

{
  "object": "chat.completion",
  "model": "gemini-2.5-flash-image",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "![Generated Image 1](data:image/png;base64,...)",
      "images": [{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}]
    }
  }],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 1290,
    "total_tokens": 1304,
    "completion_tokens_details": {"reasoning_tokens": 0, "image_tokens": 1290},
    "image_count": 1
  }
}

• Для программной обработки читайте поле message.images; content содержит Markdown-разметку для клиентов, которые показывают только текст.
• usage повторяет учёт Google так же, как нативный эндпоинт Gemini: в prompt_tokens — текстовые токены промпта плюс 1290 за каждое референсное изображение, в completion_tokens / completion_tokens_details.image_tokens — 1290 за каждое сгенерированное изображение. image_count — число сгенерированных изображений, по которому тарифицируется запрос.
• Оплата взимается за каждое сгенерированное изображение по ставке image из каталога модели; значения токенов нужны для сверки и отдельно не оплачиваются.
• При stream: true ответ состоит из одного SSE-события с delta.content и delta.images, завершающего чанка и data: [DONE]. Передайте stream_options: {"include_usage": true}, чтобы получить чанк с usage (с пустым choices) перед [DONE].
• Если модель не вернула изображение, запрос завершается ошибкой 502 и не оплачивается.

Генерация изображений

Флаги Midjourney (--ar, --s, --cref, --sref, --ow, …) указываются внутри prompt и передаются без изменений, поэтому референсы и смешивание работают так же, как у провайдера. Поля запроса size / aspect_ratio для этих моделей игнорируются — используйте --ar в промпте.

Задача генерации всегда создаёт 4 изображения, оплачивается задача целиком, и по умолчанию возвращаются все четыре. Передавайте n явно, только если хотите получить меньше, — цену это не снижает.

Параметры FLUX.1

Используйте flux-1 или flux.1 с POST /v1/images/generations. Если параметры не указаны, по умолчанию действуют checkpoint_id=1, sampler_id=1 и steps=20.

curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-1","prompt":"A sunlit botanical illustration of native wildflowers, delicate ink lines and soft watercolor washes","checkpoint_id":5,"sampler_id":6,"steps":25,"style":"3,6,12"}'

Следующие эндпоинты для получения справочных данных требуют аутентификации и не оплачиваются:

• GET /v1/yesai/flux/checkpoints
• GET /v1/yesai/flux/samplers
• GET /v1/yesai/flux/lora/models

LoRA по-прежнему задаётся синтаксисом промпта: <lora:model_id:weight>. Эти параметры не добавляют публичных моделей и не меняют маршрутизацию для Qwen, Nano Banana, Veo или Gemini Omni.

Модификации Midjourney

Каждое сгенерированное изображение возвращается с id. Передайте его как source_image_id вместе с одной из моделей ниже, чтобы выполнить действие над этим изображением. prompt нужен только для mj-remix.

# 1) generate — note the id on each returned image
curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox in the snow --ar 16:9"}'

# 2) upscale the one you liked
curl https://gateway.api429.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "mj-upscale", "source_image_id": "103"}'

source_image_id — это числовой id изображения, а не его URL. Для id, над которым нельзя выполнить действие, возвращается 400, а не молча создаётся что-то другое.

Скорость очереди. По умолчанию генерации и модификации выполняются в очереди relax (1–12 минут). Добавьте "speed": "fast" в любой запрос Midjourney, чтобы использовать быструю очередь (1–3 минуты). Это работает и для моделей модификации mj-*, в названии которых нет указания скорости. speed имеет приоритет над скоростью в алиасе модели, поэтому midjourney-7.0-relax с "speed": "fast" выполняется быстро.

Редактирование изображений

Видео

Видеозадачи выполняются долго: отправьте задачу, затем опрашивайте результат так же, как в других асинхронных медиаэндпоинтах.

Эмбеддинги

POST /v1/embeddings
POST /openai/v1/embeddings
POST /hf/v1/embeddings

OpenAI-совместимый эндпоинт для моделей эмбеддингов Google Gemini.

Один вход

response = client.embeddings.create(
    model="gemini-embedding-001",
    input="Hello world"
)
print(response.data[0].embedding[:5])

Пакет (список входов)

input принимает массив строк — все они обрабатываются за один вызов:

response = client.embeddings.create(
    model="gemini-embedding-001",
    input=["First document", "Second document", "Third document"]
)
for emb in response.data:
    print(emb.index, len(emb.embedding))

Своя размерность вывода

Передайте dimensions, чтобы уменьшить размер вектора. Это полезно для гибридного поиска, индексов ближайших соседей и приложений с ограниченным хранилищем. Поддерживаемые значения для gemini-embedding-001: 128, 256, 512, 768, 1536, 3072 (по умолчанию).

response = client.embeddings.create(
    model="gemini-embedding-001",
    input="Hello world",
    dimensions=768
)
assert len(response.data[0].embedding) == 768

cURL

curl https://gateway.api429.com/v1/embeddings \
  -H "Authorization: Bearer $YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-embedding-001",
    "input": "Hello world",
    "dimensions": 768
  }'

Структура ответа

{
  "object": "list",
  "model": "gemini-embedding-001",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0343, 0.0116, -0.0214, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

Примечания

• Эндпоинт оптимизирован для эмбеддингов во время запроса (поисковый ввод, извлечение для RAG). Эмбеддинги документов для индекса работают так же — качество векторов одинаковое.
• Пустой input возвращает HTTP 400.
• Без стриминга — ответы с эмбеддингами всегда возвращаются целиком.

Генерация музыки

Музыка генерируется асинхронно. Отправьте задачу, опрашивайте ее статус до завершения, затем используйте полученный HTTPS URL. У API-токена должен быть асинхронный scope audio. Новые активные токены внешних клиентов получают этот scope по умолчанию. Существующие управляемые политики клиентов и токенов проектов обновляются автоматически, явно заданные политики не меняются. Если для токена задан ограниченный список разрешенных моделей, в нем также должна быть lyria-3-pro-preview.

Доступная модель

duration_seconds задает ориентир для композиции, но не гарантирует точную длительность. Готовая композиция может оказаться короче или длиннее запрошенной.

Создание задачи на генерацию музыки

curl https://gateway.api429.com/v1/music/generations \
  -H "Authorization: Bearer $API429_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-theme-001" \
  -d '{
    "model": "lyria-3-pro-preview",
    "prompt": "Cinematic synth-pop at 112 BPM, restrained verse, wide uplifting chorus",
    "duration_seconds": 120,
    "lyrics": "[Verse]\nCity lights begin to glow\n\n[Chorus]\nWe are ready, let it show",
    "instrumental": false,
    "output_format": "mp3"
  }'

google/lyria-3-pro-preview принимается как алиас для совместимости на входе. В ответах по задаче он заменяется каноническим ID lyria-3-pro-preview.

Заголовок Idempotency-Key обязателен. Если тот же аутентифицированный клиент повторно отправит тот же ключ, вернется исходная задача: новая генерация не создается и не оплачивается. Новый ключ запускает новую платную генерацию.

Ответ на отправку задачи приходит с HTTP-кодом 202:

{
  "id": "job_...",
  "object": "music.generation.job",
  "status": "queued",
  "model": "lyria-3-pro-preview"
}

Опрос статуса и получение композиции

curl https://gateway.api429.com/v1/music/generations/job_... \
  -H "Authorization: Bearer $API429_TOKEN"

Пока задача выполняется, эндпоинт возвращает ее текущий статус. Для завершенной задачи ответ выглядит так:

{
  "object": "music.generation",
  "model": "lyria-3-pro-preview",
  "data": [
    {
      "url": "https://cdn.example/song.mp3",
      "mime_type": "audio/mpeg",
      "bytes": 1544920,
      "sha256": "..."
    }
  ],
  "billing": {
    "charged_amount_usd": "0.08",
    "unit_price_usd": "0.08",
    "currency": "USD",
    "pricing_status": "charged"
  }
}

Если итоговый результат у провайдера нельзя надежно определить, задача получает статус ambiguous и не повторяется автоматически. Так в рамках одной задачи не создается вторая платная композиция. Используйте новый ключ идемпотентности, только когда проверите итоговый статус.

Модели для генерации видео

Видео генерируется асинхронно. Отправьте задачу, опрашивайте ее статус до завершения, затем используйте полученный HTTPS URL на CDN. Шлюз не отдает клиентам прямые URL хранилища провайдера.

У API-токена должен быть асинхронный scope video. Новые активные токены, отнесенные к внешним клиентам, по умолчанию получают и video, и audio; любой из них можно отозвать в админке. Асинхронные текст и изображения по-прежнему включаются отдельно, а явно заданные политики существующих токенов никогда не перезаписываются управляемыми настройками клиента по умолчанию.

Доступные модели

Gemini Omni 1.1 Flash

Используйте стабильный клиентский ID модели gemini-omni-1.1-flash. Устаревшие варианты написания gemini-omni-flash-preview и короткий gemini-omni-flash принимаются как алиасы только на входе и приводятся к новому каноническому ID. API429 не подменяет модель на Veo или другого видеопровайдера незаметно для вас.

В ответе задачи сохраняется клиентский контракт model:"gemini-omni-1.1-flash". Необязательное поле metadata.actual_model указывает модель в результате конкретной задачи. В запросах используйте стабильный клиентский ID.

Поддерживаемые сценарии Omni:

Медиа для Omni можно передать как публичный HTTPS URL, URI gs://, строку base64/data URI или объект, например {"url":"https://.../image.png","mime_type":"image/png"}. Перед обращением к Google API429 приватно размещает внешние входные данные у себя.

Omni принимает duration от 3 до 10 секунд, aspect_ratio 16:9 или 9:16, один результат и resolution 360p, 720p (по умолчанию), 1080p или 4k. Результаты в 1080p и 4k апскейлит Google. Дополнительные параметры: temperature (0..2), top_p (0..1) и thinking_level (minimal, low, medium, high). Звук генерируется всегда: не передавайте audio или передайте audio:true; audio:false отклоняется.

seed есть в общей схеме Interactions, но не описан как параметр модели Gemini Omni. Поэтому API429 отклоняет его, а не делает вид, что результат воспроизводим.

Справочные тарифы: $1.50 за 1M входных токенов, $9.00 за 1M выходных токенов текста и thinking, $17.50 за 1M выходных токенов видео. Google считает выходное видео как 1,931 токена в секунду для 360p, 5,792 для 720p, 8,688 для 1080p и 17,376 для 4k (примерно $0.0338, $0.1014, $0.1520 и $0.3041 за секунду сгенерированного видео соответственно). До того как воркер обратится к Google, API429 резервирует консервативную максимальную сумму с учетом разрешения. Когда Google вернет фактический расход, разница возвращается. Если фактический расход недоступен, сохраняется fallback-сумма для этого разрешения, а задача получает соответствующую пометку. Нулевая стоимость в этом случае не выставляется.

Модель Omni не поддерживает Chat Completions, системные инструкции, структурированный вывод и JSON, context caching, grounding и поиск, function calling, выполнение кода и аудиореференсы. На неподдерживаемые комбинации возвращается ошибка валидации: запрос не переключается незаметно на другое поведение.

Пример отправки задачи Omni

curl -X POST "https://gateway.api429.com/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: omni-video-001" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "prompt": "A cinematic five-second product shot of a blue cup",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "thinking_level": "high"
  }'

Для генерации видео из изображения меняются только режим и входные данные:

{
  "model": "gemini-omni-1.1-flash",
  "mode": "image_to_video",
  "prompt": "The camera slowly moves around the product",
  "image": {
    "url": "https://example.com/product.png",
    "mime_type": "image/png"
  },
  "duration": 6,
  "aspect_ratio": "9:16"
}

Чтобы продолжить редактирование готового результата Omni, отправьте новый запрос с тем же API-ключом, указав mode:"edit" и previous_job_id с ID предыдущей задачи API429. Для продолжения нужна доступная предыдущая задача, принадлежащая тому же API-ключу.

Veo 3.1

Для Veo итоговая оценочная стоимость равна price_per_second * duration_seconds * sample_count. Шлюз резервирует оценочную сумму, когда принимает задачу. Если запрос завершается ошибкой до начала генерации видео у провайдера, резерв снимается. Если операция у провайдера уже началась, оплата фиксируется, даже если итоговый статус неоднозначен.

Поддерживаются соотношения сторон 16:9 и 9:16. Если передан seed, он должен быть беззнаковым 32-битным целым. audio / generateAudio передается в Vertex как generateAudio.

Поддерживаемые значения mode в API429:

first_last_frame требует image и last_frame для Veo. video_extension требует video. Клиенты не должны передавать ни duration_seconds, ни duration: продление всегда добавляет семь секунд. Если результат отправки задачи провайдеру неясен, асинхронная задача может перейти в статус ambiguous. В этом случае опрашивайте исходную задачу и не создавайте автоматически новый платный запрос взамен.

Если mode не указан или равен auto, API429 определяет режим по переданным полям медиа: video → video_extension, reference_images → reference_guided, image + last_frame → first_last_frame, image → image_to_video, без медиа → text_to_video.

Эндпоинт в стиле API429/OpenAI

POST /v1/videos/generations
GET  /v1/videos/generations/{job_id}

Тело запроса

Пример отправки задачи

curl -X POST "https://gateway.api429.com/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-job-001" \
  -d '{
    "model": "veo-3.1-fast-generate-001",
    "mode": "text_to_video",
    "prompt": "A calm ocean wave at sunrise, cinematic",
    "duration": 4,
    "n": 1,
    "aspectRatio": "16:9",
    "resolution": "720p",
    "audio": false
  }'

Для генерации видео из изображения используется тот же эндпоинт с mode: "image_to_video":

{
  "model": "veo-3.1-generate-001",
  "mode": "image_to_video",
  "prompt": "A slow cinematic push-in over the product",
  "image": {"gcsUri": "gs://client-inputs/product.png", "mimeType": "image/png"},
  "cameraControl": "push_in",
  "resizeMode": "crop",
  "duration_seconds": 8,
  "resolution": "1080p",
  "audio": false
}

Для генерации по первому и последнему кадру используйте mode: "first_last_frame" с image и last_frame. Для продления видео используйте mode: "video_extension" с video и без поля длительности. Для генерации объекта или продукта по референсам используйте mode: "reference_guided" и до трех элементов reference_images с referenceType: "asset".

API429 не понижает незаметно запрошенные возможности Veo. Функции, доступные только в превью, например 4k, расширенные настройки камеры или поведение модели, зависящее от аккаунта или региона, передаются, если запрос синтаксически корректен. Если Vertex отклоняет такую комбинацию, асинхронная задача завершается ошибкой валидации провайдера и очищенной сводкой запрошенных модели, режима, полей медиа и параметров. Если отказ произошел до начала операции Vertex, резерв снимается.

При успешной отправке возвращается 202 с объектом задачи:

{
  "id": "01HYVIDEOJOB",
  "object": "video.generation.job",
  "status": "queued",
  "endpoint": "videos.generations"
}

Опрашивайте задачу, пока status не станет succeeded:

curl "https://gateway.api429.com/v1/videos/generations/01HYVIDEOJOB" \
  -H "Authorization: Bearer YOUR_API_KEY"

Завершенные задачи возвращают значения data[].url со ссылками на файлы video/mp4 на CDN шлюза, доступные для скачивания. Готовый результат Omni также может содержать фактический расход и итоговую оплату:

{
  "object": "video.generation",
  "model": "gemini-omni-1.1-flash",
  "data": [
    {"url": "https://cdn.example.com/video.mp4", "mime_type": "video/mp4"}
  ],
  "usage": {
    "input_tokens": 312,
    "output_tokens": 28960,
    "thought_tokens": 144,
    "total_tokens": 29416,
    "input_tokens_by_modality": {"text": 24, "image": 288},
    "output_tokens_by_modality": {"video": 28960}
  },
  "billing": {
    "charged_amount_usd": "0.508564",
    "currency": "USD",
    "pricing_status": "usage"
  },
  "metadata": {
    "route_provider": "google",
    "actual_model": "gemini-omni-1.1-flash-preview"
  }
}

Значения токенов выше только иллюстрируют структуру ответа. Фактический расход и цена зависят от запроса и данных учета, которые вернет Google.

Эндпоинты, совместимые с Vertex (только Veo)

Эти маршруты предназначены для клиентов, которые переходят с SDK или REST-интеграции в стиле Vertex. Оставьте прежнюю структуру тела запроса и замените базовый URL и токен. Gemini Omni использует эндпоинт в стиле API429/OpenAI, описанный выше, и не доступна как модель Vertex predictLongRunning.

POST /v1/projects/{project}/locations/{location}/publishers/google/models/{model}:predictLongRunning
POST /v1/projects/{project}/locations/{location}/publishers/google/models/{model}:fetchPredictOperation

Данные для аутентификации можно передать как x-goog-api-key: YOUR_API_KEY, ?key=YOUR_API_KEY или Authorization: Bearer YOUR_API_KEY.

Пример отправки задачи

curl -X POST "https://gateway.api429.com/v1/projects/gateway/locations/us-central1/publishers/google/models/veo-3.1-fast-generate-001:predictLongRunning" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "A calm ocean wave at sunrise, cinematic"}],
    "parameters": {
      "durationSeconds": 4,
      "sampleCount": 1,
      "aspectRatio": "16:9",
      "resolution": "720p"
    }
  }'

Шлюз возвращает имя операции, которой управляет API429:

{
  "name": "api429/jobs/01HYVIDEOJOB",
  "done": false,
  "metadata": {"api429JobId": "01HYVIDEOJOB", "status": "queued"}
}

Получение состояния операции:

curl -X POST "https://gateway.api429.com/v1/projects/gateway/locations/us-central1/publishers/google/models/veo-3.1-fast-generate-001:fetchPredictOperation" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationName":"api429/jobs/01HYVIDEOJOB"}'

Если функция не включена для вашего аккаунта, маршрут возвращает 403, 404 или 503. Если на балансе недостаточно средств для оплаты оценочной стоимости видео, запрос на отправку возвращает 402.

Распознавание речи (Speech-to-Text)

POST   /v1/audio/transcriptions

OpenAI-совместимое распознавание речи моделью gemini-3.5-transcribe. Тело запроса — multipart/form-data:

verbose_json возвращает сегменты с start, end, text и меткой спикера speaker (speaker_0, speaker_1, …), а по запросу — таймкоды слов.

* Со стандартной клиентской скидкой 70%. Аудио тарифицируется по 32 токена на секунду записи, расшифровка — по числу её токенов.

curl https://gateway.api429.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=gemini-3.5-transcribe \
  -F response_format=verbose_json \
  -F file=@meeting.mp3

{
  "task": "transcribe",
  "language": "unknown",
  "duration": 3.44,
  "text": "Hello. Your order has shipped and will arrive on Thursday.",
  "segments": [
    {"id": 0, "start": 0.2, "end": 3.1, "speaker": "speaker_0",
     "text": "Hello. Your order has shipped and will arrive on Thursday."}
  ]
}

OpenAI SDK работает без изменений: client.audio.transcriptions.create(model="gemini-3.5-transcribe", file=open("meeting.mp3", "rb")).

Синтез речи (Text-to-Speech)

POST   /v1/audio/speech
GET    /v1/audio/voices
POST   /v1/audio/voices
DELETE /v1/audio/voices/{voice_id}

Единый OpenAI-совместимый эндпоинт для TTS. Здесь поддерживаются Gemini-модели gemini-3.8-flash-tts, gemini-3.8-flash-lite-tts, gemini-3.1-flash-tts-preview и gemini-2.5-flash-preview-tts. Набор параметров намеренно минимален: обязательные model и input, а также необязательные voice и response_format. Если не указать model, запрос не пройдёт валидацию и вернёт HTTP 422: шлюз не подставляет Gemini TTS-модель молча.

Gemini TTS-модели возвращают WAV целиком в теле ответа (audio/wav, 24 kHz mono PCM-16). Модели ElevenLabs возвращают MP3 (audio/mpeg). response_format принимается для совместимости с SDK, но на вывод Gemini не влияет.

Поддержка TTS по интерфейсам

Доступные модели

† Промо-цена Google до 2026-12-31; с 2027-01-01 Google указывает для gemini-3.8-flash-tts $1.00 / $18, для gemini-3.8-flash-lite-tts — $1.00 / $12 за 1M токенов.

Важно, какой API Google вы используете. gemini-2.5-flash-tts — это ID модели в отдельном Cloud Text-to-Speech API от Google. В Gemini generateContent он недействителен, а API429 сейчас не проксирует Cloud TTS text:synthesize и text:streamingSynthesize. Ошибка 400 INVALID_ARGUMENT от generateContent для этого ID означает несоответствие эндпоинта и модели, а не отключённый переключатель Cloud API на шлюзе API429.

Модели ElevenLabs

* В колонке API429 учтена стандартная клиентская скидка 70% от базовой ставки $0.0370: $0.0370 × 30% = $0.0111 за 1K символов. Индивидуальный тарифный профиль клиента может переопределять указанную здесь скидку.

elevenlabs-gen — единственная каноническая модель ElevenLabs. Передавайте нативный ID голоса ElevenLabs в стандартном OpenAI-совместимом поле voice. Если его не указать или передать неизвестное имя, используется голос по умолчанию.

Оплата выполняется по указанной выше ставке elevenlabs-gen. Длинный текст возвращается одним склеенным MP3.

Устаревшие ID eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5 и api429-tts по-прежнему принимаются для обратной совместимости, но больше не выводятся в GET /v1/models. В новых интеграциях используйте elevenlabs-gen.

Eleven v4 и v4 Turbo

eleven_v4 и eleven_v4_turbo — новейшие речевые модели ElevenLabs (вышли 2026-09-28): более выразительная подача, 90+ языков и управление произношением через фонетику (IPA). v4 Turbo немного уступает в качестве ради меньшей задержки. Обе модели выводятся в GET /v1/models; запрашивайте их по точному ID на POST /v1/audio/speech. Цены — в таблице выше. Голоса работают как у elevenlabs-gen: передайте нативный ID голоса ElevenLabs в voice или не указывайте его, чтобы использовать голос по умолчанию. Вывод — MP3 (audio/mpeg).

При недоступности сервиса запрос v4 завершается ошибкой. eleven_v3 по-прежнему доступна; выбирайте модель явно в каждом запросе.

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eleven_v4",
    "voice": "hpp4J3VqNfWAUOO0d1Us",
    "input": "Привет! Это Eleven v4 через API429."
  }' \
  --output speech.mp3

Если контент-фильтр провайдера синтеза блокирует часть текста, запрос возвращает 422 с числом отклонённых фрагментов. Переформулируйте отмеченные места и повторите запрос.

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-gen",
    "voice": "hpp4J3VqNfWAUOO0d1Us",
    "input": "Привет! Это озвучка ElevenLabs через API429."
  }' \
  --output speech.mp3

Модель Fish Audio

* В колонке API429 учтена стандартная клиентская скидка 70%. Индивидуальный тарифный профиль клиента может переопределять указанную здесь скидку.

Для этой модели voice обязателен. Передайте 32-символьный hex-ID голоса из каталога (см. ниже) или ID клонированного вами голоса. Голоса по умолчанию нет: если не указать voice, передать пустую строку или имя голоса, например "Sarah", вернётся 400 с описанием формата ID. Так сделано намеренно. Раньше подставлялся голос по умолчанию: аудио получалось нормальным, но не тем голосом, а ответ был 200. Из-за этого опечатка выглядела так, будто шлюз вообще игнорирует voice, — один клиент потратил на это целый день. У голосов есть собственные языковые теги, и многие из них мультиязычные, поэтому один голос часто подходит для нескольких рынков.

Если ID имеет правильный формат, но такого голоса нет, сейчас возвращается 502 ("could not be served by any configured provider"), а не 4xx, потому что отказ провайдера передаётся как сбой на стороне upstream. Если вы получили 502 от /v1/audio/speech, сверьте ID голоса с каталогом, прежде чем сообщать о сбое.

Формат вывода. fish-s2.1-pro учитывает response_format: mp3 (по умолчанию), wav, pcm и opus. Используйте wav, если потребителю нужен RIFF/WAVE: некоторые пайплайны постобработки не принимают MP3. WAV примерно в шесть раз больше того же аудио в MP3, поэтому выбирайте mp3, если RIFF вам не нужен.

Длинный текст обрабатывается автоматически. Текст длиннее нескольких тысяч символов разбивается по границам предложений, синтезируется параллельно и возвращается одним склеенным клипом — без архивов и без разрезанных пополам слов. Час озвучки (~60 000 символов) занимает от начала до конца примерно три минуты. Единственное исключение — opus: его нельзя надёжно склеить, поэтому для длинного текста в этом формате возвращается 400. Используйте вместо него mp3, wav или pcm.

Об оплате. Провайдер считает байты UTF-8, а ставка выше указана за символ. Латиница занимает один байт на символ, кириллица — два, CJK — три, поэтому озвучка нелатинского текста на стороне upstream обходится пропорционально дороже, чем следует из цены за символ. Для планирования бюджета всегда используйте итоговый счёт из /api/client/usage/daily.

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fish-s2.1-pro",
    "input": "Привет! Это озвучка Fish Audio через API429.",
    "voice": "90e65eaaf50e4470b8e6d43ee6afd7d5",
    "response_format": "wav"
  }' \
  --output speech.wav

Каталог голосов

GET /v1/audio/voices

Поскольку voice обязателен, а неверное значение даёт 400, так вы находите действительный ID. Доступно более тысячи публичных голосов на многих языках.

curl "https://gateway.api429.com/v1/audio/voices?language=ru&q=narrator&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "model": "fish-s2.1-pro",
  "total": 37,
  "offset": 0,
  "data": [
    {
      "id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "name": "Documentary narrator",
      "languages": ["ru", "en"],
      "tags": ["narration", "calm"],
      "description": "Warm, unhurried delivery…",
      "author": "…",
      "popularity": 48213
    }
  ]
}

Возьмите id из любой записи и передайте его как voice в POST /v1/audio/speech. Результаты отсортированы по popularity — числу задач, которые обработал голос, — поэтому первая страница — это осмысленный шорт-лист, а не случайная выборка. total — число всех записей, подходящих под фильтр, а не только на странице. Выводятся только публичные готовые голоса.

Клонированные голоса

POST   /v1/audio/voices
GET    /v1/audio/voices?scope=mine
DELETE /v1/audio/voices/{voice_id}

Загрузите запись голоса один раз и дальше синтезируйте речь этим голосом. Полученный ID работает так же, как любой голос из каталога (передавайте его в voice), с одним отличием: он доступен только API-ключу, который его создал.

Отправьте аудио как multipart/form-data:

curl https://gateway.api429.com/v1/audio/voices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@narrator.mp3" \
  -F "name=House narrator" \
  -F "transcript=I have been recording audiobooks for eleven years."

{
  "id": "voice_b3b86385ec1b489f9d16183f603ee25c",
  "object": "audio.voice",
  "name": "House narrator",
  "created": 1789661983,
  "sample_bytes": 197431,
  "sample_format": "audio/mpeg",
  "has_transcript": true
}

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fish-s2.1-pro",
    "input": "This text is read in the cloned voice.",
    "voice": "voice_b3b86385ec1b489f9d16183f603ee25c"
  }' \
  --output cloned.mp3

Клонированный голос работает везде, где работает голос из каталога, включая разбиение длинного текста: каждый фрагмент длинной озвучки синтезируется тем же голосом.

Ваши голоса принадлежат только вам. Клонированный голос привязан к API-ключу, который его создал. Другой ключ с этим ID получит 404 — тот же ответ, что и для ID, которого никогда не существовало, — и не увидит голос в своём списке scope=mine. DELETE удаляет голос и сохранённую запись; после этого ID возвращает 404.

Ограничения и ошибки.

Синтез клонированным голосом оплачивается так же, как любой другой синтез на этой модели: за символ input по той же ставке. Регистрация, просмотр списка и удаление голоса бесплатны.

Ссылка вместо файла

Час озвучки занимает около 10 MB в MP3 и намного больше в WAV — такой объём неудобно передавать в теле синхронного ответа. Укажите "delivery": "url", и клип загрузится на наш CDN, а в ответ придёт небольшой JSON с его описанием:

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fish-s2.1-pro",
    "input": "…длинный текст ролика…",
    "delivery": "url"
  }'

{
  "url": "https://api429.lon1.cdn.digitaloceanspaces.com/api429/tts/…mp3",
  "mime": "audio/mpeg",
  "bytes": 10452992
}

Если не указывать delivery (или передать "inline"), вы получите сырые байты аудио, как и раньше, — поведение по умолчанию не изменилось.

У gemini-3.1-flash-tts-preview сейчас задокументированы лимиты 8,192 входных токенов и 16,384 выходных токенов. Для этой модели поддерживается upstream Batch API, а кеширование, function calling, Live API, структурированный вывод, выполнение кода, grounding и URL context не поддерживаются.

* Как мы рассчитываем эффективную ставку. Google тарифицирует TTS по аудиотокенам: 1 секунда вывода = 25 аудиотокенов. Английская речь в среднем — 13.5 символов/с, поэтому 1M аудиотокенов ≈ 40 000 с ≈ 540 000 символов.

$20 / 1M audio tokens  ×  (1M / 540K)  =  $0.03704 per 1K chars  (Gemini 3.1)
$0.0370 rounded base rate × 30% after the standard 70% discount = $0.0111 billed

Русская речь и речь на CJK-языках медленнее (~10–12 символов/с), поэтому наша посимвольная ставка немного занижает стоимость неанглийского трафика (погрешность <25%). Для планирования бюджета всегда используйте итоговый счёт из /api/client/usage/daily — он отражает фактическое списание Google, а не эту оценку.

Текст на входе ($1.00 / 1M текстовых токенов) добавляет <5 % к итогу типичного TTS-запроса, поэтому клиенты обычно могут ориентироваться только на ставку за аудио на выходе.

Быстрый старт (OpenAI-совместимый API)

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",   # current Gemini TTS model
    voice="Kore",
    input="Hello, welcome to our API."
)
response.stream_to_file("output.wav")

curl https://gateway.api429.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.wav \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "voice": "Kore",
    "input": "Hello, welcome to our API."
  }'

// Node.js / TypeScript via the official OpenAI SDK
import OpenAI from "openai";
import { writeFile } from "node:fs/promises";

const client = new OpenAI({
  baseURL: "https://gateway.api429.com/v1",
  apiKey: process.env.BALANCER_API_KEY!,
});

const speech = await client.audio.speech.create({
  model: "gemini-3.1-flash-tts-preview",
  voice: "Kore",
  input: "Hello, welcome to our API.",
});

await writeFile("output.wav", Buffer.from(await speech.arrayBuffer()));

// Node.js / browser via plain fetch (no SDK dependency)
const res = await fetch("https://gateway.api429.com/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BALANCER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-3.1-flash-tts-preview",
    voice: "Kore",
    input: "Hello, welcome to our API.",
  }),
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`TTS failed: ${err.error?.message ?? res.status}`);
}

const wav = Buffer.from(await res.arrayBuffer());
require("node:fs").writeFileSync("output.wav", wav);

Пример с OpenAI SDK и выразительными тегами

Gemini 3.1 Flash TTS Preview поддерживает выразительные теги в квадратных скобках для управления подачей. Пишите теги по-английски, даже если сам текст на русском или другом языке.

response = client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Puck",
    input=(
        "Прочитай как тревожный рассказчик: "
        "Я открыл дверь. [short pause] Там никого не было. [gasp]"
    ),
)
response.stream_to_file("tagged.wav")

Поле response_format. Все вызовы Gemini TTS возвращают audio/wav независимо от переданного response_format. OpenAI SDK предоставляет response_format для совместимости, но upstream не поддерживает mp3/opus/aac/flac/pcm — вы всегда получите одно и то же тело WAV 24 kHz mono PCM-16. Если нужен другой контейнер, конвертируйте аудио с помощью ffmpeg на стороне клиента.

Библиотека голосов (30 готовых голосов)

В Gemini TTS есть 30 разных голосов. У каждого свой тембр и характер — выберите тот, что подходит под вашу задачу.

Во всех превью звучит одна и та же английская панграмма ("The quick brown fox jumps over the lazy dog."), чтобы вы могли сравнить их на слух. На русском и CJK-языках голоса звучат немного иначе, но сохраняют свой характер.

Женские голоса (14):

Мужские голоса (16):

⭐ Kore — голос по умолчанию в балансировщике, если voice не указан или неизвестен.

Неизвестные имена голосов молча заменяются на Kore: перед отправкой в upstream балансировщик сверяет имена с белым списком.

Для читающих офлайн или на GitHub. Превью выше размещены по адресу https://hostkey24760.api429.com/admin-panel/front-max/voice-samples/<Voice>.mp3 — они публичные, авторизация не нужна. Если вы читаете этот текст на GitHub или в офлайн-зеркале, откройте эти URL в браузере, чтобы послушать. Альтернатива — интерактивная AI Studio Voice Library от Google: там каждый голос звучит на нескольких примерах фраз.

Выбор голоса по сценарию

Краткая шпаргалка, чтобы сузить выбор с 30 до 1 в зависимости от задачи. Все рекомендации субъективны — послушайте превью и доверьтесь своему слуху.

Языки

Gemini TTS автоматически определяет язык по входному тексту. 24 языка в GA:

арабский (Египет), бенгальский (Бангладеш), нидерландский, английский (Индия, США), французский, немецкий, хинди, индонезийский, итальянский, японский, корейский, маратхи, польский, португальский (Бразилия), румынский, русский, испанский (Испания), тамильский, телугу, тайский, турецкий, украинский, вьетнамский.

Ещё 50+ в режиме Preview (китайский мандаринский, греческий, иврит, норвежский, шведский, чешский и другие — см. официальный список Google).

# Russian — just write the text, no extra parameter needed
response = client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Kore",
    input="Привет, как твои дела сегодня?",
)

Управление стилем

Манеру подачи можно задать двумя способами:

1. Префикс со стилем на естественном языке

Добавьте инструкцию по стилю в начало текста.

client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Enceladus",
    input="Say in a spooky whisper: Something wicked this way comes.",
)

client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Puck",
    input="Read excitedly, like breaking news: The rocket has landed!",
)

2. Экспрессивные аудиотеги

Теги в квадратных скобках внутри предложения управляют неречевыми звуками и темпом. Google не публикует исчерпывающий список тегов. Считайте перечень ниже официальными и распространёнными примерами из документации Gemini API и Cloud TTS и проверяйте точную формулировку на своём голосе и языке.

client.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Puck",
    input="That joke was amazing. [laughs] I cannot stop thinking about it. [short pause] But seriously…",
)

Основные категории:

Неречевые звуки — голосовые вставки:

Модификаторы стиля — меняют характер подачи:

Эмоциональная разметка — эмоциональная окраска:

Темп — паузы:

Про язык: пишите аудиотеги на английском независимо от языка речи. [laughs] работает внутри русского предложения, а [смеётся] может быть прочитан вслух буквально.

Temperature (управление креативностью)

Gemini TTS поддерживает параметр temperature в диапазоне (0.0, 2.0]. Чем выше значение, тем выразительнее и разнообразнее озвучка. Низкие значения дают предсказуемый результат. OpenAI-совместимый эндпоинт пока не поддерживает этот параметр. Если он вам нужен, используйте нативный эндпоинт Gemini без стриминга:

curl "https://gateway.api429.com/gemini/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Tell me about the stars"}]}],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "temperature": 1.5,
      "speechConfig": {
        "voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}
      }
    }
  }'

Нативный ответ Gemini содержит сырой PCM в base64 в поле candidates[0].content.parts[0].inlineData.data. Декодируйте его и упакуйте на стороне клиента в WAV: 24 kHz, моно, PCM-16.

Разумные начальные значения:

• 0.2–0.5 — дикторский текст, стабильное чтение, аудиокниги
• 0.8–1.2 — разговорная речь, звучание по умолчанию
• 1.5–2.0 — театральная, эмоциональная подача, ведущие подкастов

Диалог нескольких спикеров

Gemini TTS может озвучить разговор до 2 спикеров за один вызов. OpenAI-совместимый эндпоинт балансировщика пока не поддерживает speaker_voice_configs. Для озвучки нескольких спикеров используйте нативный эндпоинт Gemini без стриминга:

curl "https://gateway.api429.com/gemini/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text":
      "TTS the following conversation:\nJoe: How is it going today Jane?\nJane: Not too bad, how about you?"
    }]}],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {"speaker": "Joe",  "voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}},
            {"speaker": "Jane", "voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Puck"}}}
          ]
        }
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' \
     | base64 --decode > dialogue.pcm
# Wrap raw PCM 16-bit 24kHz mono into a WAV:
ffmpeg -f s16le -ar 24000 -ac 1 -i dialogue.pcm dialogue.wav

Диалог в contents.parts[0].text можно оформить двумя способами:

(a) Свободная форма (показана выше) — префиксы строк Speaker: … в обычном тексте. Такой текст проще всего сгенерировать с помощью LLM.

(b) Структурированная форма — явный список реплик (только Python SDK):

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project="YOUR_GCP_PROJECT",
    location="global",
)

turns = [
    types.Content(role="user", parts=[
        types.Part(text="Joe: How's it going today Jane?"),
    ]),
    types.Content(role="user", parts=[
        types.Part(text="Jane: Not too bad, how about you?"),
    ]),
]
response = client.models.generate_content(
    model="gemini-3.1-flash-tts-preview",
    contents=turns,
    config=types.GenerateContentConfig(
        response_modalities=["AUDIO"],
        speech_config=types.SpeechConfig(
            multi_speaker_voice_config=types.MultiSpeakerVoiceConfig(
                speaker_voice_configs=[
                    types.SpeakerVoiceConfig(speaker="Joe",
                        voice_config=types.VoiceConfig(
                            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore"))),
                    types.SpeakerVoiceConfig(speaker="Jane",
                        voice_config=types.VoiceConfig(
                            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Puck"))),
                ]
            )
        ),
        temperature=1.5,
    ),
)

Совет: если нужна озвучка нескольких спикеров через OpenAI-совместимый эндпоинт, заранее разметьте текст префиксами Speaker: и озвучьте обе роли одним голосом. Модель всё равно учитывает контекст спикеров и слегка меняет интонацию. Если вам нужна полноценная поддержка speaker_voice_configs в /v1/audio/speech, создайте тикет.

Формат выходного аудио

Ограничения на вход и выход

Профиль задержек

Замерено 2026-04-23 на продакшене (медиана по 5 запросам с холодным стартом, 60 символов на входе, голос Kore):

Совместимость голосов и моделей

Все пять Gemini TTS-моделей поддерживают 30 голосов, перечисленных выше.

Ответы с ошибками

Все ошибки возвращаются в формате ошибок OpenAI: HTTP-статус и JSON-тело вида {"error": {"message": "...", "type": "...", "code": "..."}}. В таблице перечислены ошибки, которые вы реально встретите при работе с /v1/audio/speech в штатном режиме:

Как безопасно обрабатывать ошибки (Python):

from openai import OpenAI, APIError, RateLimitError, APIStatusError

client = OpenAI(base_url="https://gateway.api429.com/v1", api_key="...")

try:
    resp = client.audio.speech.create(model="gemini-3.1-flash-tts-preview", voice="Kore", input=text)
except RateLimitError as e:                      # 429 — respect Retry-After
    retry_after = int(e.response.headers.get("retry-after", "30"))
    ...
except APIStatusError as e:
    if e.status_code in (502, 503, 504):          # transient — retry
        retry_after = int(e.response.headers.get("retry-after", "10"))
        ...
    elif e.status_code in (400, 401, 413):        # permanent — surface
        raise
    else:
        raise

Паттерн повторов

Три правила, с которыми повторы остаются безопасными и дешёвыми:

1. Соблюдайте Retry-After, если сервер его передаёт (в 429 / 503 он есть всегда). Это значение отражает текущую загрузку. Если повторить раньше, запрос просто встанет в очередь на сервере и быстрее не выполнится.
2. Экспоненциальная задержка с jitter для временных 5xx без Retry-After. Рекомендуемая схема: 2 s → 8 s → 30 s (не больше 3 попыток, jitter ±20 %).
3. Не повторяйте 400/401/413 — тот же запрос с тем же input вернёт ту же ошибку и потратит бюджет. Передайте ошибку выше.

Эталонная реализация на Python

import asyncio
import random
from openai import AsyncOpenAI, APIStatusError, RateLimitError

client = AsyncOpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)


async def synthesize_with_retry(*, model: str, voice: str, input: str,
                                max_attempts: int = 4) -> bytes:
    """Synthesize speech with bounded retry. Honours Retry-After.

    Returns the full WAV bytes. Raises on permanent errors or after
    ``max_attempts`` transient failures.
    """
    backoff_s = [2, 8, 30, 60]
    for attempt in range(max_attempts):
        try:
            resp = await client.audio.speech.create(
                model=model, voice=voice, input=input,
            )
            return await resp.aread()
        except RateLimitError as e:                      # 429
            wait = int(e.response.headers.get("retry-after", "30"))
        except APIStatusError as e:
            if e.status_code in (400, 401, 413):         # permanent
                raise
            if e.status_code in (429, 502, 503, 504, 500) and attempt < max_attempts - 1:
                wait = int(e.response.headers.get("retry-after",
                                                  str(backoff_s[attempt])))
            else:
                raise
        wait *= (1 + random.uniform(-0.2, 0.2))         # ±20 % jitter
        await asyncio.sleep(wait)
    raise RuntimeError("synthesize_with_retry: all attempts failed")

Эталонная реализация на TypeScript

import OpenAI, { APIError } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.api429.com/v1",
  apiKey: process.env.BALANCER_API_KEY!,
});

const BACKOFF_S = [2, 8, 30, 60];
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function synthesizeWithRetry(args: {
  model: string;
  voice: string;
  input: string;
  maxAttempts?: number;
}): Promise<Buffer> {
  const max = args.maxAttempts ?? 4;
  for (let attempt = 0; attempt < max; attempt++) {
    try {
      const r = await client.audio.speech.create({
        model: args.model,
        voice: args.voice,
        input: args.input,
      });
      return Buffer.from(await r.arrayBuffer());
    } catch (e) {
      if (!(e instanceof APIError)) throw e;
      const status = e.status ?? 0;
      if ([400, 401, 413].includes(status)) throw e;       // permanent
      if (![429, 500, 502, 503, 504].includes(status)) throw e;
      if (attempt === max - 1) throw e;
      const headerRetry = Number(e.headers?.["retry-after"]) || BACKOFF_S[attempt];
      const jittered = headerRetry * (1 + (Math.random() - 0.5) * 0.4);
      await sleep(jittered * 1000);
    }
  }
  throw new Error("synthesizeWithRetry: exhausted");
}

Технические настройки, доступные только в Cloud

Google Cloud Text-to-Speech предоставляет низкоуровневые настройки, полезные при прямой интеграции с Cloud. Но в нашем маршруте /v1/audio/speech таких полей нет.

curl -X POST "https://texttospeech.googleapis.com/v1/text:synthesize" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Read the following in a curious, restrained tone.",
      "text": "OK, so... tell me about this [uhm] AI thing."
    },
    "voice": {
      "languageCode": "en-us",
      "name": "Kore",
      "model_name": "gemini-2.5-flash-tts"
    },
    "audioConfig": {
      "audioEncoding": "LINEAR16",
      "sampleRateHertz": 24000,
      "speakingRate": 1.0,
      "volumeGainDb": 0.0
    },
    "advancedVoiceOptions": {
      "safetySettings": []
    }
  }'

advancedVoiceOptions.safetySettings — функция прямого API Cloud Text-to-Speech. Она намеренно не описана как поле запроса к балансировщику. Устаревшие параметры relax_safety_filters / safety_settings шлюз не передаёт.

Чего нет в /v1/audio/speech

Для полноты картины: следующих настроек нет среди полей узкого OpenAI-совместимого эндпоинта для речи. Часть из них доступна через нативный шлюз Gemini, как показано выше. Настройки, доступные только в Cloud, требуют прямой интеграции с Google Cloud:

Полная документация Google:

• Gemini Developer API: https://ai.google.dev/gemini-api/docs/speech-generation
• Vertex AI Gemini TTS: https://cloud.google.com/text-to-speech/docs/gemini-tts
• Интерактивная библиотека голосов: https://aistudio.google.com/apps/bundled/voice-library

Длинное аудио (10+ минут)

Для аудиокниг, подкастов и любой озвучки длиннее нескольких минут клиент должен разбить сценарий на фрагменты, синтезировать их параллельно и склеить WAV-файлы локально. Балансировщик не разбивает текст, не объединяет запросы в пакеты и не склеивает потоки автоматически.

Безопасный рекомендуемый размер фрагмента — 3.5–4 KB UTF-8. В старой документации это значение ошибочно называлось локальным лимитом, но такого ограничителя в шлюзе не обнаружено. Реальный лимит провайдера для prompt + text в Cloud/Vertex напрямую — 8,000 байт, а у длинных одиночных запросов через несколько минут может падать качество. Максимальная длительность выходного аудио у провайдера — около 655 секунд, но в продакшене надёжнее разбивать текст на фрагменты.

Расчёт объёма

Русская речь и речь на CJK-языках медленнее (~10–12 симв./с), поэтому при той же длительности символов нужно примерно на 25 % меньше. Стоимость растёт линейно с числом входных символов по тарифу из раздела Доступные модели выше (например, 90 min Flash ≈ $1.35).

Стратегия разбиения

1. Разбивайте по границам предложений, чтобы просодия не обрывалась посреди фразы.
2. Упаковывайте фрагменты примерно по 3 500 байт UTF-8 (оставляя запас для префиксов стиля, тегов разметки и повторов).
3. Сохраняйте порядок — при склейке результаты параллельного синтеза нужно собирать в порядке входных фрагментов, а не в порядке завершения.

Параллельный синтез

Используйте небольшое ограниченное число одновременных запросов синтеза с учётом лимитов аккаунта и получаемых ответов. При HTTP 429 учитывайте Retry-After, увеличивайте задержку и ограничивайте число повторов.

Склейка

Все ответы Gemini TTS — это WAV: 24 kHz, моно, PCM-16 (см. Формат выходного аудио выше). Частота дискретизации и раскладка каналов совпадают, поэтому аудиоданные можно склеивать напрямую, без перекодирования. Два практичных варианта:

• Стандартная библиотека Python wave — прочитайте все WAV и запишите один общий файл. Внешние зависимости не нужны.
• ffmpeg — ffmpeg -f concat -safe 0 -i list.txt -c copy out.wav, где в list.txt по порядку перечислены имена файлов фрагментов.

Полный пример на Python (разбиение → gather → склейка)

import asyncio
import io
import re
import wave
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY",
)

CHUNK_BUDGET_BYTES = 3500   # leave room for style instructions and transcript tags
PARALLELISM = 8             # example only; adjust to account limits and observed 429s


def split_into_chunks(text: str, budget: int = CHUNK_BUDGET_BYTES) -> list[str]:
    """Split text at sentence boundaries, bin-pack to ≤budget bytes UTF-8."""
    sentences = re.split(r"(?<=[.!?])\s+", text.strip())
    chunks: list[str] = []
    buf = ""
    for sent in sentences:
        candidate = (buf + " " + sent).strip()
        if len(candidate.encode("utf-8")) > budget and buf:
            chunks.append(buf)
            buf = sent
        else:
            buf = candidate
    if buf:
        chunks.append(buf)
    return chunks


async def synthesize_one(idx: int, text: str, sem: asyncio.Semaphore) -> tuple[int, bytes]:
    async with sem:
        resp = await client.audio.speech.create(
            model="gemini-3.1-flash-tts-preview",
            voice="Kore",
            input=text,
        )
        return idx, await resp.aread()


async def synthesize_long(text: str, out_path: str) -> None:
    chunks = split_into_chunks(text)
    sem = asyncio.Semaphore(PARALLELISM)
    results = await asyncio.gather(
        *(synthesize_one(i, c, sem) for i, c in enumerate(chunks))
    )
    # Reassemble in original order (gather preserves input order, but
    # we tag explicitly so partial-result paths stay safe).
    results.sort(key=lambda x: x[0])

    with wave.open(out_path, "wb") as out_wav:
        params_set = False
        for _, wav_bytes in results:
            with wave.open(io.BytesIO(wav_bytes), "rb") as in_wav:
                if not params_set:
                    out_wav.setparams(in_wav.getparams())
                    params_set = True
                out_wav.writeframes(in_wav.readframes(in_wav.getnframes()))


# Usage:
# asyncio.run(synthesize_long(open("script.txt").read(), "narration.wav"))

Советы по обработке сбоев

• Оберните synthesize_one в цикл повторов for attempt in range(3) — отдельные фрагменты могут независимо получить 429 / 5xx от провайдера. Ограничивайте число повторов и учитывайте Retry-After.
• Если фрагмент стабильно падает даже после повторов, можно либо завершить ошибкой всю задачу, либо заменить его тишиной (b"\x00" * bytes_per_second * estimated_seconds), чтобы WAV сохранил ожидаемую длину. Выбор зависит от того, допускает ли ваша дальнейшая обработка пропуски.
• Отслеживайте расход по каждому фрагменту: каждый вызов тарифицируется отдельно (/api/client/usage/daily суммирует их).

Когда запрашивать поддержку на стороне сервера

Если вы регулярно генерируете аудио длиннее ~30 минут, а склейка на клиенте неудобна в эксплуатации (например, в мобильных клиентах или в браузере, где нет стандартной библиотеки wave), создайте тикет. Мы можем повысить приоритет серверного эндпоинта /v1/audio/speech/long, который сам разобьёт текст, распараллелит запросы и вернёт один WAV в одном HTTP-ответе.

Рецепты интеграции

Готовые примеры для типовых продуктов. Каждый пример самодостаточен и использует только публичный эндпоинт /v1/audio/speech.

1. Telegram-бот — голосовые ответы

# pip install python-telegram-bot openai
import io, os
from openai import OpenAI
from telegram import Update
from telegram.ext import Application, MessageHandler, ContextTypes, filters

tts = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key=os.environ["BALANCER_API_KEY"],
)

async def voice_reply(update: Update, ctx: ContextTypes.DEFAULT_TYPE):
    text = update.message.text or "Hello!"
    if len(text.encode("utf-8")) > 4000:
        await update.message.reply_text("Sorry, message too long for TTS.")
        return
    speech = tts.audio.speech.create(
        model="gemini-3.1-flash-tts-preview",
        voice="Kore",
        input=text,
    )
    # Telegram accepts WAV directly via send_voice (or send_audio for file).
    await update.message.reply_voice(io.BytesIO(speech.read()))

app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, voice_reply))
app.run_polling()

2. Аудиокнига из файла .txt

Использует функцию разбиения на фрагменты из раздела Длинное аудио: подключает её к обычному текстовому файлу и собирает один WAV. Выбран голос Sulafat (тёплый, ровный) — он хорошо подходит для многочасового чтения.

import asyncio
from pathlib import Path
# ...split_into_chunks, synthesize_one, synthesize_long defined in
# the "Long-form audio" section above...

async def audiobook(in_path: str, out_path: str, voice: str = "Sulafat") -> None:
    text = Path(in_path).read_text(encoding="utf-8")
    # Override the default voice in synthesize_one by using a partial
    # or just pass it through — see Long-form Python example.
    await synthesize_long(text, out_path, voice=voice, model="gemini-3.1-flash-tts-preview")

# CLI: python audiobook.py book.txt narration.wav
if __name__ == "__main__":
    import sys
    asyncio.run(audiobook(sys.argv[1], sys.argv[2]))

3. Озвучка чата — ответ LLM вслух

Пропускает ответ chat completions через TTS. Работают два потока параллельно: текстовый поток читает пользователь, а задача синтеза обрабатывает собранные фрагменты.

import os
from openai import OpenAI

llm = OpenAI(base_url="https://gateway.api429.com/v1",
             api_key=os.environ["BALANCER_API_KEY"])

# 1) Get a chat reply
chat = llm.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Tell me a 3-sentence bedtime story."}],
    max_tokens=200,
)
reply_text = chat.choices[0].message.content

# 2) TTS it (single-shot — short replies fit comfortably)
speech = llm.audio.speech.create(
    model="gemini-3.1-flash-tts-preview",
    voice="Despina",         # smooth, calming for bedtime
    input=reply_text,
)
with open("story.wav", "wb") as f:
    f.write(speech.read())

4. Кнопка предпрослушивания в веб-приложении

Браузер отправляет запрос с тем же Bearer-токеном. В продакшене храните токен на сервере — этот пример предназначен для админского интерфейса с авторизацией, где токен уже доступен.

<button id="preview" data-text="Hello, this is a preview." data-voice="Puck">▶</button>
<audio id="player" controls></audio>
<script>
document.getElementById("preview").addEventListener("click", async (e) => {
  const btn = e.currentTarget;
  const res = await fetch("https://gateway.api429.com/v1/audio/speech", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${window.YOUR_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gemini-3.1-flash-tts-preview",
      voice: btn.dataset.voice,
      input: btn.dataset.text,
    }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    alert("TTS failed: " + (err.error?.message ?? res.status));
    return;
  }
  const blob = await res.blob();
  document.getElementById("player").src = URL.createObjectURL(blob);
  document.getElementById("player").play();
});
</script>

Практикум по интеграции

Этот раздел пригодится, если вы адаптируете готовый клиент или отлаживаете запрос, который работает с SDK одного вендора, но не проходит через шлюз.

Выбор эндпоинта под задачу

Прежде чем показывать модель в интерфейсе, вызовите GET /v1/models с тем же API-ключом, который будете использовать в продакшене. Ответ содержит только модели, разрешённые для этого токена.

Форматы мультимодальных запросов

Vision в OpenAI-совместимом чате:

{
  "model": "gemini-3.1-pro",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]
  }]
}

Нативный мультимодальный формат Gemini:

{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "Describe this image"},
      {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_IMAGE_DATA>"}}
    ]
  }]
}

Используйте нативный маршрут Gemini, только если ваш клиент уже работает с форматом contents.parts. Клиентам на OpenAI SDK нужен OpenAI-совместимый формат messages[].content[], показанный выше.

Для медиа в нативном формате Gemini поля inlineData.data / inline_data.data и thoughtSignature принимают как стандартный base64, так и URL-safe base64, с паддингом или без. В ответах API429 используется канонический стандартный base64 с паддингом. Поэтому данные из ответа можно без перекодирования на клиенте передать в следующий запрос.

Клиенты со стримингом

• Читайте SSE до data: [DONE].
• Пропускайте SSE-комментарии и пустые строки.
• Для долгих задач не превращайте ситуацию «стрим вернул 0 чанков» в немедленный повторный запрос без стриминга: так можно выполнить работу дважды и заплатить дважды.
• Если HTTP-запрос упал до обработки первых данных SSE, повторите его с экспоненциальной задержкой.
• Если event: error пришёл после начала генерации текста, аудио или изображения, считайте попытку неудачной и повторяйте её только в соответствии с политикой идемпотентности вашего продукта.

Повторы и ограничения частоты запросов

• Учитывайте Retry-After, если он есть.
• Повторяйте запросы при 429, 503, 504 и временных сетевых ошибках с задержкой.
• Не повторяйте запросы в плотном цикле. Добавляйте jitter и ограничивайте число повторов.
• Для долгих текстовых задач Claude используйте stream:true в интерактивных сценариях или X-Async-Jobs-Optin: true для надёжного выполнения без стриминга.

Типичные исправления запросов

Files API

Нативный Gemini Files API, проксируется 1:1. Подходит для загрузки больших входных данных (видео, длинных PDF), на которые затем ссылаются вызовы generateContent.

Те же маршруты доступны по путям /gemini/upload/v1beta/files и /gemini/v1beta/files[/…]. Аутентификация — x-goog-api-key: <token> или ?key=<token>.

Использование и баланс клиента

Эти эндпоинты показывают состояние Bearer-токена, с которым их вызвали. Права администратора не нужны.

curl https://gateway.api429.com/api/client/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "token_id": "tok_…",
  "token_last4": "a1b2",
  "balance": {
    "currency": "USD",
    "available": "12.3400",
    "spent_today": "0.5120"
  }
}

Тело запроса POST /api/client/usage/daily/telegram принимает:

{
  "chat_id": "123456789",
  "message_thread_id": 42
}

chat_id обязателен при первой отправке; в последующих вызовах его можно не передавать — будет использовано сохранённое значение.

Клиентский портал (веб)

Панель самообслуживания в браузере доступна по адресу:

https://client.api429.com/

Вход. Вставьте свой bearer-токен (то же значение gb_…, которое вы используете для вызовов API) в поле Sign in и нажмите кнопку. Токен хранится только в sessionStorage текущей вкладки браузера и удаляется, как только вы закроете вкладку. Никаких cookie, паролей и отдельных учётных записей.

Что показывает портал.

• Текущий баланс в USD с предупреждением о низком балансе, когда он приближается к порогу, настроенному для вашего токена.
• Разбивку по дням, неделям и месяцам: общее число вызовов, успешные и неудачные вызовы, входные, выходные токены и токены изображений, официальная цена и ваша цена со скидкой.
• Топ-10 моделей за последние 30 дней: запросы, токены, стоимость.

Обновление и выход. Кнопка Refresh заново загружает баланс и данные об использовании. Sign out удаляет токен из вкладки и возвращает вас на экран входа.

Обработка ошибок

Коды состояния HTTP

Формат ответа с ошибкой

{
  "error": {
    "code": "http_error",
    "message": "Human-readable error description"
  }
}

Блокировка ответа провайдером

Если ответ заблокирован фильтром контента, запрос чата возвращает HTTP 400 с error.code: "content_filter" вместо пустого успешного ответа. Сообщение содержит причину, например PROHIBITED_CONTENT, без заблокированного текста. Списание с клиента не выполняется; автоматических повторов нет. Обычный пустой ответ с STOP остаётся успешным.

В стриминге блокировка до первой отправленной части возвращает ту же HTTP-ошибку. Если поток уже начался, HTTP-статус остаётся 200, а перед [DONE] приходит SSE error с code: "content_filter" и status: 400. Такой ответ нужно считать незавершённым.

Частые ошибки

Стратегия повторов

import time
from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://gateway.api429.com/v1",
    api_key="YOUR_API_KEY"
)

for attempt in range(3):
    try:
        response = client.chat.completions.create(
            model="gemini-3-flash-preview",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except APIError as e:
        if e.status_code in (429, 503):
            time.sleep(30)
            continue
        raise

Ограничения частоты запросов

• Если мощности ненадолго перегружены, вы получите HTTP 429 или 503. Сделайте паузу с экспоненциальной задержкой и jitter и повторите запрос — на практике обычно хватает одной-двух секунд.
• Очень долгие генерации (некоторые аудио- и image-модели) могут вернуть 504 после истечения внутреннего таймаута; повторите запрос с тем же промптом.
• Клиентские квоты, если они настроены, применяются через HTTP 403 с поясняющим сообщением. Чтобы увеличить лимит, обратитесь к администратору.

Поддерживаемые SDK

Любой OpenAI-совместимый SDK работает без доработок:

Укажите в base_url / baseURL адрес https://gateway.api429.com/v1 и используйте свой API-ключ. SDK для нативного Gemini или Vertex Express направьте на https://gateway.api429.com/v1beta или https://gateway.api429.com/vertex-express/v1beta соответственно и используйте заголовок x-goog-api-key (или query-параметр ?key=).

Скидка клиента на видео Google

Цена Veo рассчитывается от официального тарифа Google с учётом модели, разрешения, аудио, длительности и числа роликов. Клиентская скидка действует на видео: при скидке 70% вы платите 30% тарифа Google. Например, Veo 3.1 Fast, 720p с аудио — $0,03 за секунду, или $0,24 за один восьмисекундный ролик, при этой скидке. Переключение провайдера не меняет клиентский тариф. Неудачная генерация до оплачиваемого результата возвращает зарезервированную сумму. Успешный результат содержит billing.charged_amount_usd, billing.official_amount_usd и billing.discount_percent. Стандартные ставки Veo доступны через GET /api/public/catalog: метрика video_second, условия разрешения и аудио; условия вашего аккаунта могут отличаться. Тарифы Google.