# AI Gateway — полный текст документации > Полный текст раздела «AI Gateway» документации Timeweb Cloud в markdown. Каждая статья начинается с заголовка первого уровня и ссылки на свою каноническую страницу. Индекс: https://timeweb.cloud/docs/ai-gateway/llms.txt Статей: 7 Последнее обновление: 2026-10-22 # AI Gateway Source: https://timeweb.cloud/docs/ai-gateway AI Gateway — это API для работы напрямую с языковыми моделями без использования AI-агентов. В отличие от [OpenAI-совместимого API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api) и [нативного API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api), AI Gateway не предоставляет возможности агентов, такие как: - RAG; - MCP; - Системные настройки (системный промпт, температура, ограничения на длину ответа). AI Gateway подходит, когда требуется работать с моделями напрямую, без логики AI-агента. Например: - если вы реализуете собственную логику поверх моделей (строите RAG, подключение MCP); - если нужна единая точка доступа к нескольким моделям; - если вы уже используете OpenAI SDK и хотите переключаться между моделями без изменения кода. Отличия AI Gateway от OpenAI-совместимого API: | | **OpenAI-совместимый API** | **AI Gateway** | | --- | --- | --- | | **Объект работы** | Агент | Модель | | **RAG / MCP** | Есть | Нет | | **Системные настройки** | Можно задать в панели управления агента | Передаются с каждым запросом | | **Выбор модели** | Модель агента | Любая доступная | Для работы с API рекомендуется использовать OpenAI SDK — он абстрагирует различия и упрощает интеграцию. Поддерживаемые методы и возможности зависят от используемой модели. Например, эндпоинт `responses` доступен только для моделей с поддержкой размышлений. В AI Gateway не поддерживаются: - `Fine-tuning` — обучение и кастомизация моделей; - `Video API` — работа с видео. ## Управление AI Gateway Для работы с AI Gateway перейдите во вкладку «AI Gateway» в разделе «ИИ-сервисы». В интерфейсе доступны три вкладки: - «Модели»; - «Подключение»; - «API-ключи». ### Выбор модели Во вкладке «Модели» отображаются доступные модели и их параметры: - тип; - объем контекста; - максимальная длина ответа; - стоимость входящих и исходящих токенов. Чтобы найти подходящую модель, отфильтруйте список по типу или провайдеру либо введите название модели в поле поиска. ![Модели](https://content.timeweb.com/assets/dab6ed12-59ec-4741-9c82-305bd6452a98.png?width=2244&height=1596) Для сопоставления характеристик нажмите «Сравнить модели» и выберите нужные модели. ### Получение параметров подключения Во вкладке «Подключение» выберите модель и инструмент — язык программирования, для которого требуется пример. В интерфейсе отобразятся: - базовый URL для подключения; - стоимость входящих и исходящих токенов выбранной модели; - команда для установки библиотеки OpenAI; - базовый пример подключения к API. ![ПОдключение](https://content.timeweb.com/assets/b6b57ae6-dfb2-4c62-a624-0e01548a8365.png?width=2166&height=1942) ### Создание API-ключа AI Gateway использует отдельные ключи, не связанные с API-ключами аккаунта. > [!NOTE] > Каждый API-ключ тарифицируется отдельно и стоит 1 ₽ в месяц. Чтобы создать API-ключ: 1. Перейдите во вкладку «API-ключи» и нажмите «Добавить». 2. Укажите имя ключа и при необходимости добавьте комментарий. 3. Выберите срок действия: 30, 60 или 90 дней, один год либо бессрочно. 4. Выберите проект, в который будет добавлен ключ. 5. Нажмите «Создать». ![Создание ключа](https://content.timeweb.com/assets/f11ad7ee-c3af-4663-859b-74d2ea002377.png?width=2758&height=1962) После создания ключ отобразится один раз. Скопируйте его и сохраните в надежном месте — повторно посмотреть ключ не получится. ### Управление API-ключами Во вкладке «API-ключи» отображаются все созданные ключи, даты их создания, сроки действия и комментарии. Чтобы перегенерировать или удалить ключ, нажмите на три точки рядом с ним и выберите нужное действие. ![Ключи](https://content.timeweb.com/assets/9be63129-4020-4eee-9c62-4445646cc30b.png?width=2180&height=1640) Кликните на карточку ключа, чтобы перейти в его панель управления. В ней доступны две вкладки: - «Дашборд» — позволяет отслеживать количество входящих и исходящих токенов, их расход и количество запросов. Статистику можно отфильтровать по периоду и модели; - «Управление» — позволяет [установить лимит](https://timeweb.cloud/docs/ai-agents/pricing/token-limit) на использование токенов. ![Дашборд](https://content.timeweb.com/assets/34de0159-6c21-44fb-9564-e05d39e4a7e8.png?width=2170&height=1618) ## Использование Для работы с AI Gateway рекомендуем использовать OpenAI SDK — с ним не нужно вручную отправлять HTTP-запросы и интеграция становится проще. Доступные SDK: - [Python](https://github.com/openai/openai-python) - [Node.js](https://github.com/openai/openai-node) - [Java](https://github.com/openai/openai-java) - [Go](https://github.com/openai/openai-go) Полный список SDK доступен [в репозитории OpenAI](https://github.com/orgs/openai/repositories). В примерах ниже мы используем Python и библиотеку `openai`. Установить ее можно с помощью `pip`: ```bash pip install openai ``` ### Отправка запроса Для отправки сообщений используется метод `Chat Completions`. При его использовании сообщения передаются в массиве `messages`. Каждое сообщение содержит: - `role` — [роль отправителя](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#roli) (`user`, `assistant`, `system`); - `content` — текст сообщения. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.chat.completions.create( model="MODEL_NAME", messages=[ { "role": "system", "content": "Отвечай кратко и по существу.", }, { "role": "user", "content": "Объясни, что такое Kubernetes", }, ], ) print(response.choices[0].message.content) ``` Параметры: - `api_key` — API-ключ AI Gateway. Замените значение на ваш ключ. - `base_url` — базовый URL для подключения к AI Gateway. - `model` — имя используемой модели. Укажите модель, которую хотите использовать. - `messages` — массив сообщений с ролями и текстом. ### Отправка запроса с историей сообщений Чтобы сохранить контекст диалога, передавайте предыдущие сообщения в массиве `messages`: ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.chat.completions.create( model="MODEL_NAME", messages=[ { "role": "system", "content": "Отвечай только короткими фразами.", }, { "role": "user", "content": "Сколько будет 2 + 5?", }, { "role": "assistant", "content": "7", }, { "role": "user", "content": "Теперь умножь результат на 2", }, ], ) print(response.choices[0].message.content) ``` В примере передаются предыдущие сообщения (`assistant` и `user`), чтобы сохранить контекст диалога. ### Отправка запроса (Responses API) `Responses API` — более новый способ работы с моделями. Он упрощает структуру запроса и не требует явного формирования массива `messages`. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.responses.create( model="MODEL_NAME", instructions="Отвечай кратко и по существу.", input="Объясни, что такое Kubernetes" ) print(response.output_text) ``` Параметры: - `model` — имя используемой модели; - `instructions` — инструкция для модели (аналог системного промпта); - `input` — текст запроса. ### Отправка запроса с историей сообщений (Responses API) Чтобы сохранить контекст диалога при использовании Responses API, укажите `previous_response_id` — идентификатор предыдущего ответа. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.responses.create( model="MODEL_NAME", instructions="Отвечай только короткими фразами.", input="Сколько будет 2 + 5?" ) next_response = client.responses.create( model="MODEL_NAME", instructions="Отвечай только короткими фразами.", previous_response_id=response.id, input="Теперь умножь результат на 2" ) print(next_response.output_text) ``` В этом примере первый запрос возвращает объект ответа, содержащий уникальный идентификатор `id`. Этот идентификатор передается в параметре `previous_response_id` при следующем запросе, что позволяет продолжить диалог без передачи всей истории сообщений. Параметр `model` необходимо указывать в каждом запросе, включая последующие вызовы с `previous_response_id`. ### Получение списка моделей AI Gateway позволяет получить список доступных моделей: ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) models = client.models.list() for model in models.data: print(model.id) ``` Метод `models.list()` возвращает список моделей, которые можно использовать в параметре `model`. ### Использование embeddings `Embeddings` используются для преобразования текста в векторное представление. Это может применяться, например, для поиска по смыслу, кластеризации или работы с RAG. В AI Gateway для создания embeddings доступна модель `openai/text-embedding-3-large`. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.embeddings.create( model="openai/text-embedding-3-large", input="Текст для векторизации", ) print(response.data[0].embedding) ``` Метод возвращает векторное представление переданного текста. # Управление AI Gateway Source: https://timeweb.cloud/docs/ai-gateway/manage Для работы с AI Gateway перейдите во вкладку «AI Gateway» в разделе «ИИ-сервисы». В интерфейсе доступны три вкладки: - «Модели»; - «Подключение»; - «API-ключи». ### Выбор модели Во вкладке «Модели» отображаются доступные модели и их параметры: - тип; - объем контекста; - максимальная длина ответа; - стоимость входящих и исходящих токенов. Чтобы найти подходящую модель, отфильтруйте список по типу или провайдеру либо введите название модели в поле поиска. ![Модели](https://content.timeweb.com/assets/dab6ed12-59ec-4741-9c82-305bd6452a98.png?width=2244&height=1596) Для сопоставления характеристик нажмите «Сравнить модели» и выберите нужные модели. ### Получение параметров подключения Во вкладке «Подключение» выберите модель и инструмент — язык программирования, для которого требуется пример. В интерфейсе отобразятся: - базовый URL для подключения; - стоимость входящих и исходящих токенов выбранной модели; - команда для установки библиотеки OpenAI; - базовый пример подключения к API. ![ПОдключение](https://content.timeweb.com/assets/b6b57ae6-dfb2-4c62-a624-0e01548a8365.png?width=2166&height=1942) ### Создание API-ключа AI Gateway использует отдельные ключи, не связанные с API-ключами аккаунта. > [!NOTE] > Каждый API-ключ тарифицируется отдельно и стоит 1 ₽ в месяц. Чтобы создать API-ключ: 1. Перейдите во вкладку «API-ключи» и нажмите «Добавить». 2. Укажите имя ключа и при необходимости добавьте комментарий. 3. Выберите срок действия: 30, 60 или 90 дней, один год либо бессрочно. 4. Выберите проект, в который будет добавлен ключ. 5. Нажмите «Создать». ![Создание ключа](https://content.timeweb.com/assets/f11ad7ee-c3af-4663-859b-74d2ea002377.png?width=2758&height=1962) После создания ключ отобразится один раз. Скопируйте его и сохраните в надежном месте — повторно посмотреть ключ не получится. ### Управление API-ключами Во вкладке «API-ключи» отображаются все созданные ключи, даты их создания, сроки действия и комментарии. Чтобы перегенерировать или удалить ключ, нажмите на три точки рядом с ним и выберите нужное действие. ![Ключи](https://content.timeweb.com/assets/9be63129-4020-4eee-9c62-4445646cc30b.png?width=2180&height=1640) Кликните на карточку ключа, чтобы перейти в его панель управления. В ней доступны две вкладки: - «Дашборд» — позволяет отслеживать количество входящих и исходящих токенов, их расход и количество запросов. Статистику можно отфильтровать по периоду и модели; - «Управление» — позволяет [установить лимит](https://timeweb.cloud/docs/ai-agents/pricing/token-limit) на использование токенов. ![Дашборд](https://content.timeweb.com/assets/34de0159-6c21-44fb-9564-e05d39e4a7e8.png?width=2170&height=1618) ## Использование Для работы с AI Gateway рекомендуем использовать OpenAI SDK — с ним не нужно вручную отправлять HTTP-запросы и интеграция становится проще. Доступные SDK: - [Python](https://github.com/openai/openai-python) - [Node.js](https://github.com/openai/openai-node) - [Java](https://github.com/openai/openai-java) - [Go](https://github.com/openai/openai-go) Полный список SDK доступен [в репозитории OpenAI](https://github.com/orgs/openai/repositories). В примерах ниже мы используем Python и библиотеку `openai`. Установить ее можно с помощью `pip`: ```bash pip install openai ``` ### Отправка запроса Для отправки сообщений используется метод `Chat Completions`. При его использовании сообщения передаются в массиве `messages`. Каждое сообщение содержит: - `role` — [роль отправителя](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#roli) (`user`, `assistant`, `system`); - `content` — текст сообщения. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.chat.completions.create( model="MODEL_NAME", messages=[ { "role": "system", "content": "Отвечай кратко и по существу.", }, { "role": "user", "content": "Объясни, что такое Kubernetes", }, ], ) print(response.choices[0].message.content) ``` Параметры: - `api_key` — API-ключ AI Gateway. Замените значение на ваш ключ. - `base_url` — базовый URL для подключения к AI Gateway. - `model` — имя используемой модели. Укажите модель, которую хотите использовать. - `messages` — массив сообщений с ролями и текстом. ### Отправка запроса с историей сообщений Чтобы сохранить контекст диалога, передавайте предыдущие сообщения в массиве `messages`: ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.chat.completions.create( model="MODEL_NAME", messages=[ { "role": "system", "content": "Отвечай только короткими фразами.", }, { "role": "user", "content": "Сколько будет 2 + 5?", }, { "role": "assistant", "content": "7", }, { "role": "user", "content": "Теперь умножь результат на 2", }, ], ) print(response.choices[0].message.content) ``` В примере передаются предыдущие сообщения (`assistant` и `user`), чтобы сохранить контекст диалога. ### Отправка запроса (Responses API) `Responses API` — более новый способ работы с моделями. Он упрощает структуру запроса и не требует явного формирования массива `messages`. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.responses.create( model="MODEL_NAME", instructions="Отвечай кратко и по существу.", input="Объясни, что такое Kubernetes" ) print(response.output_text) ``` Параметры: - `model` — имя используемой модели; - `instructions` — инструкция для модели (аналог системного промпта); - `input` — текст запроса. ### Отправка запроса с историей сообщений (Responses API) Чтобы сохранить контекст диалога при использовании Responses API, укажите `previous_response_id` — идентификатор предыдущего ответа. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.responses.create( model="MODEL_NAME", instructions="Отвечай только короткими фразами.", input="Сколько будет 2 + 5?" ) next_response = client.responses.create( model="MODEL_NAME", instructions="Отвечай только короткими фразами.", previous_response_id=response.id, input="Теперь умножь результат на 2" ) print(next_response.output_text) ``` В этом примере первый запрос возвращает объект ответа, содержащий уникальный идентификатор `id`. Этот идентификатор передается в параметре `previous_response_id` при следующем запросе, что позволяет продолжить диалог без передачи всей истории сообщений. Параметр `model` необходимо указывать в каждом запросе, включая последующие вызовы с `previous_response_id`. ### Получение списка моделей AI Gateway позволяет получить список доступных моделей: ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) models = client.models.list() for model in models.data: print(model.id) ``` Метод `models.list()` возвращает список моделей, которые можно использовать в параметре `model`. ### Использование embeddings `Embeddings` используются для преобразования текста в векторное представление. Это может применяться, например, для поиска по смыслу, кластеризации или работы с RAG. В AI Gateway для создания embeddings доступна модель `openai/text-embedding-3-large`. ```py from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.timeweb.ai/v1" ) response = client.embeddings.create( model="openai/text-embedding-3-large", input="Текст для векторизации", ) print(response.data[0].embedding) ``` Метод возвращает векторное представление переданного текста. # Files API Source: https://timeweb.cloud/docs/ai-gateway/files-api Files API позволяет загружать файлы в AI Gateway и передавать их моделям в запросах. Это удобно, когда модели нужно обработать документ, таблицу, текстовый файл или другой материал, который не требуется каждый раз вставлять в тело запроса. Файл загружается один раз, после чего AI Gateway возвращает его идентификатор. Этот идентификатор можно использовать в последующих запросах к модели. ## Подготовка токена Для работы с Files API нужен [API-ключ AI Gateway](https://timeweb.cloud/docs/ai-gateway/manage#sozdanie-api-klucha). Создать ключ можно в разделе «ИИ-сервисы» во вкладке «AI Gateway» → «API-ключи». В примерах используется переменная окружения `TIMEWEB_AI_TOKEN`, чтобы не указывать ключ напрямую в каждом запросе. На Linux и macOS переменную можно задать командой: ```bash export TIMEWEB_AI_TOKEN="ваш_API-ключ" ``` После этого значение переменной будет доступно в текущей сессии терминала. Чтобы переменная сохранялась после перезапуска терминала, добавьте эту же строку в файл конфигурации вашей оболочки, например `~/.zshrc` для zsh или `~/.bashrc` для bash. ## Методы API Ниже приведены методы для работы с файлами через API. Для запросов к уже загруженному файлу используется идентификатор `file_id`, который возвращается при загрузке. ### Загрузка файла Чтобы загрузить файл, отправьте POST-запрос на эндпоинт `/v1/files`: ```bash curl --request POST \ --url https://api.timeweb.ai/v1/files \ --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \ --header "content-type: multipart/form-data" \ --form purpose=user_data \ --form "file=@" \ --form "target_model_names=openai/gpt-4.1" ``` Параметры: - `purpose` — назначение файла. В AI Gateway поддерживаются только значения `user_data` и messages. Значение `user_data` используется для работы с файлами в запросах к моделям, `messages` доступно при работе с моделями Claude. Другие значения `purpose` не поддерживаются. - `file` — путь к локальному файлу. Перед путем указывается символ `@`, например `file=@/Users/timeweb_cloud/test.txt`. - `target_model_names` — имена моделей, для которых загружается файл. Если файл должен быть доступен нескольким моделям, перечислите их через запятую, например `target_model_names=openai/gpt-4.1,openai/gpt-5`. Корректные имена моделей можно найти во вкладке «Подключение» в разделе AI Gateway. Загруженный файл будет доступен только для модели, указанной в параметре `model`. Пример ответа: ```js { "id": "file-bGl0ZWxsbTpmaWxlLUdmMWRD1mDEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI", "bytes": 27, "created_at": 1782804439, "filename": "testfile.txt", "object": "file", "purpose": "user_data", "status": "processed", "expires_at": null, "status_details": null } ``` Для дальнейшей работы с файлом используйте значение поля `id`. ### Получение информации о файле Метод позволяет получить метаданные загруженного файла: ```bash curl --request GET \ --url https://api.timeweb.ai/v1/files/ \ --header "authorization: Bearer $TIMEWEB_AI_TOKEN" ``` Где `file_id` — идентификатор файла, полученный при загрузке. ### Получение содержимого файла Метод `/content` реализован для совместимости с Files API и дальнейшего расширения сценариев работы с файлами: ```bash curl --request GET \ --url https://api.timeweb.ai/v1/files//content \ --header "authorization: Bearer $TIMEWEB_AI_TOKEN" ``` Получение содержимого доступно только для подходящих значений purpose, например для сценариев `fine-tuning`. Такие сценарии сейчас не поддерживаются в AI Gateway. Для файлов с `purpose=user_data` или `purpose=messages` метод для чтения содержимого файла не используется. ### Удаление файла Чтобы удалить файл, отправьте DELETE-запрос: ```bash curl --request DELETE \ --url https://api.timeweb.ai/v1/files/ \ --header "authorization: Bearer $TIMEWEB_AI_TOKEN" ``` После удаления идентификатор файла нельзя использовать в запросах к модели. ## Пример работы с файлом Рассмотрим пример с загрузкой текстового файла `test.txt`, который расположен по пути `/Users/timeweb_cloud/test.txt`. ```bash curl --request POST \ --url https://api.timeweb.ai/v1/files \ --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \ --header "content-type: multipart/form-data" \ --form purpose=user_data \ --form "file=@/Users/timeweb_cloud/test.txt" \ --form "target_model_names=openai/gpt-4.1" ``` В параметре `file` указан полный путь к файлу на локальном компьютере. Если файл находится в текущей директории терминала, можно указать относительный путь, например `file=@test.txt`. Пример ответа: ```js { "id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI", "bytes": 27, "created_at": 1782804439, "filename": "test.txt", "object": "file", "purpose": "user_data", "status": "processed", "expires_at": null, "status_details": null } ``` После загрузки файл можно передать модели в Responses API. Для этого в запросе используется объект с типом `input_file`, а в поле `file_id` передается идентификатор из ответа на загрузку: ```shell curl https://api.timeweb.ai/v1/responses \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \ --data '{ "model": "openai/gpt-4.1", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Прочитай загруженный файл и кратко перескажи, что в нем написано." }, { "type": "input_file", "file_id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI" } ] } ] }' ``` Модель в запросе должна совпадать с моделью, для которой файл был загружен. # Batch API Source: https://timeweb.cloud/docs/ai-gateway/batch-api Batch API (пакетная обработка запросов) позволяет отправить несколько запросов к модели одним файлом и получить результаты после завершения обработки. Запросы выполняются в фоновом режиме в течение 24 часов, обычно быстрее. Пакетная обработка подходит для задач, в которых ответ не нужен сразу, например: - перевода большого количества текстов; - классификации отзывов и обращений; - подготовки описаний товаров; - создания векторных представлений текста (embeddings). При использовании Batch API запросы к моделям становятся вдвое дешевле обычных запросов. Для использования Batch API: 1. Подготовьте и загрузите JSONL-файл с запросами. 2. Создайте на его основе пакетную задачу — батч. 3. Проверяйте статус батча до завершения обработки. 4. Скачайте файлы с результатами и ошибками отдельных запросов. Batch API совместим с OpenAI SDK. ## Поддерживаемые модели и ограничения Batch API доступен только в AI Gateway. Ключи AI-агентов для пакетной обработки не подходят. Поддерживаются только модели OpenAI, для которых включена пакетная обработка: - чат-модели, например `openai/gpt-4.1-mini`, — через эндпоинт `/v1/chat/completions`; - модели для создания embeddings из семейства `openai/text-embedding-*` — через эндпоинт `/v1/embeddings`. Ограничения JSONL-файла: | **Параметр** | **Ограничение** | | --- | --- | | Формат | JSONL: один JSON-объект на строку | | Количество запросов | До 50 000 на файл | | Размер файла | До 50 МБ | | Модель | Одна на весь файл | | Эндпоинт | Один на весь файл | | Срок обработки | До 24 часов | Внутри запросов не поддерживаются: - параметры `stream` и `store`; - инструменты, кроме `function`, например `web_search` и `file_search`; - аудио и изображения во входных данных; - ссылки на файлы через `file_id`; Запросы с неподдерживаемыми параметрами возвращаются с ошибкой. ## Тарификация Стоимость обработки рассчитывается по входящим и исходящим токенам с учетом множителя Batch API — 0,5 от обычной стоимости запросов к выбранной модели. ### Резервирование средств При создании батча на балансе аккаунта резервируются средства на обработку всего файла. Сумма складывается из стоимости входящих токенов и предполагаемой стоимости исходящих токенов по цене пакетной обработки. Количество исходящих токенов определяется отдельно для каждой строки: - если указан `max_tokens`, для расчета используется это значение; - если `max_tokens` не указан, резерв рассчитывается исходя из максимальной длины ответа выбранной модели — `max_completion_tokens`. Этот максимум учитывается для каждого запроса в файле, поскольку заранее определить фактическую длину ответов невозможно. Поэтому без `max_tokens` сумма резерва может значительно превышать итоговую стоимость обработки. Чтобы ограничить резерв, указывайте значение с учетом ожидаемой длины ответа. Зарезервированная сумма сразу вычитается из отображаемого баланса и становится недоступна для других платных действий. При этом окончательная стоимость батча определяется только после завершения обработки. ### Средства на работу других сервисов Для создания батча на аккаунте должно хватать средств не только на резерв, но и на 30 часов работы остальных сервисов. Это необходимо, чтобы резервирование средств для батча не приводило к их блокировке. Например, если на балансе 5 000 ₽, а остальные сервисы расходуют 500 ₽ в сутки, на 30 часов их работы потребуется: 500 × 30 / 24 = 625 ₽. Для резервирования под батч останется 4 375 ₽, если на аккаунте нет других зарезервированных сумм. Если доступных средств недостаточно, API вернет ошибку `402 Insufficient funds`. В этом случае можно пополнить баланс, уменьшить количество запросов в файле или сократить максимальную длину ответа. ### Списание после обработки После завершения батча рассчитывается стоимость фактически использованных токенов. Оплачиваются только успешные запросы с кодом `200`. Запросы с ошибками не оплачиваются. Неиспользованная часть резерва сразу возвращается в доступный баланс. Например, если для батча было зарезервировано 1 000 ₽, а фактическая стоимость обработки составила 200 ₽, на балансе снова станут доступны 800 ₽. Фактический расход отображается в истории расходов как расход по модели. Если батч завершился со статусом: - `expired` или `cancelled` — оплачиваются успешные запросы, которые успели выполниться; остаток резерва возвращается в доступный баланс; - `failed` — списания нет, весь резерв возвращается в доступный баланс. ### Дневные лимиты ключа Batch API учитывает дневные лимиты API-ключа. При создании батча проверяется, укладывается ли оценка расхода в оставшийся лимит в рублях или токенах. Фактический расход записывается в лимит после завершения обработки. Например, если оставшийся дневной лимит составляет 5 000 ₽, а батч без `max_tokens` требует резерва в 7 000 ₽, его создание будет отклонено. Батч не запустится и придет уведомление о достижении лимита. Это произойдет, даже если фактическая стоимость обработки была бы сильно ниже лимита (например, 500 ₽): при создании проверяется сумма резерва. При отказе дневной лимит не расходуется. ## Пример пакетной обработки запросов Рассмотрим пример пакетного перевода двух текстов с помощью модели `openai/gpt-4.1-mini`. ### Подготовка файла с запросами Создайте файл `batch.jsonl` со следующим содержимым: ```js {"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"Переведи на русский: Hello!"}],"max_tokens":500}} {"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"Переведи на русский: Thank you for your order."}],"max_tokens":500}} ``` Каждый JSON-объект должен занимать одну строку. Объединять запросы в массив и ставить запятые между строками не нужно. Параметры: - `custom_id` — идентификатор запроса, уникальный в пределах файла. По нему вы сможете сопоставить ответ с исходным запросом. - `method` — HTTP-метод. - `url` — эндпоинт для обработки запроса: `/v1/chat/completions` для чат-моделей или `/v1/embeddings` для создания эмбеддингов. Значение должно быть одинаковым во всех строках файла. - `body` — тело запроса к модели. В примере оно содержит имя модели `model`, массив сообщений `messages` и ограничение длины ответа `max_tokens`. Для чат-запросов рекомендуем задавать `max_tokens` с учетом ожидаемой длины ответа. Этот параметр влияет на сумму, которая резервируется при создании батча. Без него резерв будет больше. ### Загрузка файла Отправьте файл через Files API с назначением `purpose=batch`: ```shell curl --request POST \ --url https://api.timeweb.ai/v1/files \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \ --form "purpose=batch" \ --form "file=@batch.jsonl" ``` Параметры: - `purpose` — назначение файла. Для пакетной обработки укажите `batch`. - `file` — путь к файлу на локальном компьютере. Перед путем указывается символ `@`. Для файлов с `purpose=batch` модель определяется из содержимого файла. Параметр `target_model_names` передавать не нужно. Сохраните значение `id` из ответа — оно понадобится для создания батча. ### Создание батча Отправьте POST-запрос на эндпоинт `/v1/batches`: ```shell curl --request POST \ --url https://api.timeweb.ai/v1/batches \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "input_file_id": "FILE_ID", "endpoint": "/v1/chat/completions", "completion_window": "24h" }' ``` Параметры: - `input_file_id` — идентификатор загруженного файла. Замените `FILE_ID` на значение `id` из предыдущего шага. - `endpoint` — эндпоинт обработки. Он должен совпадать со значением `url` в строках файла. - `completion_window` — срок обработки батча. Укажите `24h`. В ответе API вернет объект батча со статусом `validating`. Сохраните его `id` для проверки статуса и отмены задачи. При создании батча на балансе резервируются средства на обработку всего файла. Если доступных средств недостаточно, API вернет ошибку `402 Insufficient funds`. ### Проверка статуса Чтобы узнать состояние батча, отправьте GET-запрос, заменив `BATCH_ID` на его идентификатор: ```shell curl --request GET \ --url "https://api.timeweb.ai/v1/batches/BATCH_ID" \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" ``` Текущее состояние отображается в поле `status`: | **Статус** | **Описание** | | --- | --- | | `validating` | Выполняется проверка входных данных | | `in_progress` | Запросы обрабатываются | | `finalizing` | Подготавливаются результаты | | `completed` | Обработка завершена. В отдельных запросах могут быть ошибки | | `failed` | Батч завершился с ошибкой | | `expired` | Истек срок обработки | | `cancelled` | Батч отменен | Повторяйте запрос для проверки состояния, пока обработка не завершится. Успешный батч проходит статусы `validating` → `in_progress` → `finalizing` → `completed`. Статусы `failed`, `expired` и `cancelled` также означают завершение задачи — ждать перехода в `completed` в этих случаях не нужно. Получить список батчей, доступных текущему ключу, можно отдельным запросом: ```shell curl --request GET \ --url https://api.timeweb.ai/v1/batches \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" ``` ### Получение результатов После завершения обработки получите актуальную информацию о батче. Для скачивания файлов используются поля: - `output_file_id` — идентификатор файла с результатами; - `error_file_id` — идентификатор файла с ошибками отдельных запросов. Если в поле `output_file_id` есть идентификатор, подставьте его вместо `OUTPUT_FILE_ID` и скачайте результаты: ```shell curl --request GET \ --url "https://api.timeweb.ai/v1/files/OUTPUT_FILE_ID/content" \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \ --output results.jsonl ``` Результаты сохранятся в файл `results.jsonl` в текущей директории. Каждая строка содержит JSON-объект с полями: - `custom_id` — идентификатор исходного запроса; - `response.status_code` — HTTP-код ответа; - `response.body` — тело ответа модели; - `error` — информация об ошибке, если она есть. Порядок строк в результатах может отличаться от порядка во входном файле. Сопоставляйте запросы и ответы по `custom_id`. Пример строки из файла результатов для первого запроса: ```js {"id":"batch_req_b83d7a9e420f4c6198a56e2d03f7c145","custom_id":"req-a7f3","response":{"status_code":200,"request_id":"e7294b18-6c3a-4f85-9d02-a147c8e65b30","body":{"id":"chatcmpl-K7m2R9v4N6p8T1x3B5q0C2d4F6h8J","object":"chat.completion","created":1791804147,"model":"gpt-4.1-mini-2025-04-14","choices":[{"index":0,"message":{"role":"assistant","content":"\u041f\u0440\u0438\u0432\u0435\u0442!","refusal":null,"annotations":[]},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":15,"completion_tokens":3,"total_tokens":18,"prompt_tokens_details":{"cached_tokens":0,"audio_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"service_tier":"default","system_fingerprint":"fp_a83b72d901"}},"error":null} ``` Значение `content` в этом примере — «Привет!». Кириллица записывается в виде Unicode escape-последовательностей `\uXXXX`: это экранирование символов в JSON. Если у вас установлен `jq`, вывести идентификатор и текст ответа для каждой строки можно командой: ```shell jq -r '[.custom_id, .response.body.choices[0].message.content] | @tsv' results.jsonl ``` Для двух запросов из примера вывод может выглядеть так: ```shell 1 Привет! 2 Спасибо за ваш заказ. ``` Если в поле `error_file_id` есть идентификатор, скачайте файл ошибок, заменив `ERROR_FILE_ID` на его значение: ```shell curl --request GET \ --url "https://api.timeweb.ai/v1/files/ERROR_FILE_ID/content" \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \ --output errors.jsonl ``` Статус `completed` не гарантирует, что все запросы выполнены успешно. Проверьте файл ошибок: он содержит код и описание ошибки для каждого неуспешного запроса. Исправленные запросы можно отправить новым батчем. При отмене батча или истечении срока обработки запросы, которые успели выполниться, доступны в результатах. > [!NOTE] > Файл результатов хранится 30 дней. Скачайте его до окончания этого срока. ## Пример пакетного создания эмбеддингов Для пакетного создания embeddings подготовьте отдельный JSONL-файл. Используйте модель, для которой включена пакетная обработка, и эндпоинт `/v1/embeddings`. Например, строка запроса для модели `openai/text-embedding-3-large` выглядит так: ```shell {"custom_id":"embedding-1","method":"POST","url":"/v1/embeddings","body":{"model":"openai/text-embedding-3-large","input":"Текст для векторизации"}} ``` Загрузите файл с `purpose=batch`, затем создайте батч со значением `endpoint` равным `/v1/embeddings`. Проверка статуса и получение результатов выполняются так же, как для чат-запросов. ## Отмена батча Чтобы отменить обработку, отправьте POST-запрос, заменив `BATCH_ID` на идентификатор батча: ```shell curl --request POST \ --url "https://api.timeweb.ai/v1/batches/BATCH_ID/cancel" \ --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" ``` Успешные запросы, выполненные до отмены, попадут в результаты и будут оплачены. Остальные запросы не выполняются и не оплачиваются. Неиспользованный резерв возвращается в доступный баланс. # Работа с аудио Source: https://timeweb.cloud/docs/ai-gateway/audio-api В AI Gateway доступны модели для синтеза и распознавания речи. С их помощью можно озвучивать тексты, добавлять голосовые ответы в приложения, расшифровывать звонки и преобразовывать другие аудиозаписи в текст. Для синтеза речи, или TTS (Text-to-Speech), используется модель `openai/gpt-4o-mini-tts`. Для распознавания речи, или STT (Speech-to-Text), доступны модели `openai/gpt-4o-mini-transcribe` и `openai/gpt-4o-transcribe`. ## Возможности синтеза речи Модель `openai/gpt-4o-mini-tts` создает аудио на основе переданного текста. Модель поддерживает русский и другие языки, а также позволяет управлять звучанием речи с помощью инструкции: например, задать темп, интонацию, эмоциональную окраску или тон. Для генерации можно выбрать один из голосов: - `alloy`; - `ash`; - `ballad`; - `coral`; - `echo`; - `fable`; - `nova`; - `onyx`; - `sage`; - `shimmer`; - `verse`; - `marin`; - `cedar`. Послушать примеры голосов можно на сайте [OpenAI.fm](https://openai.fm/). Поддерживаются следующие форматы аудио: - `mp3` — используется по умолчанию; - `opus` — подходит для потоковой передачи и голосовой связи; - `aac` — формат сжатия, который используется, например, на мобильных устройствах; - `flac` — формат сжатия без потери качества; - `wav` — несжатое аудио; - `pcm` — необработанные аудиоданные без заголовка файла. Форматы `wav` и `pcm` подходят для сценариев, в которых важна минимальная задержка. AI Gateway также поддерживает потоковую передачу: воспроизведение можно начать до завершения генерации всего аудио. ## Возможности транскрибации Модели `openai/gpt-4o-mini-transcribe` и `openai/gpt-4o-transcribe` преобразуют речь из аудиофайла в текст. Язык записи можно определить автоматически или указать в запросе явно. Для транскрибации можно использовать файлы следующих форматов: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav` и `webm`. Результат можно получить в формате `json` или обычного текста. В запросе также можно передать параметр `prompt` с дополнительным контекстом. Он помогает модели правильно распознавать: - имена и фамилии; - названия продуктов и компаний; - аббревиатуры; - профессиональные термины; - слова, написание которых сложно определить только по произношению. Если запись разделена на несколько фрагментов, в `prompt` можно передавать текст предыдущего фрагмента. Это помогает модели сохранять контекст между запросами. ## Как считаются токены В аудиомоделях учитываются текстовые токены и аудиотокены. Текстовые токены зависят от объема текста, а аудиотокены — от продолжительности аудио. При синтезе речи (TTS-модели): - `input_tokens` — текстовые токены переданного текста; - `output_tokens` — аудиотокены созданной записи. Одна секунда аудио считается за один аудиотокен. Например, если модель создала аудио продолжительностью четыре секунды, будет учтено четыре выходных аудиотокена. Количество входных текстовых токенов зависит от длины исходного текста. При транскрибации (STT-модели): - `input_tokens` — аудиотокены исходной записи: примерно 10 токенов за одну секунду; - `output_tokens` — текстовые токены расшифровки. Например, для записи продолжительностью 10 секунд будет потрачено примерно 100 входных аудиотокенов. Количество выходных текстовых токенов зависит от длины расшифровки. ## Ограничения и особенности - Аудиомодели доступны только в AI Gateway. - Потоковая генерация и воспроизведение речи поддерживаются только для TTS. - Транскрибация звука с микрофона в реальном времени не поддерживается. - Для транскрибации доступны форматы ответа `json` и `plain text`. ## Подключение Для работы с аудиомоделями нужен [API-ключ AI Gateway](https://timeweb.cloud/docs/ai-gateway/manage#sozdanie-api-klucha). Создать его можно в разделе «ИИ-сервисы» во вкладке «AI Gateway» → «API-ключи». В примерах используется переменная окружения `TIMEWEB_AI_TOKEN`, чтобы не указывать ключ непосредственно в коде. В Linux и macOS ее можно задать командой: ```bash export TIMEWEB_AI_TOKEN="ваш_API-ключ" ``` Установите библиотеку OpenAI: ```bash pip install openai ``` Создайте клиент и укажите базовый URL AI Gateway: ```py import os from openai import OpenAI client = OpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) ``` ## Синтез речи Для синтеза речи используется метод `audio.speech.create()`. ### Создание аудиофайла В следующем примере модель озвучивает текст и сохраняет результат в файл `speech.mp3`: ```py import os from pathlib import Path from openai import OpenAI client = OpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) speech_file = Path("speech.mp3") with client.audio.speech.with_streaming_response.create( model="openai/gpt-4o-mini-tts", voice="shimmer", input="Привет! Это проверка синтеза речи.", instructions="Говори спокойно и доброжелательно.", response_format="mp3", ) as response: response.stream_to_file(speech_file) ``` Параметры: - `model` — модель для синтеза речи; - `voice` — голос, которым будет озвучен текст; - `input` — текст для озвучивания; - `instructions` — инструкция, определяющая манеру речи; - `response_format` — формат созданного аудио. ### Потоковое воспроизведение Чтобы начать воспроизведение до завершения генерации, используйте асинхронный клиент и `LocalAudioPlayer`. Для работы `LocalAudioPlayer` установите библиотеки `numpy` и `sounddevice`: ```bash pip install numpy sounddevice ``` Пример потокового воспроизведения: ```py import asyncio import os from openai import AsyncOpenAI from openai.helpers import LocalAudioPlayer client = AsyncOpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) async def main() -> None: async with client.audio.speech.with_streaming_response.create( model="openai/gpt-4o-mini-tts", voice="shimmer", input="Привет! Это проверка потокового синтеза речи.", response_format="pcm", ) as response: await LocalAudioPlayer().play(response) if __name__ == "__main__": asyncio.run(main()) ``` В примере используется формат `pcm`, поэтому аудио можно воспроизводить по мере получения данных от модели. ## Транскрибация аудио Для преобразования речи в текст используется метод `audio.transcriptions.create()`. ### Транскрибация из файла В следующем примере модель расшифровывает русскую речь из файла `audio.mp3`: ```py import os from openai import OpenAI client = OpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) with open("audio.mp3", "rb") as audio_file: transcription = client.audio.transcriptions.create( model="openai/gpt-4o-mini-transcribe", file=audio_file, language="ru", response_format="json", ) print(transcription.text) ``` Параметры: - `model` — модель для транскрибации; - `file` — аудиофайл, который нужно преобразовать в текст; - `language` — язык аудио. Если параметр не указан, модель определит язык автоматически; - `response_format` — формат ответа: `json` или `text`. ### Передача контекста С помощью параметра `prompt` можно передать модели термины, дополнительный контекст и требования к результату. Также, можно попросить ее удалить слова-паразиты: ```py import os from openai import OpenAI client = OpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) with open("meeting.mp3", "rb") as audio_file: transcription = client.audio.transcriptions.create( model="openai/gpt-4o-transcribe", file=audio_file, language="ru", response_format="json", prompt=( "Запись посвящена Kubernetes и облачной инфраструктуре. " "В разговоре упоминаются Timeweb Cloud, kubectl и Ingress. " "Удали из расшифровки слова-паразиты и междометия. " "Сохрани смысл и не перефразируй остальную речь." ), ) print(transcription.text) ``` В примере `prompt` помогает модели распознать технические термины и задает требования к готовому тексту. Параметр не заменяет содержимое аудио, а дополняет его контекстом и инструкциями. ### Транскрибация звука с микрофона AI Gateway не поддерживает транскрибацию в реальном времени. Для приближенного к реальному времени результата можно записывать звук короткими фрагментами и отправлять каждый фрагмент в API отдельно. Установите дополнительные библиотеки: ```shell pip install numpy sounddevice ``` Пример ниже записывает звук фрагментами по три секунды. Между соседними фрагментами добавляется небольшое перекрытие, чтобы модель не потеряла слова на границе записи: ```py import io import os import queue import threading import time import wave from dataclasses import dataclass import numpy as np import sounddevice as sd from openai import OpenAI MODEL = "openai/gpt-4o-mini-transcribe" SAMPLE_RATE = 16_000 CHANNELS = 1 SAMPLE_WIDTH_BYTES = 2 CHUNK_SECONDS = 3.0 OVERLAP_SECONDS = 0.4 FRAMES_PER_BLOCK = 1_600 client = OpenAI( api_key=os.environ["TIMEWEB_AI_TOKEN"], base_url="https://api.timeweb.ai/v1", ) @dataclass class AudioChunk: index: int pcm_data: bytes audio_queue: queue.Queue[AudioChunk | None] = queue.Queue(maxsize=10) stop_event = threading.Event() def pcm_to_wav_bytes(pcm_data: bytes) -> io.BytesIO: wav_buffer = io.BytesIO() with wave.open(wav_buffer, "wb") as wav_file: wav_file.setnchannels(CHANNELS) wav_file.setsampwidth(SAMPLE_WIDTH_BYTES) wav_file.setframerate(SAMPLE_RATE) wav_file.writeframes(pcm_data) wav_buffer.seek(0) wav_buffer.name = "chunk.wav" return wav_buffer def transcription_worker() -> None: while True: chunk = audio_queue.get() if chunk is None: audio_queue.task_done() break try: wav_file = pcm_to_wav_bytes(chunk.pcm_data) started_at = time.perf_counter() transcription = client.audio.transcriptions.create( model=MODEL, file=wav_file, language="ru", response_format="json", ) elapsed = time.perf_counter() - started_at text = getattr(transcription, "text", "").strip() if text: print( f"\n[{chunk.index:04d}] " f"({elapsed:.2f} сек.) {text}", flush=True, ) else: print( f"\n[{chunk.index:04d}] " f"({elapsed:.2f} сек.) [тишина]", flush=True, ) except Exception as exc: print( f"\nОшибка транскрибации фрагмента " f"{chunk.index}: {exc}", flush=True, ) finally: audio_queue.task_done() def record_microphone() -> None: chunk_samples = int(SAMPLE_RATE * CHUNK_SECONDS) overlap_samples = int(SAMPLE_RATE * OVERLAP_SECONDS) accumulated = np.empty(0, dtype=np.int16) previous_tail = np.empty(0, dtype=np.int16) chunk_index = 1 print("Говорите. Для остановки нажмите Ctrl+C.") with sd.InputStream( samplerate=SAMPLE_RATE, channels=CHANNELS, dtype="int16", blocksize=FRAMES_PER_BLOCK, ) as stream: while not stop_event.is_set(): block, overflowed = stream.read(FRAMES_PER_BLOCK) if overflowed: print("\nПредупреждение: переполнение аудиобуфера.") accumulated = np.concatenate((accumulated, block[:, 0])) while len(accumulated) >= chunk_samples: current_samples = accumulated[:chunk_samples] accumulated = accumulated[chunk_samples:] if len(previous_tail) > 0: samples_to_send = np.concatenate( (previous_tail, current_samples) ) else: samples_to_send = current_samples if overlap_samples > 0: previous_tail = current_samples[-overlap_samples:].copy() else: previous_tail = np.empty(0, dtype=np.int16) audio_chunk = AudioChunk( index=chunk_index, pcm_data=samples_to_send.astype( "= SAMPLE_RATE // 2: if len(previous_tail) > 0: accumulated = np.concatenate( (previous_tail, accumulated) ) audio_queue.put( AudioChunk( index=chunk_index, pcm_data=accumulated.astype( " None: worker = threading.Thread( target=transcription_worker, daemon=True, ) worker.start() try: record_microphone() except KeyboardInterrupt: print("\nОстанавливаю запись...") stop_event.set() finally: audio_queue.put(None) audio_queue.join() worker.join(timeout=5) print("Готово.") if __name__ == "__main__": main() ``` Значения `CHUNK_SECONDS` и `OVERLAP_SECONDS` можно изменить. Более короткие фрагменты уменьшают задержку, но увеличивают количество запросов. Из-за перекрытия в результате могут повторяться отдельные слова — при необходимости удаляйте такие повторы при дальнейшей обработке текста. # Резервные модели Source: https://timeweb.cloud/docs/ai-gateway/fallback Резервные модели позволяют автоматически переключить запрос на другую языковую модель, если основная вернула ошибку или не ответила вовремя. Для каждого API-ключа [AI Gateway](https://timeweb.cloud/docs/ai-gateway) можно выбрать до двух резервных моделей и задать порядок их вызова. Основная модель определяется в каждом запросе — это модель, указанная в поле model. В настройках ключа выбираются только резервные модели. Одна и та же цепочка применяется ко всем запросам с этим ключом. ## Настройка резервных моделей Чтобы добавить резервные модели: 1. Перейдите в раздел «ИИ-сервисы» → «AI Gateway» → «API-ключи» и кликните на нужный ключ. 2. Перейдите на вкладку «Управление». 3. В строке «Резервные модели» нажмите «Выбрать». Если модели уже настроены, нажмите «Изменить». 4. В поле «Модель 2» выберите первую резервную модель. 5. При необходимости выберите вторую резервную модель в поле «Модель 3». Это поле станет доступно после выбора «Модели 2». 6. Нажмите «Сохранить». ![Выбор резервных моделей](https://content.timeweb.com/assets/6711283a-80d1-4cd6-b25f-05ffcb85db76.png?width=2702&height=1806) После сохранения в строке «Резервные модели» отобразится выбранная цепочка. В качестве резервных доступны только текстовые модели. Локальные модели выбрать нельзя. Одну и ту же модель нельзя добавить в цепочку дважды. ## Изменение и отключение Чтобы изменить цепочку, нажмите «Изменить» в строке «Резервные модели», выберите другие модели и сохраните изменения. Чтобы удалить модель из цепочки, нажмите на крестик в ее поле. Если удалить «Модель 2», выбранная «Модель 3» переместится на ее место. Для отключения автоматического переключения очистите оба поля и нажмите «Сохранить». В строке «Резервные модели» отобразится «Не выбраны». ## Как работает переключение AI Gateway обрабатывает запрос в следующем порядке: 1. Отправляет запрос основной модели из поля model. 2. Если основная модель не ответила успешно, отправляет запрос первой резервной модели — «Модели 2». 3. Если первая резервная модель также вернула ошибку, отправляет запрос «Модели 3», если она выбрана. 4. Если ни одна модель не ответила успешно, возвращает ошибку. Если резервная модель совпадает с основной моделью запроса, AI Gateway пропускает ее и переходит к следующей. Повторно вызывать основную модель в резервной цепочке он не будет. Каждая резервная модель вызывается не более одного раза за запрос. ### Когда запрос передается резервной модели Переключение срабатывает, если: - провайдер модели недоступен или вернул ошибку `5xx`; - истекло время ожидания ответа; - провайдер ограничил частоту запросов — ошибка `429`; - запрос превышает объем контекста модели; - провайдер отклонил запрос как некорректный — ошибка `400`. ### Когда переключение не срабатывает - Модель вернула успешный ответ, в том числе отказ отвечать. Например, сообщение «Я не могу обсуждать эту тему» не считается ошибкой и не запускает резервную цепочку. - Исчерпан лимит ключа на запрошенную модель. Лимит проверяется до обращения к модели. API вернет ошибку `422`, даже если лимит резервной модели еще не исчерпан. Чтобы продолжить работу, увеличьте лимит на запрашиваемую модель или укажите другую модель в запросе. - Потоковый ответ уже начал поступать. После первого фрагмента ответа переключение на другую модель не выполняется. ## Поддерживаемые запросы Резервные модели работают для запросов к `/v1/chat/completions` и `/v1/responses`. При потоковой передаче переключение возможно только до получения первого фрагмента ответа. Резервные модели не поддерживаются для: - эмбеддингов; - генерации изображений; - генерации речи и транскрибации; - запросов в формате Anthropic к `/v1/messages`; - устаревшего эндпоинта `/completions`. ## Тарификация Запрос оплачивается по стоимости модели, которая сформировала ответ. Неудачная попытка основной модели не оплачивается и не расходует ее лимит. Расход токенов учитывается в лимите ответившей модели и в общем лимите ключа. ## Определение модели, которая ответила Поле `model` в ответе API содержит имя модели, которая фактически обработала запрос. Дополнительно проверьте HTTP-заголовок `x-timeweb-attempted-fallbacks`: значение больше нуля означает, что выполнялось переключение на резервную модель. Это признак переключения, а не количество пройденных шагов цепочки. Например, при запросе к `gemini/gemini-3.1-flash-lite` ответ может сформировать резервная Claude 4.5 Haiku. Сокращенный пример ответа: ```js HTTP/1.1 200 OK x-timeweb-attempted-fallbacks: 1 { "model": "claude-haiku-4-5-20251001", "choices": [ { "message": { "content": "Да" } } ] } ``` # Логи запросов Source: https://timeweb.cloud/docs/ai-gateway/logs Логи запросов — это журнал обращений к моделям по ключам AI Gateway. Для каждого запроса логируются такие данные, как модель, расход токенов, стоимость, время выполнения и результат. С помощью логов можно просмотреть статистику запросов, определить, на какие запросы расходовались ресурсы, как долго шла обработка, почему запрос завершился ошибкой, и так далее. ## Ограничения - Записи в логе хранятся 90 дней, после чего автоматически удаляются. - Запрос появляется в панели через несколько секунд после ответа модели, а не мгновенно. - Запросы, выполненные до 9 октября 2026 года, отсутствуют в логах. - В логах доступны только запросы по ключам AI Gateway. Запросы агентов и баз знаний в логи не попадают. ## Как формируется лог Лог фиксирует состояние запроса на момент его выполнения. Запись в логе формируется в несколько этапов: 1. Приложение отправляет запрос в AI Gateway по своему ключу. 2. AI Gateway передает запрос провайдеру, при необходимости переключается на резервную модель и параллельно фиксирует ход выполнения. 3. Сервис логов дополняет запись ценами и именем ключа. После этого строка появляется во вкладке «Логи». ### Состав данных Из запроса в лог попадают: - модель, указанная в запросе, и модель, которая фактически ответила; - ключ; - время запроса; - количество входящих и исходящих токенов, а также доля токенов, взятых из кэша; - IP-адрес и user-agent, с которых пришел запрос (доступны в RAW JSON в детализации). При сохранении запись дополняется тремя значениями: - стоимость, рассчитанная по ценам на момент запроса с учетом индивидуальных скидок; - имя ключа на момент запроса; - цепочка резервных моделей, с которой запрос поступил в AI Gateway. > [!NOTE] > Тексты промпта и ответа модели не сохраняются в логе, в том числе в RAW JSON в детализации. ## Просмотр логов Чтобы просмотреть логи: 1. Перейдите в раздел «ИИ-сервисы» → «AI Gateway». 2. Откройте вкладку [«Логи»](https://timeweb.cloud/my/cloud-ai/gateway/logs). 3. (Опционально) Выберите конкретный ключ и интересующий вас период. 4. (Опционально) Отфильтруйте вывод по имени провайдера и причине завершения запроса. Удаленные ключи будут доступны в списке, если за последние 90 дней по ним выполнялись запросы. ### Чтение графика На графике можно вывести данные по запросам, токенам и стоимости. Для периодов до 48 часов данные группируются по часам, для более длинных — по суткам. Три самые часто используемые модели выделяются отдельно, остальные объединяются в серию «Остальное». ![Ии Сервисы 2026 10 20 10 55](https://content.timeweb.com/assets/3a76a70e-c584-4e12-b0de-72ae02177f46.png?width=1099&height=564) ### Чтение таблицы В таблице для каждого запроса указаны ключ и модель, дата в часовом поясе браузера, цена, токены, кэш, скорость, задержка, TTFT (время до первого токена, отображается только у стриминговых запросов) и результат. По клику на строку таблицы откроется [детализация запроса](https://timeweb.cloud/docs/ai-agents/api-usage/logs#detalizaciya-zaprosa). ![Ии Сервисы 2026 10 20 13 54](https://content.timeweb.com/assets/7d53cc4f-6a56-4541-9f31-abf8fbe55136.png?width=1105&height=605) ## Поиск и фильтрация Чтобы найти конкретный лог, можно воспользоваться поиском и фильтрами. Поиск работает по трем полям: имени ключа, названию модели и ID запроса. ID необходимо указывать в поле поиска целиком. Дополнительно доступны фильтры по провайдеру и по причине завершения запроса. Если нужный запрос не удается найти, проверьте, какой ключ и период выбраны над графиком и какие фильтры применены, а также обратите внимание [на ограничения логов](https://timeweb.cloud/docs/ai-agents/api-usage/logs#ogranicheniya). ## Анализ логов ### Детализация запроса Кликните по строке в таблице логов, чтобы открыть детализацию запроса. В ней можно посмотреть: - **Модель запроса** — модель, указанная приложением в поле `model`. Если запрос обработан без переключений, совпадает с моделью ответа. - **Модель ответа** — модель, которая фактически ответила. Отличается от модели запроса, если [сработал фолбэк](https://timeweb.cloud/docs/ai-agents/api-usage/logs#analiz-raboty-rezervnyh-modelej). Провайдер в логе определяется по модели ответа. - **Ключ AI Gateway** — если ключ еще существует, по клику на имя можно [перейти к управлению им](https://timeweb.cloud/docs/ai-gateway/manage#upravlenie-api-kluchami). - **ID запроса** — уникальный идентификатор запроса, который можно скопировать в один клик. По ID запрос ищется через поиск. Его же можно передать в тикете при обращении в поддержку. - **Стриминг** — признак того, что ответ передавался частями по мере генерации, а не целиком после завершения. - **Задержка провайдера** — длительность запроса целиком: от момента поступления в AI Gateway до последнего токена ответа, включая все попытки. - **Скорость** — количество токенов ответа в секунду, рассчитанное по времени генерации. Если ответ пустой или сгенерирован быстрее чем за 0,1 секунды, указывается прочерк. - [**Стоимость / токены**](https://timeweb.cloud/docs/ai-agents/api-usage/logs#proverka-stoimosti) — входящие и исходящие токены, кэш и итог в рублях и токенах. - **Фолбэки** — блок отображается, если был [переход на резервную модель](https://timeweb.cloud/docs/ai-agents/api-usage/logs#analiz-raboty-rezervnyh-modelej). В логе видна вся цепочка и точка, на которой она остановилась. - **Ответы провайдеров** — время обработки, а при неуспешном обращении — [коды и причины отказа](https://timeweb.cloud/docs/ai-agents/api-usage/logs#diagnostika-oshibok) по каждой попытке. - **RAW JSON** — вся строка лога целиком, включая поля, которых нет в интерфейсе. Ее можно скачать файлом и приложить к обращению в поддержку. ![Ии Сервисы 2026 10 20 13 56](https://content.timeweb.com/assets/92d546bc-5fb2-48b4-8c4f-0128e8f82536.png?width=1713&height=862) ### Проверка стоимости Стоимость показана для входящих и исходящих токенов, кэша и итога, в рублях и токенах. Кэш отображается в виде скидки, то есть суммы, сэкономленной на повторном контексте. Сумма меньше одной тысячной рубля отображается как «< 0,001 ₽». Прочерк означает, что цену на момент запроса получить не удалось: модель неизвестна биллингу или биллинг не ответил. У запросов, завершившихся отказом, токенов нет, поэтому стоимость нулевая. > [!NOTE] > Сумма в логах может отличаться от фактических списаний. Логи в первую очередь помогают определить, какие именно запросы дали расход. ### Анализ работы резервных моделей Если основная модель не ответила, AI Gateway последовательно пробует [резервные модели](https://timeweb.cloud/docs/ai-gateway/fallback) из настроек ключа. В этом случае модель ответа в детализации будет отличаться от модели запроса. В детализации для такого запроса доступны: - Блок «Фолбэки» с основной моделью и резервами по порядку, где зеленая точка отмечает модель, давшую ответ. - Коды и причины отказа по каждой попытке в блоке «Ответы провайдеров», например, таймаутом, превышением лимита запросов или ошибкой провайдера. ![U P9 Ffuc Ugx 2026 10 20 13 57](https://content.timeweb.com/assets/96b3cf17-decb-4155-b5b0-414591cd65e1.png?width=614&height=502) Повторные попытки к одной и той же модели не выводятся — в «Ответах провайдеров» отображается одна строка на каждую модель цепочки, до которой дошел запрос. Стоимость такого запроса рассчитывается по модели, которая ответила. ### Диагностика ошибок Итог каждого запроса отображается в таблице в колонке «Результат», а в детализации — в пункте «Причина завершения». Успешные завершения помечаются зеленым и бывают трех видов: - «Успешный ответ», когда модель закончила ответ сама; - «Лимит длины ответа», когда достигнут `max_tokens` и ответ обрезан; - «Вызов инструмента», когда модель запросила вызов функции. Отказы помечаются красным, а в детализации выводится код ошибки. Статус «В обработке» ошибкой не является. Так помечается генерация видео, которая выполняется у провайдера в течение нескольких минут. Итог такой строки в лог не дописывается: статус и пустая стоимость сохраняются как есть, а списание за видео проходит в обычном порядке. Код и имя ошибки отображаются в блоке «Ответы провайдеров» в детализации. Полный текст ошибки можно найти в RAW JSON, в поле `error_message`. | **Код** | **Значение** | **Причина и рекомендуемые действия** | | --- | --- | --- | | 400 | Некорректный запрос | Провайдер не принял запрос: неподдерживаемый параметр, слишком длинный контекст, неверный формат сообщений или отказ фильтра безопасности. Необходимо исправить запрос с учетом текста ошибки. | | 402 | Недостаточно средств | AI Gateway не смог зарезервировать оплату: на балансе недостаточно средств или аккаунт заблокирован. Необходимо пополнить баланс, а при положительном балансе проверить, не заблокирован ли аккаунт. | | 404 | Модель недоступна | Модель с таким названием неизвестна. Название необходимо сверить с каталогом моделей. | | 408, 504 | Таймаут ответа | Модель не ответила вовремя. Запрос можно повторить, для длинных ответов включить стриминг, а при частых таймаутах настроить резервные модели. | | 410 | Модель недоступна | Модель снята с поддержки. Необходимо перейти на другую модель. | | 422 | Превышен лимит ключа | Исчерпан лимит расхода, заданный на ключ. Лимит можно поднять или снять в настройках ключа. | | 429 | Превышен лимит запросов | Провайдер ограничил частоту запросов или не располагает свободной мощностью. Можно повторить запрос позже, снизить частоту или настроить резервные модели. | | 5xx | Ошибка провайдера | Сбой на стороне провайдера или в канале связи с ним. Можно повторить запрос, резервные модели переключат его автоматически. | | Другой код | Ошибка | Любой другой отказ. Причину необходимо искать в тексте ошибки в детализации. | ## Выгрузка логов Вы можете выгрузить логи в формате CSV. В один файл попадают 10 000 последних запросов. Если запросов больше, измените период, ключ или фильтры, чтобы сузить выборку и выгрузить данные частями. Чтобы скачать логи в CSV: 1. Перейдите в раздел «ИИ-сервисы» → «AI Gateway». 2. Откройте вкладку [«Логи»](https://timeweb.cloud/my/cloud-ai/gateway/logs). 3. (Опционально) Выберите ключ и период. 4. (Опционально) Отфильтруйте вывод по имени провайдера и причине завершения запроса. 5. Нажмите на иконку скачивания справа над графиком. ![Ии Сервисы 2026 10 20 13 59](https://content.timeweb.com/assets/c4e70ae7-d121-4026-aeb2-be1f63c4c517.png?width=1110&height=570)