Amazi AI Gateway

Назначение Gateway

Amazi AI Gateway предоставляет приложениям проекта управляемый доступ к OpenAI. На данный момент поддерживается только OpenAI. Это отдельная возможность, не часть каталога внешних Integrations: у провайдеров есть собственная вкладка проекта, право плана, учётные данные, каталог моделей и учёт расхода. Функция управляет AI-сервисами ваших приложений, а не включает или выключает агента Amazi в чате проекта. Для работы в чате по-прежнему нужны соответствующие права проекта и кредиты.

Откройте Gateway в проекте и подключите его, если это разрешают ваша роль и план владельца. Amazi включает OpenAI, создаёт и хранит его управляемые данные доступа и показывает имена переменных. Другие провайдеры недоступны в списке Gateway проекта. Отключение прекращает доступ к Gateway и удаляет маршруты голосовых агентов, но не превращает провайдеров в обычные интеграции.

Под шапкой по центру расположены две вкладки. Провайдеры открывается первой и содержит данные доступа и каталоги моделей. Раскройте Доступные эндпоинты над Доступными моделями, чтобы увидеть поддерживаемые HTTP-пути OpenAI и правило их добавления к базовому URL. Раскройте Доступные модели, чтобы увидеть таблицу с названиями, API-идентификаторами, категориями и описаниями. На каждой вкладке один информационный блок. SIP Realtime содержит голосовых агентов, их Realtime-адреса и SIP-реквизиты. При переключении сохраняются выбранный провайдер и незавершённая форма голосового агента.

Если Gateway не удалось загрузить, нажмите Повторить. Ошибка загрузки не означает, что Gateway отключён для вашего аккаунта: ограничения тарифа и роли показываются отдельно.

Использование на сервере

Учётные данные Gateway — серверные секреты:

• обращайтесь к провайдеру из backend или service;
• используйте точные имена окружения, показанные Amazi;
• не копируйте секрет в чат, Git, браузерную переменную или frontend-код.

Агент получает инструкции и имена переменных, но не сохранённое значение.

Обычные HTTP-запросы

Из backend-кода отправляйте совместимые с провайдером запросы на внедрённый base URL и передавайте внедрённый ключ как bearer token. Выбирайте модель из каталога провайдера в Amazi. В нём указаны названия моделей, точные API-идентификаторы, категории и описания. Таблица доступных провайдеров и моделей ниже загружается из актуального каталога Amazi. При выборе модели для приложения агент может проверить сведения об endpoints, форматах и стоимости.

Пути операций ниже определены API OpenAI. Amazi AI Gateway пересылает поддерживаемые запросы на соответствующие эндпоинты OpenAI, сохраняя эти пути. Базовый URL OpenAI заканчивается на /openai/v1. Добавляйте к нему путь операции из таблицы; повторно добавлять /v1 не нужно. Все перечисленные операции используют POST:

Например, для распознавания речи нужен <base URL>/audio/transcriptions. Запрос только на /v1 не выбирает операцию, а путь /transcribe не поддерживается. Выберите точный API-идентификатор модели, совместимой с операцией и форматом входных данных. Категория модели не выбирает маршрут автоматически; Gateway предоставляет не все эндпоинты провайдера.

Для JSON-операций задавайте Content-Type: application/json и передавайте JSON в формате провайдера. Например, POST <base URL>/embeddings принимает {"model":"<embedding-model-from-the-catalog>","input":"Example text"} с bearer-ключом.

Для распознавания аудио передавайте file и одно текстовое поле model в multipart/form-data. Порядок полей не имеет значения. При использовании FormData HTTP-клиент сам формирует заголовок Content-Type и boundary. В этом примере для backend modelName — выбранная модель распознавания речи, а audioBlob содержит аудиофайл:

const baseUrl = process.env.AMAZI_AI_GATEWAY_OPENAI_BASE_URL;
const key = process.env.AMAZI_AI_GATEWAY_OPENAI_API_KEY;
const form = new FormData();
form.append("file", audioBlob, "recording.wav");
form.append("model", modelName);
form.append("response_format", "json");
const response = await fetch(baseUrl + "/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: "Bearer " + key },
  body: form,
});
if (!response.ok) throw new Error("Transcription failed: " + response.status);
const transcript = await response.json();

Настраивайте время ожидания в HTTP-клиенте или SDK провайдера своего приложения. Gateway не задаёт лимит выполнения модели. Приложение может отменить запрос, закрыв соединение; в остальных случаях оно ожидает результат или ошибку провайдера.

Для потоковых OpenAI Responses backend может запросить текущий прогресс заголовком X-Amazi-Stream-Mode: live и параметром stream: true. Текст и сводки рассуждений приходят во время работы модели. В ответе с заголовком x-amazi-live-stream: 1 списанный расход передаётся событием amazi.billing с полями chargedCredits и requestId перед завершением. Учитывайте сумму один раз по ID запроса; если события нет, показывайте отсутствие данных о расходе.

Realtime WebSocket

Realtime доступен серверным приложениям. Замените в схеме внедрённого base URL https на wss (или http на ws), добавьте /realtime?model=<точное-имя-модели> и передайте тот же bearer credential в заголовках WebSocket upgrade. События Realtime сохраняют протокол OpenAI. Не запрашивайте браузерный client secret и не переносите серверный credential во frontend-код.

Amazi не задаёт фиксированную продолжительность звонка. Сессия остаётся подключённой, пока доступен провайдер и у владельца проекта есть кредиты. Завершённые ответы тарифицируются прямо во время сессии. Транспортная ошибка Amazi приходит событием amazi.gateway.error с полями code, message, requestId, stage и retryable; используйте их в безопасных backend-логах.

Телефонные голосовые агенты

После подключения Gateway откройте SIP Realtime и создайте одного или нескольких голосовых агентов OpenAI. У каждого агента есть необязательные название, URL конфигурации backend и URL уведомлений о звонках, а также собственный SIP-адрес. Скопируйте адрес в направление переадресации любого совместимого SIP-оператора. Удаление агента отзывает его SIP-адрес и не затрагивает других агентов. В карточке подписаны сохранённые URL конфигурации, webhook звонков и Realtime WebSocket, чтобы их назначение было понятно без открытия формы редактирования. Если при создании сообщается о недоступности SIP-сервиса, агент не сохранён. Повторите попытку позже или обратитесь в поддержку, если проблема сохраняется.

Без URL конфигурации агент использует настройки сессии по умолчанию и первую Realtime-модель из текущего каталога. Добавьте URL для собственных инструкций, настроек аудио или инструментов. Если URL задан, Amazi отправляет на него авторизованный GET для каждой сессии. Preview-backend можно использовать только для ручной проверки, пока окружение запущено; активный телефонный маршрут должен использовать production URL приложения, чтобы после засыпания preview вместо JSON не вернулся wake-ответ. URL должен работать по HTTPS, быть доступен из интернета и не зависеть от browser cookies или интерактивной авторизации пользователя. Сравните bearer token с серверной переменной AMAZI_VOICE_CONFIGURATION_SECRET и верните нативный объект Realtime-сессии провайдера с полем model. Заголовки запроса также определяют сессию, голосового агента, провайдера, аудиоконтракт mono PCM16 24 кГц и URL событийного WebSocket. Backend проекта может подключиться к этому URL с внедрённым Gateway-ключом выбранного провайдера, получать события модели и без изменений возвращать результаты tools. Бизнес-логика и доступ к БД остаются в проекте; Amazi переносит события, но не исполняет проектные функции.

Кредиты и история

В чате проекта введите / и выберите Посмотреть расход проекта, чтобы открыть общую страницу AI Gateway с выбранным проектом. Фильтр сохраняется, даже если расхода ещё нет; на странице можно выбрать другой проект или все проекты.

Архивные и окончательно удалённые проекты остаются в статистике с отдельными метками В архиве и Удалён. Их можно выбрать для просмотра прошлых расходов; списания по ним продолжают учитываться в общих суммах. После восстановления архивного проекта метка архива исчезает.

Чтобы показывать точный расход внутри своего приложения, читайте заголовки x-amazi-charged-credits и x-amazi-gateway-request-id успешных HTTP-ответов на сервере. Суммируйте целые значения кредитов по уникальным ID запросов. Это уже списанная Amazi сумма с учётом кешированных токенов и округления. Если заголовков нет, показывайте отсутствие данных, а не нулевой расход.

Запросы Gateway оплачиваются с баланса текущего владельца проекта. Они используют общие плановые и купленные кредиты аккаунта вместе с личной работой агента. Страница Gateway на уровне аккаунта показывает, откуда пришёл расход: из Gateway приложения или от агента проекта. Отдельно указаны операции агента проекта, генерации изображений и распознавания аудио; прежние записи Research и Code сохраняются в истории вместе с провайдером, моделью, проектом, статусом, временем, токенами и расходом кредитов.

Если план владельца больше не включает Gateway, записи подключений сохраняются, но использование провайдера останавливается до восстановления доступа. При проблеме баланса или настроек провайдера обратитесь в поддержку; кредиты аккаунта можно пополнить на странице План.

Доступные провайдеры и модели

OpenAI