AI Gateway

Используйте учетные записи AI , подключенные к вашему собственному экземпляру AirCode Ø из ваших личных приложений. Поставьте базу ** URL**, отдельный токен приложения ****и точную модель ID. Инстанция называет своего подключенного провайдера CLI и возвращает ответ через подкомплект Заполнения чата для текста и подкомплект Изображения для изображений.

Your application's backend
  → your instance URL + application token
    → a connected native provider account
      → validated answer + available usage counters

На сайте размещается только документация. Запросы API направляются непосредственно в ваш инстант; aircodezero.com не получает ваш адрес инстанции, токен или пометки. Используйте эту услугу только для собственных приложений и учетных записей. Условия поставщика, доступ к подписке и квоты по-прежнему действуют.

Настройка

1. Подключите учетную запись совместимого носителя в AI Usage. « Gateway перечисляет модели учетных записей, поддерживаемые установленным инстанцией; API-key и управляемые кредитные соединения исключены.
2. Откройте Настройки → AI gateway на компьютере или в браузере, либо Ещё → AI gateway на мобильном устройстве. В разделе Создать доступ включите Разрешить приватные подключения.
3. Копировать изображенный Base URL. Он заканчивается /api/ai-gateway/v1.
4. В разделе Создать токен выберите Приложение, введите его имя и нажмите Создать токен. Скопируйте токен, пока он показан единственный раз. Такой выбор разрешает текстовые и графические запросы через API ИИ, но не сеансы между экземплярами.
5. Настройте следующие переменные среды сервера в своем приложении:

Сохраняйте токены в конфигурации вашего бак-энда, а не в браузерном коде, пачке мобильных приложений, репозитории, URL или совместном разговоре. Примеры читают переменные окружающей среды вместо встраивания аккредитаций. Никогда не используйте пароль инстанции или токен входа владельца в поле API-key.

Инстанция должна оставаться запущенной и доступной из бак-энда вашего приложения. localhost означает компьютер, на котором работает этот резервный блок. Используйте адрес instance HTTPS для удаленного доступа, или ваше доверенное локальное/частное сетевое соединение. Гейтвей не создает публичного происхождения. Поставщика, не перечисленного /models , нельзя выбрать, придумав ID.

Аутентификация и обнаружение моделей

Отправьте Authorization: Bearer YOUR_APPLICATION_TOKEN на каждый звонок. Отправить JSON с помощью Content-Type: application/json. Параметры запросов или аутентификация файлов cookie не поддерживаются. Перекрестные звонки браузера не поддерживаются; используйте свой бак-энд.

GET {BASE_URL}/models возвращает объект с object: "list" и матрицей data . Каждая модель обеспечивает id, выставка label, engine, engineLabel, provider, connectionLabel, efforts и capabilities: chat.completions Для текстовых моделей, images.generations и images.edits Для модели изображения. Передайте возвращенный id без изменений; он уже может содержать процентное кодирование. Список может изменяться при изменении учетных записей, доступа провайдера или установленных моделей.

Для конфигурации совместимого с OpenAI приложения выберите Chat Completions, используйте полную базу URL, поместите токен приложения в поле API key и скопируйте один из возвращенных идентификаторов модели. Изображения используют подкомплект Изображения, описанный ниже. Приложение, которое требует ответы, инструменты или не поддерживаемые параметры отбора образцов, не совместимо с текущим шлюзом.

Создать ответ

POST {BASE_URL}/chat/completions принимает следующие поля. Неизвестные поля отклоняются, а не молча игнорируются.

Сообщения содержат только role и content. Текстовые блоки присоединяются к новостям. Нулевые символы отклоняются. Нормализованный массив сообщений должен соответствовать 64 KiB UTF-8 JSON; полное тело HTTP ограничено 80 KiB. Валидированный ответ ограничен 49,152 единицами JavaScript. Это ограничения шлюзов, а не обещания о контекстном окне поставщика или выходной мощности.

Поставьте полный соответствующий разговор на каждый звонок. Чтобы продолжить разговор, приложите предыдущий ответ помощника и следующее сообщение пользователя. В портале не создается и не сохраняется история разговоров, сеансов или завершений. Токен не предоставляет доступа к проектам, файлам, терминалу, сессиям или настройкам владельца.

Нормальный ответ имеет object: "chat.completion"; читайте текст из choices[0].message.content. В него также входят id, created, запрошенные modelи finish_reason: "stop". Натуральные счетчики появляются в usage , когда они достаточно полны для отчета. Расширение aircode_usage сохраняет бухгалтерские детали и неполные оценки. Недостающие счетчики или цены неизвестны, никогда не нулевые. API-эквивалентные оценки не являются дополнительными абонентскими сборами.

Потоковый

Настройте stream: true на получение Content-Type: text/event-stream. Текущая реализация использует баферный потоковый: она отправляет первоначальный комментарий ожидания и keepalive комментарии, пока провайдер работает, а затем отправляет полный ответ после проверки. Это делает не потока слов или токенов, как они генерируются.

Успешный поток содержит:

1. SSE комментарии, начинающиеся с : в ожидании; игнорируйте их.
2. A data: JSON chat.completion.chunk с ролью помощника и полным Текст в choices[0].delta.content.
3. Часть с пустой дельтой и finish_reason: "stop".
4. Дополнительная часть с choices: [], usage (возможно, null) и aircode_usage когда stream_options.include_usage верно.
5. data: [DONE].

После начала потока неудачи приходят как событие SSE data: , содержащее error; не рассматривайте HTTP 200 как успех. Неудачный поток закрывается без маркера успеха. Рамки SSE могут быть разделены на транспортные части; используйте SDK или SSE -апсер, а не анализируйте каждую сетевую частицу как JSON.

Закрытие соединения отменяет его активное запрос. Отмена токена, отключение шлюза или остановка инстанции также отменяет соответствующую работу. Нет автоматического воспроизведения или рецидива. Долгостоящие запросы нуждаются в соответствующем клиенте и обратном прокси-времени; Keepalives не могут преодолевать абсолютный предел продолжительности запроса сети.

Создать изображение

Модель изображения перечислена, в то время как учетная запись instance native Codex может использовать свой собственный инструмент изображения, который требует плана ChatGPT, который включает в себя генерацию изображения. Его id является codex/image-generation. Codex решает, какую модель изображения он использует; шлюз не выбирает одну.

• POST {BASE_URL}/images/generations принимает JSON с model, prompt (до 32 000 символов) и опционально size, n: 1 и response_format: "b64_json".
• POST {BASE_URL}/images/edits принимает multipart/form-data с теми же полями и от 1 до 4 ссылочных изображений в image или image[]. Каждый из них должен быть PNG или JPEG не более 4 МиБ. Другие файловые поля, такие как mask, отклоняются.

size является auto или WIDTHxHEIGHT между 64 и 4096 пикселей. Она передается модели в качестве руководства; ответ сообщает о фактическом размере. Любое другое поле отклоняется, а не игнорируется.

curl -sS "$AIRCODE_AI_BASE_URL/images/edits" \
  -H "Authorization: Bearer $AIRCODE_AI_TOKEN" \
  -F model=codex/image-generation \
  -F "prompt=Place this product in a premium studio shot on a stone pedestal." \
  -F size=1024x1536 \
  -F image=@product.png

Один ответ несет created, один data[0].b64_json, output_format (png, jpeg или webp), фактический size и aircode_usage. Бухгалтерский учет охватывает агента, который запустил инструмент изображения; провайдер не сообщает о собственной стоимости инструмента изображения, поэтому costComplete всегда является false. Поколение обычно занимает от одной до трех минут, делится ограничениями ниже с текстовыми звонками и отменяется, когда клиент отключается. Когда модель отвечает без изображения, вызов не удается с 422 AI_GATEWAY_NO_IMAGE и предложением модели, если она дала одно.

Автоматически подключить сохраненное приложение AirCode Ø

Приложение, сохраненное в Apps , которое работает на своем собственном сервере, может получать этот доступ без копирования токена. На странице приложения откройте Настройки → Доступ → AI учетные записи и включите его. AirCode Ø тогда:

1. Включает частный AI шлюз, если он был выключен;
2. Перезапускает приложение и, при каждом запуске, дает своему серверу свежий токен собственный, отменяя токен предыдущего старта;
3. Задает AIRCODE_AI_BASE_URL (вход на адрес, на котором прослушивается инстанция), AIRCODE_AI_TOKEN и, если есть, AIRCODE_AI_MODEL (текстовая модель) и AIRCODE_AI_IMAGE_MODEL (модель изображения).

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

Котировки, жизненный цикл токенов и ошибки

Gateway позволяет проводить два активных вызова по всему случаю, один активный вызов за токен и 30 допущенных запросов генерации за токен в минуту. Звонки не подвешиваются. Эти местные ограничения не заменяют квоты поставщиков. Токены истекают через 90 дней; создайте замену, обновите свое приложение, а затем отмените предыдущий токен. Отключение шлюза сохраняет токены, но приостанавливает их использование. Восстановление состояния инстанции отключает шлюз и очищает авторитет токенов; создает новые токены.

Ошибки используют error.message, error.type, error.code и error.param. Читайте код, а также статус HTTP . Не следует автоматически переводить поколение, исход которого неизвестен: оно может уже потреблять квоты поставщиков. В примерах отключены ретрии SDK .

Время перезагрузки неизвестного провайдера остается неизвестным. Никогда не делайте одно из названия модели или расписания квот несвязанного поставщика.

Использование другого экземпляра из приложения

Внешнее приложение может обращаться к другому собственному экземпляру по его Base URL с токеном, созданным на нём. Токен принадлежит выдавшему его экземпляру. Чтобы агент на B работал с проектом A, при создании токена на B выберите Другой экземпляр и следуйте руководству по удалённым сеансам. По умолчанию файлы и команды остаются на A. Сохраните подключение на A, выберите B в Новый сеанс → Запустить на и оставьте Расположение проекта → Этот экземпляр. Для работы с проектом на B при создании токена на B выберите Этот экземпляр и проект, а при запуске на A — Расположение проекта → Удалённый экземпляр. Оба режима передают события в реальном времени. Обычные токены поддерживают текст и изображения, но не выполняют вход от имени владельца удалённого экземпляра. Вызовы инструментов через Responses, Anthropic Messages и Chat Completions не входят в поддерживаемую текстовую API.

Для AI Помощь в интеграции, см. Документация для AI, The Равный Markdown Руководство, The OpenAPI схема, а также The Интеграционные навыки.

Примеры кода

Установите три переменных среды выше, прежде чем запустить пример. Эти фрагменты также доступны в Настройки и в руководстве Raw Markdown.

set -euo pipefail
# The token is read from standard input, not a command-line argument.
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/models" --header @- <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

body=$(jq -n --arg model "$AIRCODE_AI_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello!"}]}')
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/chat/completions" \
  --header 'Content-Type: application/json' \
  --header @- --data "$body" <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

import os
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    base_url=os.environ["AIRCODE_AI_BASE_URL"],
    api_key=os.environ["AIRCODE_AI_TOKEN"],
    max_retries=0,
    http_client=DefaultHttpx2Client(follow_redirects=False),
)

for model in client.models.list():
    print(model.id)

response = client.chat.completions.create(
    model=os.environ["AIRCODE_AI_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

function required(name) {
  if (!process.env[name]) throw new Error("Set " + name + " first.");
  return process.env[name];
}

const client = new OpenAI({
  baseURL: required("AIRCODE_AI_BASE_URL"),
  apiKey: required("AIRCODE_AI_TOKEN"),
  maxRetries: 0,
  fetchOptions: { redirect: "error" },
});

const stream = await client.chat.completions.create({
  model: required("AIRCODE_AI_MODEL"),
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true },
});

try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
    if (chunk.usage) console.error("Tokens:", chunk.usage.total_tokens);
  }
  process.stdout.write("\n");
} finally {
  stream.controller.abort();
}

Конфигурация SDK ссылки:OpenAI SDK для Pythonи OpenAI JavaScript SDK. Этот шлюз поддерживает подкомплект, документированный выше.