Справочник по API (Endpoints)

В этом разделе представлено подробное описание всех доступных конечных точек API, их параметров и возвращаемых данных.

Адреса серверов (Base URL)

Все запросы следует отправлять на один из наших базовых URL. Полный список доступных серверов (основной, резервный и сервер в Санкт-Петербурге) вы можете найти на странице Сервера HydraAI API.

Авторизация

Авторизация

Для доступа к большинству конечных точек требуется авторизация. Передавайте ваш API ключ в заголовке Authorization по схеме Bearer.

Authorization: Bearer sk-hydra-ai-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Если вы используете какие-то библиотеки или программы, в большинстве случаев нужно указать только сам API-ключ sk-hydra-ai-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. Для получения информации, как задается API-ключ в библиотеке или программе, которые вы используете, обратитесь к их документации.

---

Пользователи (Users)

Эндпоинты для управления информацией о пользователе и его балансе.

---

GET /users/profile

Возвращает информацию о профиле пользователя, включая текущий баланс, статистику использования и лимиты.

• Авторизация: Требуется

Параметры запроса

Отсутствуют.

Структура ответа (200 OK)

Поле	Тип	Описание
id	string	Уникальный ID вашего профиля.
balance	number	Текущий баланс в рублях.
user_type	string	Тип вашего аккаунта.
last_used_at	string	Дата и время последнего использования ключа (UTC).
total_balance_added	number	Общая сумма всех пополнений.
free_requests	integer	Количество оставшихся бесплатных запросов.
request_count_last_hour	number	Количество запросов за последний час.
total_cost_request_last_hour	number	Суммарная стоимость запросов за последний час.
average_rpm	number	Среднее количество запросов в минуту (RPM) за последний час.
requests_per_minute	number	Лимит запросов в минуту (RPM).

Пример ответа

{
  "id": "00000000-0000-0000-0000-000000000000",
  "user_type": "Pack",
  "last_used_at": "2025-08-11T16:56:33.906409Z",
  "balance": 10877.975,
  "total_balance_added": 49900,
  "free_requests": 800,
  "request_count_last_hour": 0,
  "total_cost_request_last_hour": 0,
  "average_rpm": 0,
  "requests_per_minute": 500
}

---

POST /users/redeem

Активирует код пополнения для зачисления средств на баланс API ключа.

• Авторизация: Требуется

Важно

Попытки подбора кода пополнения приведут к автоматической и перманентной блокировке вашего аккаунта без возможности восстановления.

Параметры запроса (Тело)

Поле	Тип	Обязательный	Описание
code	string	Да	Уникальный код пополнения, полученный в магазине.

Структура ответа (200 OK)

Поле	Тип	Описание
id	string	Уникальный ID вашего профиля.
balance	number	Новый баланс в рублях после пополнения.
add_balance	number	Сумма, на которую был пополнен баланс.
add_free_requests	integer	Количество добавленных бесплатных запросов (если применимо).
...	...	Остальные поля аналогичны ответу /v1/users/profile.

Пример ответа

{
  "id": "00000000-0000-0000-0000-000000000000",
  "user_type": "Pack",
  "last_used_at": "2025-08-11T20:37:38.748390Z",
  "balance": 10977.975,
  "total_balance_added": 50000,
  "free_requests": 900,
  "add_balance": 100,
  "add_free_requests": 100
}

---

GET /users/refill_logs

Возвращает пагинированный список истории пополнений баланса для аутентифицированного пользователя.

• Авторизация: Требуется

Параметры запроса (Query)

Поле	Тип	Обязательный	Описание
page	integer	Нет	Номер страницы для пагинации. По умолчанию 1.
page_size	integer	Нет	Количество записей на странице. По умолчанию 20, максимум 100.

Структура ответа (200 OK)

Поле	Тип	Описание
total_count	integer	Общее количество записей о пополнениях.
total_pages	integer	Общее количество доступных страниц.
page	integer	Номер текущей возвращенной страницы.
page_size	integer	Количество записей, запрошенное на одной странице.
items	array[object]	Массив объектов, содержащий историю пополнений.

Структура объекта в массиве items

Поле	Тип	Описание
created_at	string	Дата и время пополнения в формате UTC.
refill_code_redeemed	string	Код, который был активирован.
balance_added	number	Сумма, зачисленная на баланс в рублях.
free_requests_added	integer	Количество бесплатных запросов, добавленных при пополнении.

Пример ответа

{
  "total_count": 2,
  "total_pages": 1,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "created_at": "2025-07-10T14:25:00Z",
      "refill_code_redeemed": "hydra-ai-ZZZZZZZZZZZZ-refill-code",
      "balance_added": "1000.00",
      "free_requests_added": 1000
    },
    {
      "created_at": "2025-06-27T10:30:00Z",
      "refill_code_redeemed": "hydra-ai-YYYYYYYYYYYY-refill-code",
      "balance_added": "500.00",
      "free_requests_added": 500
    }
  ]
}

---

GET /users/stats

Возвращает агрегированную суточную статистику по использованию API для аутентифицированного пользователя за указанный период.

• Авторизация: Требуется

Примечание

Данные агрегируются за сутки по времени UTC. Период включает последние 30 календарных дней. Разбивка по моделям доступна внутри каждого дня; для исторических записей она может отсутствовать или быть неполной, если такие данные не собирались в момент запроса.

Параметры запроса (Query)

Поле	Тип	Обязательный	Описание
start_date	string	Нет	Дата начала периода в формате YYYY-MM-DD. Если не указана, по умолчанию устанавливается дата 30 дней назад.
end_date	string	Нет	Дата окончания периода в формате YYYY-MM-DD. Если не указана, по умолчанию используется текущая дата.

Структура ответа (200 OK)

Поле	Тип	Описание
period_start_date	string	Начальная дата периода, за который предоставлена статистика.
period_end_date	string	Конечная дата периода, за который предоставлена статистика.
total_requests	integer	Общее количество запросов за весь указанный период.
total_prompt_tokens	integer	Общая сумма prompt_tokens за весь период.
total_cache_read_tokens	integer	Общая сумма cache_read_tokens за весь период.
total_completion_tokens	integer	Общая сумма completion_tokens за весь период.
total_cost	string	Общая стоимость всех запросов за период в рублях. Денежные значения возвращаются в JSON строкой.
total_free_requests	integer	Общее количество бесплатных запросов, использованных за период.
daily_stats	array[object]	Массив объектов, содержащий подробную статистику по каждому дню.

Структура объекта в массиве daily_stats

Поле	Тип	Описание
stat_date	string	Дата, за которую предоставлена статистика (YYYY-MM-DD).
request_count	integer	Количество запросов за этот день.
prompt_tokens	integer	Сумма prompt_tokens за этот день.
cache_read_tokens	integer	Сумма токенов, прочитанных из prompt cache, за этот день.
completion_tokens	integer	Сумма completion_tokens за этот день.
cost_request	string	Стоимость запросов за этот день в рублях. Денежное значение возвращается в JSON строкой.
free_requests	integer	Количество бесплатных запросов, использованных за этот день.
model_stats	array[object]	Статистика по моделям за этот день. Может быть пустым.

Структура объекта в массиве model_stats

Поле	Тип	Описание
model_name	string	Идентификатор модели.
request_count	integer	Количество запросов к модели за этот день.
prompt_tokens	integer	Сумма входных токенов модели за этот день.
cache_read_tokens	integer	Сумма токенов, прочитанных из prompt cache.
completion_tokens	integer	Сумма выходных токенов модели за этот день.
cost_request	string	Стоимость запросов к модели в рублях, возвращаемая в JSON строкой.
free_requests	integer	Количество бесплатных запросов к модели за этот день.

Пример ответа

{
  "period_start_date": "2025-10-01",
  "period_end_date": "2025-10-02",
  "total_requests": 1150,
  "total_prompt_tokens": 75000,
  "total_cache_read_tokens": 12000,
  "total_completion_tokens": 220000,
  "total_cost": "145.755",
  "total_free_requests": 15,
  "daily_stats": [
    {
      "stat_date": "2025-10-02",
      "request_count": 150,
      "prompt_tokens": 15000,
      "cache_read_tokens": 3000,
      "completion_tokens": 70000,
      "cost_request": "45.125",
      "free_requests": 5,
      "model_stats": [
        {
          "model_name": "gpt-4o-mini",
          "request_count": 120,
          "prompt_tokens": 12000,
          "cache_read_tokens": 3000,
          "completion_tokens": 60000,
          "cost_request": "40.125",
          "free_requests": 4
        },
        {
          "model_name": "gpt-4o",
          "request_count": 30,
          "prompt_tokens": 3000,
          "cache_read_tokens": 0,
          "completion_tokens": 10000,
          "cost_request": "5.000",
          "free_requests": 1
        }
      ]
    },
    {
      "stat_date": "2025-10-01",
      "request_count": 1000,
      "prompt_tokens": 60000,
      "cache_read_tokens": 9000,
      "completion_tokens": 150000,
      "cost_request": "100.630",
      "free_requests": 10,
      "model_stats": []
    }
  ]
}

---

GET /users/request_logs

Возвращает пагинированный список истории запросов к AI-моделям для аутентифицированного пользователя.

• Авторизация: Требуется

Важно

В список попадают только те запросы, которые были обработаны и отправлены непосредственно AI-модели (как успешные, так и неуспешные). Запросы, отклоненные из-за ошибок валидации, превышения лимитов или нехватки баланса, в этом логе не отображаются. Максимальный период, за который можно запросить статистику, ограничен последними 72 часами.

Параметры запроса (Query)

Поле	Тип	Обязательный	Описание
page	integer	Нет	Номер страницы для пагинации. По умолчанию 1.

Структура ответа (200 OK)

Поле	Тип	Описание
total_count	integer	Общее количество логов запросов.
total_pages	integer	Общее количество доступных страниц.
page	integer	Номер текущей возвращенной страницы.
page_size	integer	Количество записей на странице (зафиксировано: 300).
items	array[object]	Массив объектов, содержащий логи запросов.

Структура объекта в массиве items

Поле	Тип	Описание
created_at	string	Дата и время запроса в формате UTC.
success	boolean	true, если запрос был успешно обработан, иначе false.
response_code	int	HTTP код ответа. 200 при успешном ответе, остальные коды сообщают о типе ошибки.
request_id	string	Уникальный ID запроса.
details	string | null	Описание ошибки, если запрос завершился неудачей. null, если запрос успешен.
user_ip	string	IP-адрес, с которого был отправлен запрос.
model_name	string	ID использованной модели (например, gpt-4.1, glm-4.5).
prompt_tokens	integer	Количество токенов, отправленных в модель.
cache_read_tokens	integer | null	Количество токенов, прочитанных из prompt cache.
completion_tokens	integer	Количество токенов, полученных от модели.
total_time	number	Общее время обработки запроса в секундах.
cost_request	number	Стоимость запроса в рублях.
is_free_request	boolean	true, если для оплаты был использован бесплатный запрос, иначе false.

Пример ответа

{
  "total_count": 2,
  "total_pages": 1,
  "page": 1,
  "page_size": 300,
  "items": [
    {
      "created_at": "2025-08-11T16:56:32.905381Z",
      "success": true,
      "request_id": "chat-id-4c3265de-5dd8-48cd-8741-0ccf4ce19098",
      "details": null,
      "user_ip": "127.0.0.1",
      "model_name": "gpt-4.1",
      "prompt_tokens": 29,
      "cache_read_tokens": 12,
      "completion_tokens": 263,
      "total_time": 23.392,
      "cost_request": 0.081,
      "is_free_request": false
    },
    {
      "created_at": "2025-08-11T16:51:54.254152Z",
      "success": true,
      "request_id": "chat-id-5adf07e9-aa41-4642-af84-230301f0454e",
      "details": null,
      "user_ip": "127.0.0.1",
      "model_name": "glm-4.5",
      "prompt_tokens": 26,
      "completion_tokens": 16,
      "total_time": 8.783,
      "cost_request": 0.001,
      "is_free_request": false
    }
  ]
}

---

PUT /users/regenerate_api_key

Создает и возвращает новый API-ключ, который заменяет текущий. Старый ключ после этого деактивируется.

• Авторизация: Требуется

Критически важно

• Не генерируйте ключ без необходимости. После выполнения этого запроса ваш старый API-ключ будет деактивирован. Вам потребуется обновить новый ключ во всех ваших приложениях и скриптах.
• Сохраните новый ключ! Новый API-ключ показывается только один раз в ответе на этот запрос. Если вы не сохраните его, вы потеряете программный доступ к API и восстановить его можно будет только через поддержку в течение 24 часов.

Возможна задержка

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

Параметры запроса (Query)

Нет.

Структура ответа (200 OK)

Поле	Тип	Описание
new_api_key	string	Новый сгенерированный API-ключ.

Структура объекта detail

Поле	Тип	Описание
error	string	Код ошибки (например, key_generation_failed).
message_ru	string	Описание ошибки на русском языке.
message_en	string	Описание ошибки на английском языке.

Пример ответа

{
  "new_api_key": "sk-hydra-ai-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

---

Модели (Models)

Эндпоинты для получения списка моделей и статуса работы моделей.

---

GET /models

Возвращает список всех доступных в API моделей, их характеристики и актуальные цены.

• Авторизация: Не требуется

Параметры запроса (Query)

Поле	Тип	Обязательный	Описание
type	string	Нет	Фильтр по типу модели. Возможные значения: chat, vision, image, embedding, systemone. Например, GET /models?type=systemone.

Структура ответа (200 OK)

Ответ содержит объект со свойством data, которое является массивом объектов моделей.

Структура объекта модели

Поле	Тип	Описание
id	string	Уникальный идентификатор модели, который используется в запросах.
name	string	Человекочитаемое название модели.
description	string	Краткое описание возможностей модели.
type	string	Тип модели (chat, vision, image, embedding, systemone).
endpoints	array of strings | null	Поддерживаемые конечные точки, например ["/systemone"].
context	integer	Максимальный размер контекстного окна в токенах.
max_completion_tokens	integer	Максимальное количество токенов ответа модели; положительное целое число. Это отдельный лимит, не размер контекстного окна context.
supported_parameters	array of strings	Список поддерживаемых дополнительных параметров и возможностей модели, например max_tokens, tools, tool_choice, response_format, structured_outputs. Пустой список [] означает, что дополнительные параметры не поддерживаются.
active	boolean	true, если модель в данный момент активна и доступна для использования.
reasoning	boolean | null	true, если модель поддерживает рассуждения. false или null, если не поддерживает.
reasoning_effort	object (OptionSpec) | null	Настройки уровня рассуждений (если поддерживается). Содержит допустимые значения и значение по умолчанию.
image_quality	object (OptionSpec) | null	Настройки качества изображения (если поддерживается). Содержит допустимые значения и значение по умолчанию.
web_search	boolean | null	true, если модель поддерживает поиск в интернете. false, если не поддерживает. null, если параметр неприменим.
input_modalities	array of strings | null	Список модальностей, которые модель принимает на вход (например, ["text", "image"]).
output_modalities	array of strings | null	Список модальностей, которые модель может генерировать в ответе (например, ["text", "image"]).
supported_file_types	array of strings | null	Список поддерживаемых расширений файлов для загрузки (например, ["jpg", "png", "pdf"]).
max_image_count	integer | null	Максимальное количество изображений, которое можно запросить за один раз (параметр n). Актуально для моделей типа image.
max_file_count	integer | null	Максимальное количество файлов, которые можно передать в одном запросе. Актуально для мультимодальных моделей.
architecture	string | null	Архитектура модели (например, MoE - Mixture of Experts).
quantization	string | null	Тип квантизации, используемый в модели (например, fp16, int8).
delete_at	string | null	Дата отключения модели, отключение производится в 00:00 по UTC в указанную дату (например, 01.05.2026, 22.01.2027).
pricing	object	Объект с информацией о стоимости использования модели. Для токеновой тарификации содержит поля prompt, completion, input_cache_read и overrides; цены указываются за миллион токенов.
new_pricing	object	Объект с информацией о новой стоимости использования модели. Дата применения новой стоимости в 00:00 по UTC указана в поле date_of_use в формате DD.MM.YYYY (например, 22.01.2027). Структура цен аналогична pricing, включая токеновые поля и overrides.
owned_by	string	Владелец или провайдер модели.
rpm_coefficient	integer	Коэффициент RPM. Указывает, сколько слотов RPM (Requests Per Minute) списывается за совершение 1 фактического запроса к данной модели (по умолчанию 1).

Пример новых характеристик модели

Ниже приведён фрагмент объекта модели из массива data (остальные поля опущены):

{
  "id": "example-model",
  "context": 200000,
  "max_completion_tokens": 128000,
  "supported_parameters": [
    "max_tokens",
    "response_format",
    "structured_outputs",
    "tool_choice",
    "tools"
  ]
}

Структура объекта токеновой тарификации

Поля prompt, completion, input_cache_read и input_cache_write задают стоимость соответствующего типа токенов за один миллион токенов. Поле prompt — стоимость обычных входных токенов, completion — стоимость выходных токенов, input_cache_read — стоимость токенов, прочитанных из prompt cache, input_cache_write — стоимость записи токенов в prompt cache.

Поле	Тип	Описание
prompt	number | null	Стоимость входных токенов за миллион токенов.
completion	number | null	Стоимость выходных токенов за миллион токенов.
input_cache_read	number | null	Стоимость токенов, прочитанных из prompt cache, за миллион токенов.
input_cache_write	number | null	Стоимость токенов, записанных в prompt cache, за миллион токенов.
overrides	array[object] | null	Набор ценовых уровней, выбираемых по размеру промпта.

Структура объекта overrides

Поле	Тип	Описание
min_prompt_tokens	integer	Нижняя граница размера промпта в токенах для данного уровня.
prompt	number | null	Стоимость входных токенов за миллион токенов на этом уровне.
completion	number	Стоимость выходных токенов за миллион токенов на этом уровне.
input_cache_read	number | null	Стоимость чтения из prompt cache за миллион токенов на этом уровне.
input_cache_write	number | null	Стоимость записи в prompt cache за миллион токенов на этом уровне.

Уровень выбирается по значению min_prompt_tokens; при совпадении с несколькими уровнями используется последний подходящий уровень.

Примеры других форматов тарификации

Старая токеновая тарификация с раздельной стоимостью входных и выходных токенов:

{
  "type": "tokens",
  "in_cost_per_million": 5.5,
  "out_cost_per_million": 33.0,
  "free_requests": false
}

in_cost_per_million — стоимость входных токенов, out_cost_per_million — стоимость выходных токенов. Оба значения указываются за миллион токенов.

Фиксированная стоимость генерации одного изображения:

{
  "type": "image",
  "cost_per_image": 3.0,
  "free_requests": false
}

cost_per_image — стоимость генерации одного изображения в рублях.

Стоимость изображения в зависимости от качества:

{
  "type": "image",
  "cost_per_image_quality": {
    "1k": 1.2,
    "2k": 3.0
  },
  "free_requests": false
}

Ключи объекта cost_per_image_quality соответствуют значениям параметра качества модели, а значения задают стоимость одного изображения в рублях. Например, 1k — стоимость изображения в качестве 1K, 2k — стоимость изображения в качестве 2K.

Аналогичная структура используется для new_pricing. В отличие от pricing, объект new_pricing дополнительно содержит поле date_of_use с датой начала применения новой стоимости в формате DD.MM.YYYY.

Структура объекта OptionSpec (Спецификация опций)

Этот объект описывает доступные варианты выбора для конкретной настройки модели (например, уровня reasoning_effort или image_quality).

Поле	Тип	Описание
default	string | null	Значение настройки по умолчанию, которое используется, если параметр не передан явно в запросе.
choices	array of strings | null	Список всех допустимых значений для данной настройки (например, ["low", "medium", "high"] или ["1K", "2K", "4K"]).

---

GET /models/status

Возвращает текущий статус работоспособности всех моделей, процент успешных запросов и метрики производительности (TPS или ART).

Обратите внимание

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

• Авторизация: Не требуется

Параметры запроса (Query)

Параметры отсутствуют.

Структура ответа (200 OK)

Ответ представляет собой JSON-объект, где ключами являются идентификаторы моделей (например, gpt-4o, hydra-gpt), а значениями — объекты со статистикой по каждой модели.

Структура объекта статистики модели

Поле	Тип	Описание
message	string	Текстовый статус состояния модели. Возможные значения: • Good: Стабильная работа (>90% успеха). • Normal: Незначительные сбои (>80% успеха). • Acceptable: Нестабильно, но работает (>70% успеха). • Bad: Критические проблемы стабильности (>60% успеха). • Dead: Модель неработоспособна (<60% успеха). • Disabled: Модель отключена администратором. • Not enough data: Недостаточно запросов для статистики.
success_rate	float	Процент успешных запросов за последнее время (на основе последних логов).
tps	float | null	(Tokens Per Second) Средняя скорость генерации токенов. Присутствует для текстовых (chat, vision) и эмбеддинг моделей.
art	float | null	(Average Response Time) Среднее время ответа в секундах. Присутствует для всех моделей.

---

Генерация контента (Creation)

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

---

POST /chat/completions

Основной эндпоинт для генерации текста, поддерживающий мультимодальные запросы (текст + изображения) и вызов инструментов (function calling).

• Авторизация: Требуется

Параметры запроса (Тело)

Параметр	Тип	Обязательный	По умолчанию	Описание
model	string	Да	-	ID модели для генерации (например, gpt-4o-mini).
messages	array	Да	-	Массив объектов сообщений, формирующих диалог. См. структуру ниже.
max_tokens	integer	Нет	0	Максимальное количество токенов в ответе. 0 означает без ограничений.
temperature	number	Нет	0.7	"Креативность" ответа (от 0.0 до 2.0).
stream	boolean	Нет	false	true для получения ответа в виде потока (server-sent events).
tools	array	Нет	-	Список инструментов (функций), которые модель может вызвать. Универсальная поддержка инструментов (Function Calling). Требует поддержки tools моделью, если её supported_parameters задан. См. описание инструментов ниже.
tool_choice	string / object	Нет	-	Управление вызовом инструментов: "none", "auto", "required" или {"type": "function", "function": {"name": "имя_функции"}}. Передаётся при поддержке tool_choice моделью.
response_format	object	Нет	-	Формат ответа: {"type": "text"}, {"type": "json_object"} или {"type": "json_schema", "json_schema": {...}}. См. описание Structured Outputs ниже.
reasoning_effort	string	Нет	-	Уровень усилий при рассуждении (reasoning). Только для поддерживаемых моделей. Доступные варианты (choices) можно узнать через GET /models.
quality	string	Нет	-	Уровень качества изображения. Только для поддерживаемых моделей. Доступные варианты (choices) можно узнать через GET /models.
size	string	Нет	-	Размер изображения (например, 1024x1024). Зависит от модели. Только для поддерживаемых моделей. Доступные варианты (choices) можно узнать через GET /models.
top_p	number	Нет	-	Ядерная выборка (от 0.0 до 1.0). Модель рассматривает токены с суммарной вероятностью top_p.
top_k	integer	Нет	-	Модель выбирает из k наиболее вероятных следующих токенов.
frequency_penalty	number	Нет	-	Штраф за частоту токенов (от -2.0 до 2.0).
presence_penalty	number	Нет	-	Штраф за наличие токенов в тексте (от -2.0 до 2.0).
repetition_penalty	number	Нет	-	Штраф за повторение (от 0.0 до 2.0). Помогает уменьшить зацикливание модели.
min_p	number	Нет	-	Минимальная вероятность токена (от 0.0 до 1.0). Токены с вероятностью ниже min_p * вероятность самого вероятного токена отсекаются.
top_a	number	Нет	-	Параметр Top-A (от 0.0 до 1.0). Ограничивает выбор токенов в зависимости от вероятности самого вероятного токена.
web_search	boolean, string	Нет	-	Возможные значения: true или "links" — поиск с источниками (ссылками); "no-links" — поиск без источников (чистый текст); false или null — поиск выключен. Подробнее: Поиск в интернете через чат.

Поддержка параметров моделью

Перед запросом проверяйте supported_parameters выбранной модели в GET /models.

• Если список задан, неподдерживаемые дополнительные параметры не передаются провайдеру. Это относится к temperature, top_p, top_k, frequency_penalty, presence_penalty, repetition_penalty, min_p, top_a, max_tokens, response_format и tool_choice.
• Пустой список [] означает отсутствие поддержки этих дополнительных параметров и возможностей tools / structured_outputs.
• Если поле отсутствует в ответе /models, фильтрация по этому списку и проверки возможностей по нему не применяются: сохраняется прежнее поведение. Это не гарантирует поддержку всех возможностей провайдером.
• reasoning_effort регулируется отдельными настройками модели, а не этим списком. Поля model, messages и stream также не являются дополнительными параметрами из списка.
• Для инструментов и Structured Outputs действуют проверки с ошибкой, а не молчаливое отключение, как описано ниже.

supported_parameters — характеристика модели, а не поле запроса /chat/completions. Значение structured_outputs в этом списке обозначает возможность, а не отдельный параметр тела запроса.

Вызов инструментов (Function Calling)

Элемент массива tools имеет следующую структуру:

Поле	Тип	Обязательный	Описание
type	string	Да	"function".
function.name	string	Да	Имя функции.
function.description	string	Нет	Описание назначения функции.
function.parameters	object	Для strict: true	JSON Schema аргументов функции.
function.strict	boolean	Нет	При true включает строгую схему аргументов; правила приведены ниже.

Значения tool_choice:

• "none" — не вызывать инструменты.
• "auto" — модель выбирает между обычным ответом и вызовом инструмента.
• "required" — требуется вызов инструмента.
• {"type": "function", "function": {"name": "get_weather"}} — выбор конкретной функции из tools.

Если supported_parameters задан и не содержит tools, запрос с непустым tools или историей вызовов (messages[].tool_calls, сообщения с role: "tool") отклоняется с HTTP 400. Указание tool_choice: "none" не отменяет эту проверку.

Для tools[].function.strict: true в списке модели также требуется structured_outputs. Схема function.parameters проверяется по тем же строгим правилам, что и схема ответа. Для строгих инструментов наличие response_format в списке не требуется.

Формат ответа и Structured Outputs

response_format.type	Назначение	Требуемые возможности при заданном supported_parameters
text	Обычный текстовый ответ.	response_format для передачи параметра провайдеру.
json_object	JSON mode: запрос JSON без заданной схемы.	response_format для передачи параметра провайдеру.
json_schema	Структурированный ответ по JSON Schema.	Одновременно response_format и structured_outputs; иначе HTTP 400.

Для text и json_object поле json_schema передавать нельзя. Если модель не поддерживает response_format, эти два формата отфильтровываются, поэтому на JSON-ответ в таком случае рассчитывать нельзя.

JSON mode

Для {"type": "json_object"} в текстовом содержимом хотя бы одного сообщения должна присутствовать строка JSON без учёта регистра, например: «Ответь в формате JSON». В противном случае API возвращает HTTP 422. Этот режим не задаёт структуру полей; для этого используйте json_schema.

Структура response_format.json_schema

Поле	Тип	Обязательный	Описание
name	string	Да	Имя схемы: от 1 до 64 символов, латинские буквы, цифры, _ и -.
description	string	Нет	Описание назначения схемы.
schema	object	Да	JSON Schema ответа.
strict	boolean	Нет	При true включает строгий режим. Если отсутствует или равен false, строгие проверки не включаются.

Правила валидации схемы

• Корень должен иметь type: "object" и не должен содержать anyOf.
• Допускаются типы object, array, string, number, integer, boolean, null, а также вложенный anyOf.
• Поддерживаются локальные ссылки $ref (#, #/$defs/...), определения $defs / definitions и рекурсивные схемы. Внешние и неразрешимые ссылки отклоняются.
• Проверяемая глубина вложения схемы ограничена 10 уровнями.
• При strict: true каждый объект должен задавать additionalProperties: false, а required должен включать все его свойства. Необязательное значение можно выразить типом с null, сохранив поле в required.
• При strict: true массив должен иметь items. Не поддерживаются ключевые слова allOf, oneOf, not, dependentRequired, dependentSchemas, if, then, else, patternProperties, unevaluatedProperties, prefixItems, contains, unevaluatedItems.
• Для строгой схемы действуют суммарные ограничения: 5000 свойств объектов, 1000 значений enum, 120 000 символов в именах свойств и определений, строковых значениях enum и const. Для одного enum с более чем 250 значениями суммарная длина его строковых значений не должна превышать 15 000 символов.

Запрос со Structured Outputs

Замените example-model на ID модели, у которой в /models указаны response_format и structured_outputs.

{
  "model": "example-model",
  "messages": [
    {
      "role": "user",
      "content": "Извлеки информацию: Анна и Борис идут на выставку в пятницу."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "event",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "day": {"type": "string"},
          "participants": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": ["name", "day", "participants"],
        "additionalProperties": false
      }
    }
  }
}

При обычном ответе JSON возвращается строкой в choices[].message.content, а не отдельным объектом в оболочке ответа:

{
  "role": "assistant",
  "content": "{\"name\":\"Выставка\",\"day\":\"пятница\",\"participants\":[\"Анна\",\"Борис\"]}"
}

Границы проверки

HydraAI проверяет входную схему и передаёт формат провайдеру, но не выполняет повторную валидацию сгенерированного ответа по этой схеме. Фактическое соблюдение формата зависит от модели и провайдера. При прерывании генерации, достижении лимита или отказе модели результат может не соответствовать схеме. При потоковом ответе не разбирайте отдельный фрагмент как законченный JSON — сначала соберите полный ответ.

Рассуждения модели в ответе

Если выбранная модель и провайдер поддерживают вывод рассуждений, они возвращаются отдельно от обычного текста ответа:

• при stream: false — в поле choices[].message.reasoning_content;
• при stream: true — фрагментами в поле choices[].delta.reasoning_content.

Фрагменты reasoning_content в потоковом ответе необходимо объединить в исходном порядке. Поле необязательное: оно может отсутствовать, быть пустым или не возвращаться для моделей без поддержки рассуждений.

Обычный ответ может выглядеть так:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Итоговый ответ.",
        "reasoning_content": "Краткое отображаемое рассуждение модели."
      }
    }
  ]
}

В потоковом режиме поле передаётся в SSE-фрагментах аналогично content:

data: {"choices":[{"delta":{"reasoning_content":"Фрагмент рассуждения"}}]}

Ошибки инструментов и формата ответа

HTTP	Условие	Сообщение
400	Есть инструменты или их история, но в списке модели нет tools.	Tool calling is not supported for this model: <model_id>
400	Запрошен json_schema или строгий инструмент, но нет structured_outputs.	Structured Outputs are not supported for this model: <model_id>
400	Для json_schema есть structured_outputs, но нет response_format.	Structured Outputs response_format is not supported for this model: <model_id>
422	Некорректная структура response_format, недопустимая схема, неверный tool_choice или отсутствие JSON в сообщениях для JSON mode.	Сообщение валидации с причиной ошибки.

Ошибки возвращаются в общей оболочке API с полями error.message, error.type и error.code; подробнее см. Ошибки API.

Структура объекта messages

Каждый объект в массиве messages представляет одно сообщение в диалоге.

Поле	Тип	Описание
role	string	Роль автора сообщения. Возможные значения: user, assistant, system, tool.
content	string / array	Содержимое сообщения. Может быть простой строкой или массивом для мультимодальных запросов.
tool_calls	array	(Только для role: assistant) Список вызовов инструментов, которые сделала модель.
tool_call_id	string	(Только для role: tool) ID вызова инструмента, на который отвечает это сообщение.

Мультимодальный content

Для отправки изображений вместе с текстом (для vision моделей), поле content должно быть массивом объектов:

"content": [
  {
    "type": "text",
    "text": "Что изображено на этой картинке?"
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "https://example.com/image.jpg" 
    }
  }
]

Поле url в image_url поддерживает как URL-адреса (https://...), так и Data URI в формате base64 (data:image/jpeg;base64,...).

Структура ответа (200 OK)

Поле	Тип	Описание
id	string	Уникальный идентификатор чат-сессии.
object	string	Тип объекта, обычно chat.completion.
created	integer	Unix-время создания ответа.
model	string	Модель, которая обработала запрос.
choices	array	Массив с вариантами ответов. Обычно содержит один элемент.
usage	object	Объект с информацией о токене и стоимости.

Структура объекта choices

Поле	Тип	Описание
message	object	Объект сообщения от ассистента. Содержит поля role, content и, если модель поддерживает рассуждения, необязательное reasoning_content.
finish_reason	string	Причина завершения генерации. Возможные значения: stop (естественное завершение), length (достигнут лимит max_tokens), tool_calls (модель вызвала инструмент).
index	integer	Индекс варианта ответа в массиве choices.

Структура объекта usage

Поле	Тип	Описание
prompt_tokens	integer	Количество токенов в вашем запросе (messages).
prompt_tokens_details	PromptTokensDetails | None	Детализация токенов в запросе. Может содержать cached_tokens — количество токенов, прочитанных из prompt cache.
completion_tokens	integer	Количество токенов в сгенерированном ответе.
completion_tokens_details	CompletionTokensDetails | None	Детализация токенов в ответе.
total_tokens	integer	Суммарное количество токенов.
total_time	float	Общее время генерации в секундах.
cost_request	number	Итоговая стоимость запроса в рублях.
free_request	bool | None	Был запрос бесплатным или нет.

prompt_tokens_details может содержать следующие поля:

Поле	Тип	Описание
cached_tokens	integer | null	Количество токенов, прочитанных из prompt cache.

Пример запроса

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "Ты — полезный ассистент."
    },
    {
      "role": "user",
      "content": "Что такое API?"
    }
  ],
  "temperature": 0.5
}

Пример ответа

{
  "id": "chat-id-...",
  "object": "chat.completion",
  "created": 1716900000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "API (Application Programming Interface) — это программный интерфейс приложения..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 8
    },
    "completion_tokens": 50,
    "total_tokens": 70,
    "cost_request": 0.005,
    "total_time": 1.23,
    "free_request": false
  }
}

---

POST /images/edits

POST /images/generations

Эндпоинты (взаимозаменяемые) для генерации и редактирования изображений по текстовому описанию или изображению.

• Авторизация: Требуется

Время жизни URL

Сгенерированные изображения, передаваемые в формате url, доступны по ссылке только 24 часа, после чего удаляются с сервера.

Параметры запроса (Тело)

Параметр	Тип	Обязательный	По умолчанию	Описание
model	string	Да	-	ID модели для генерации (например, flux.1-schnell).
prompt	string	Да	-	Текстовое описание желаемого изображения (минимум 3 символа).
negative_prompt	string	Нет	-	Описание того, чего не должно быть на изображении.
n	integer	Нет	1	Количество генерируемых изображений (от 1 до 4).
response_format	string	Нет	b64_json	Формат ответа: url (ссылка на изображение) или b64_json (строка base64).
quality	string	Нет	-	Качество генерируемого изображения (например, 2k, HD). Зависит от модели.
size	string	Нет	1024x1024	Размер изображения (например, 1024x1024, 9:16). Зависит от модели.
style	string	Нет	-	Стиль генерируемого изображения (например, cinematic, anime). Зависит от модели.
image_url	array of strings | null	Нет	-	URL-адрес или base64 входного/эталонного изображения для редактирования. Например ["https://i.com/1.jpg","data:image/png;base64,iVBORw0KG"] или "https://i.com/cat.jpg".

Структура ответа (200 OK)

Поле	Тип	Описание
id	string	Уникальный идентификатор запроса.
created	integer	Unix-время создания ответа.
data	array	Массив с результатами генерации.
usage	object	Объект с информацией о стоимости и времени выполнения.

Структура объекта data

Поле	Тип	Описание
b64_json	string / null	Сгенерированное изображение в формате base64 (если response_format="b64_json").
url	string / null	Ссылка на сгенерированное изображение (если response_format="url").
revised_prompt	string / null	Промпт, который был изменен моделью для улучшения качества (если применимо).

Пример запроса

{
  "model": "flux.1-schnell",
  "prompt": "Фото большого и пушистого кота в высоком качестве, RAW фото",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}

Пример ответа

{
  "id": "genimg-id-...",
  "created": 1716900100,
  "data": [
    {
      "revised_prompt": "A high-quality RAW photo of a large, fluffy cat.",
      "url": "https://s2.hydraai.ru/..."
    }
  ],
  "usage": {
    "total_time": 5.43,
    "cost_request": 0.5,
    "free_request": false
  }
}

---

POST /systemone

Получение типизированных решений по состоянию state и именованным вопросам questions. System One не генерирует текстовое объяснение: возвращает выбор, оценку или вероятность для каждого вопроса.

• Авторизация: Требуется

Параметры запроса (Тело)

Поле	Тип	Обязательный	Описание
model	string	Да	Непустой ID модели или её альтернативный ID.
state	string / object / array	Да	Состояние и контекст для принятия решений. null, числа и boolean на верхнем уровне не допускаются.
questions	object	Да	Непустой объект: имя вопроса → объект вопроса.
questions[name].type	string	Да	Тип вопроса: choice, score, noul или box. Доступность зависит от провайдера.
questions[name].instructions	string / object / array	Да	Инструкция для вопроса. Upstage принимает только строку.
questions[name].criteria	object / array	Зависит от типа	Варианты выбора или уровни оценки, см. ниже.

Не передавайте параметры chat completions: messages, stream, temperature, max_tokens, tools и другие неописанные поля. Неизвестные поля запроса и вопросов отклоняются с HTTP 422.

Типы вопросов и ограничения Upstage (solar-decide)

Тип	Общая схема criteria	Ограничения Upstage
choice	Обязательный объект: имя варианта → описание (строка, объект, массив или null).	От 2 до 26 вариантов, каждое описание — строка.
score	Обязательный непустой массив описаний уровней (строки, объекты или массивы).	От 2 до 10 уровней, каждое описание — строка.
noul	Необязательный объект с полями true и false, каждое — строка, объект или массив.	Не передавайте criteria (допускается null).
box	Не используется.	Не поддерживается; HTTP 422.

Расширения общей схемы не означают, что конкретный провайдер их поддерживает. У Upstage выбор ограничен 26 вариантами, поскольку используются однотокенные метки A–Z.

Пример запроса

{
  "model": "solar-decide",
  "state": {
    "review": "Доставка быстрая, товар понравился."
  },
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "Определи тональность отзыва.",
      "criteria": {
        "positive": "Положительный отзыв",
        "negative": "Отрицательный отзыв"
      }
    },
    "satisfaction": {
      "type": "score",
      "instructions": "Оцени удовлетворённость покупателя.",
      "criteria": ["Недоволен", "Нейтрален", "Доволен"]
    },
    "fast_delivery": {
      "type": "noul",
      "instructions": "Сообщает ли покупатель о быстрой доставке?"
    }
  }
}

Пример ответа (иллюстративный; usage и стоимость зависят от запроса и тарифа)

{
  "id": "s-one-id-8407daad-cc0f-4ac9-84e6-d2ed40e4abcb",
  "created": 1792161359,
  "model": "solar-decide",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "positive",
      "probabilities": {"positive": 1.0, "negative": 0.0},
      "confidence": 1.0
    },
    "satisfaction": {
      "type": "score",
      "score": 2.0,
      "legend": {"0": "Недоволен", "1": "Нейтрален", "2": "Доволен"},
      "probabilities": {"0": 0.0, "1": 0.0, "2": 1.0},
      "confidence": 1.0
    },
    "fast_delivery": {
      "type": "noul",
      "noul": 0.98
    }
  },
  "usage": {
    "input_tokens": 490,
    "output_tokens": 3,
    "total_tokens": 493,
    "total_time": 2.887,
    "cost_request": 0.001,
    "free_request": false
  }
}

Поля ответа

Поле	Описание
id	Идентификатор запроса HydraAI с префиксом s-one-id-.
created	Unix timestamp формирования ответа в секундах.
model	Канонический ID модели HydraAI.
answers	Один ответ на каждый вопрос; ключи совпадают с именами вопросов запроса.
answers[name].type	Тип соответствующего вопроса.
usage.input_tokens	Входные токены.
usage.output_tokens	Выходные токены.
usage.total_tokens	Сумма входных и выходных токенов.
usage.total_time	Время обработки запроса в секундах.
usage.cost_request	Стоимость запроса в рублях по тарифу модели.
usage.free_request	Признак использования бесплатного запроса.

Для choice поле choice содержит выбранный вариант, probabilities — вероятности вариантов, confidence — степень концентрации распределения (не гарантия правильности). Для score поле score — ожидаемое значение от 0 до числа уровней минус один; legend — описания уровней по индексам, probabilities — вероятности по индексам, confidence — концентрация распределения. Для noul поле noul — вероятность ответа «да» от 0 до 1, без отдельного confidence. Для box общая схема предусматривает box с координатами top, bottom, left, right и необязательный confidence; Upstage этот тип не обслуживает.

Поля probabilities, confidence и legend могут отсутствовать, если провайдер их не вернул. Порог принятия решения по вероятности задаёт ваше приложение.

---

POST /embeddings

Эндпоинт для создания числовых представлений (векторов или эмбеддингов) для текста.

• Авторизация: Требуется

Параметры запроса (Тело)

Параметр	Тип	Обязательный	По умолчанию	Описание
model	string	Да	-	ID модели для создания эмбеддингов (например, text-embedding-ada).
input	string / array	Да	-	Текст или массив текстов для векторизации. Макс. 2048 элементов в массиве.
dimensions	integer	Нет	-	Желаемое количество измерений для векторов (поддерживается только в text-embedding-3-*).
encoding_format	string	Нет	float	Формат возвращаемых векторов: float (массив чисел) или base64 (строка).
user	string	Нет	-	Уникальный идентификатор вашего конечного пользователя для отслеживания злоупотреблений.

Структура ответа (200 OK)

Поле	Тип	Описание
id	string	Уникальный идентификатор запроса.
object	string	Тип объекта, всегда list.
created	integer	Unix-время создания ответа.
data	array	Массив с результатами векторизации.
model	string	Модель, которая обработала запрос.
usage	object	Объект с информацией о токене и стоимости.

Структура объекта data

Поле	Тип	Описание
object	string	Тип объекта, всегда embedding.
embedding	array / string	Вектор эмбеддинга в виде массива чисел или строки base64.
index	integer	Индекс этого эмбеддинга в исходном массиве input.

Пример запроса

{
  "input": [
    "HydraAI API — это мощно",
    "Векторизация текста"
  ],
  "model": "text-embedding-3-small",
  "dimensions": 512
}

Пример ответа

{
  "id": "embd-id-...",
  "created": 1716900200,
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [ 0.001, -0.023, /* ... 512 more floats */ ],
      "index": 0
    },
    {
      "object": "embedding",
      "embedding": [ -0.015, 0.008, /* ... 512 more floats */ ],
      "index": 1
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12,
    "total_time": 0.12,
    "cost_request": 0.0001,
    "free_request": false
  }
}

Системные (System)

Эндпоинты для получения системной информации о состоянии API и доступных серверах подключения.

---

GET /logs/summary

Возвращает агрегированную статистику HydraAi API за последние 24 часа.

• Авторизация: Не требуется

Параметры запроса

Отсутствуют.

Структура ответа (200 OK)

Поле	Тип	Описание
version	string	Текущая версия API.
total_tokens	integer	Общее количество токенов, обработанных API за последние 24 часа.
total_requests	integer	Общее количество запросов к API за последние 24 часа.
successful_requests_percentage	number	Процент успешно обработанных запросов за последние 24 часа.

Пример ответа

{
  "version": "0.10.4β",
  "total_tokens": 1331686237,
  "total_requests": 428209,
  "successful_requests_percentage": 99.979
}

---

GET /servers

Возвращает список базовых URL серверов, доступных для подключения к API.

• Авторизация: Не требуется

Примечание

Этот эндпоинт предназначен для получения актуального списка основных, резервных и региональных серверов HydraAi API.

Параметры запроса

Отсутствуют.

Структура ответа (200 OK)

Ответ представляет собой массив объектов.

Структура объекта сервера

Поле	Тип	Описание
name	string	Название сервера.
description	string | null	Дополнительное описание сервера, если применимо.
base_url	string	Базовый URL для работы с API, включая /v1.
health_url	string	URL для проверки работоспособности сервера API.
server_url	string	Базовый URL сервера без /v1.

Пример ответа

[
  {
    "name": "Основной сервер",
    "description": "Поддерживает работу с ZennoPoster.",
    "base_url": "https://api.gidra.ai/v1",
    "health_url": "https://api.gidra.ai/v1/health",
    "server_url": "https://api.gidra.ai"
  },
  {
    "name": "Резервный сервер (Германия)",
    "base_url": "https://de.api.gidra.ai/v1",
    "health_url": "https://de.api.gidra.ai/v1/health",
    "server_url": "https://de.api.gidra.ai"
  },
  {
    "name": "Сервер в России (Санкт-Петербург)",
    "base_url": "https://spb.api.gidra.ai/v1",
    "health_url": "https://spb.api.gidra.ai/v1/health",
    "server_url": "https://spb.api.gidra.ai"
  }
]

---

Рекомендации по использованию /servers

Для повышения отказоустойчивости интеграции рекомендуется:

1. При запуске приложения или периодически запрашивать список серверов через GET /servers.
2. Кэшировать полученный список серверов в памяти приложения.
3. При необходимости сохранять его в файл, базу данных или другое локальное хранилище.
4. Если текущий сервер API становится недоступен, последовательно проверять доступность серверов из списка через поле health_url.
5. Использовать первый сервер, который успешно отвечает и доступен для работы.

Рекомендуемый подход

Используйте /servers как источник актуального списка точек подключения, а health_url — как механизм автоматического переключения между серверами при сбоях или сетевых проблемах.

Это особенно полезно для:

• high-availability интеграций;
• серверных приложений с автоматическим failover;
• desktop и automation-решений;
• сценариев, где важно минимизировать простой при недоступности одного из серверов.