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

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

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

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

Авторизация

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

Authorization: Bearer sk-hydra-ai-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

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

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

`GET /v1/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).

`POST /v1/users/redeem`

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

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

Важно

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

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

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

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

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

Модели (Models)

`GET /v1/models`

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

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

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

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

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

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

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

Поле	Тип	Описание
`id`	string	Уникальный идентификатор модели, который используется в запросах.
`name`	string	Человекочитаемое название модели.
`description`	string	Краткое описание возможностей модели.
`type`	string	Тип модели (`chat`, `vision`, `image`, `embedding`).
`context`	integer	Максимальный размер контекстного окна в токенах.
`active`	boolean	`true`, если модель в данный момент активна и доступна для использования.
`pricing`	object	Объект с информацией о стоимости использования модели.

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

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

`POST /v1/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).
`top_p`	number	Нет	-	Ядерная выборка. Модель рассматривает токены с суммарной вероятностью `top_p`.
`top_k`	integer	Нет	-	Модель выбирает из `k` наиболее вероятных следующих токенов.
`frequency_penalty`	number	Нет	-	Штраф за частоту токенов (от `-2.0` до `2.0`).
`presence_penalty`	number	Нет	-	Штраф за наличие токенов в тексте (от `-2.0` до `2.0`).

Структура объекта `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`.
`finish_reason`	string	Причина завершения генерации. Возможные значения: `stop` (естественное завершение), `length` (достигнут лимит `max_tokens`), `tool_calls` (модель вызвала инструмент).
`index`	integer	Индекс варианта ответа в массиве `choices`.

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

Поле	Тип	Описание
`prompt_tokens`	integer	Количество токенов в вашем запросе (`messages`).
`completion_tokens`	integer	Количество токенов в сгенерированном ответе.
`total_tokens`	integer	Суммарное количество токенов.
`cost_request`	number	Итоговая стоимость запроса в рублях.

Пример запроса (текст)

{
  "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,
    "completion_tokens": 50,
    "total_tokens": 70,
    "cost_request": 0.005,
    "total_time": 1.23,
    "free_request": false
  }
}

`POST /v1/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).
`size`	string	Нет	`1024x1024`	Размер изображения (например, `1024x1024`). Зависит от модели.
`style`	string	Нет	-	Стиль генерируемого изображения (например, `cinematic`, `anime`). Зависит от модели.

Структура ответа (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 /v1/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
  }
}

Инструменты (Tools)

Наш API предоставляет мощный набор инструментов для работы с веб-контентом: поиск информации, новостей, изображений и прямое извлечение контента со страниц.

`POST /v1/search`

Позволяет выполнять поиск в различных системах с опциональным извлечением полного контента найденных страниц и его очисткой.

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

Расчет стоимости

Стоимость запроса = 0.02 ₽ (за сам поиск) + (количество успешно обработанных crawl_results * 0.02 ₽).

Пример 1: Запрос с crawl_results=0. Стоимость = 0.02 ₽.
Пример 2: Запрос с max_results=5 и crawl_results=2. Если контент успешно извлечен с 2 страниц, стоимость составит 0.02 ₽ + (2 * 0.02 ₽) = 0.06 ₽.

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`query`	string	Да	-	Ваш поисковый запрос (длина от 3 до 250 символов).
`search_service`	string	Нет	`google`	Поисковая система. Доступные значения: `google`, `bing`, `duckduckgo`.
`max_results`	integer	Нет	`5`	Количество результатов для возврата (от 1 до 10).
`crawl_results`	integer	Нет	`0`	Количество результатов, с которых нужно извлечь полный контент (от 0 до 10).
`language`	string	Нет	-	Предпочтительный язык (например, `ru`, `en`).
`time_range`	string	Нет	-	Временной диапазон. Доступные значения: `day`, `month`, `year`.
`content_clearing`	boolean	Нет	`true`	Очищать ли контент извлеченных страниц (при `crawl_results > 0`).

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

{
    "query": "Что такое API?",
    "search_service": "google",
    "language": "ru",
    "max_results": 3,
    "crawl_results": 1,
    "content_clearing": true
}

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

Возвращает список найденных результатов. Каждый результат содержит title, link, snippet. Для страниц, где crawl_results был применен успешно, также будет поле content. В конце ответа находится объект usage с информацией о стоимости.

`POST /v1/search/news`

Специализированный поиск по новостным источникам.

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

Расчет стоимости

Стоимость запроса = 0.02 ₽ (за поиск новостей) + (количество успешно обработанных crawl_results * 0.02 ₽).

Пример: Запрос с max_results=3 и crawl_results=1. Если контент успешно извлечен с 1 страницы, стоимость составит 0.02 ₽ + (1 * 0.02 ₽) = 0.04 ₽.

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`query`	string	Да	-	Запрос для поиска новостей (длина от 3 до 250 символов).
`search_service`	string	Нет	`google`	Новостной сервис. Доступные значения: `google`, `bing`, `duckduckgo`.
`max_results`	integer	Нет	`5`	Количество новостей для возврата (от 1 до 10).
`crawl_results`	integer	Нет	`0`	Количество новостей, с которых нужно извлечь полный контент (от 0 до 10).
`language`	string	Нет	-	Предпочтительный язык новостей (например, `ru`, `en`).
`time_range`	string	Нет	-	Временной диапазон. Доступные значения: `day`, `month`, `year`.
`content_clearing`	boolean	Нет	`true`	Очищать ли контент извлеченных новостей.

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

{
    "query": "Технологические стартапы 2025",
    "search_service": "google",
    "max_results": 3,
    "crawl_results": 1,
    "language": "ru",
    "time_range": "month"
}

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

Возвращает список найденных новостей (аналогично обычному поиску) и информацию об использовании.

`POST /v1/search/images`

Позволяет находить изображения по ключевым словам с различными фильтрами.

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

Расчет стоимости

Стоимость фиксирована и составляет 0.02 ₽ за каждый запрос, независимо от количества найденных изображений.

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`keywords`	string	Да	-	Ключевые слова для поиска (длина от 3 до 250 символов).
`safesearch`	string	Нет	`moderate`	Уровень безопасного поиска. Возможные значения: `on`, `moderate`, `off`.
`max_results`	integer	Нет	`10`	Максимальное количество результатов (от 1 до 100).
`timelimit`	string	Нет	-	Время публикации. Возможные значения: `Day`, `Week`, `Month`, `Year`.
`size`	string	Нет	-	Размер. Возможные значения: `Small`, `Medium`, `Large`, `Wallpaper`.
`color`	string	Нет	-	Цвет. Возможные значения: `color`, `Monochrome`, `Red`, `Orange`, `Yellow`, `Green`, `Blue`, `Purple`, `Pink`, `Brown`, `Black`, `Gray`, `Teal`, `White`.
`type_image`	string	Нет	-	Тип. Возможные значения: `photo`, `clipart`, `gif`, `transparent`, `line`.
`layout`	string	Нет	-	Компоновка. Возможные значения: `Square`, `Tall`, `Wide`.

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

{
    "keywords": "ночной город огни",
    "safesearch": "moderate",
    "max_results": 5,
    "size": "Large",
    "color": "Blue"
}

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

Возвращает список найденных изображений. Каждый объект содержит title, image (URL на полное изображение), thumbnail (URL на превью), url (URL страницы-источника), height, width, source.

`POST /v1/crawl`

Получает и (опционально) очищает основной контент веб-страницы по её URL.

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

Расчет стоимости

Стоимость фиксирована и составляет 0.02 ₽ за каждый успешный запрос на извлечение контента.

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`url`	string	Да	-	URL-адрес страницы, с которой нужно получить контент.
`content_clearing`	boolean	Нет	`true`	Очищать ли контент (удалять разметку, лишние переносы и т.д.).

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

{
    "url": "https://example.com/some-article-to-read",
    "content_clearing": true
}

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

Возвращает объект results с извлеченным контентом (title, link, content) и объект usage со стоимостью. В случае ошибки извлечения поле results может быть null.

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

Авторизация

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

GET /v1/users/profile

POST /v1/users/redeem

Модели (Models)

GET /v1/models

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

POST /v1/chat/completions

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

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

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

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

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

POST /v1/images/generations

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

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

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

POST /v1/embeddings

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

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

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

Инструменты (Tools)

POST /v1/search

POST /v1/search/news

POST /v1/search/images

POST /v1/crawl

`GET /v1/users/profile`

`POST /v1/users/redeem`

`GET /v1/models`

`POST /v1/chat/completions`

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

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

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

`POST /v1/images/generations`

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

`POST /v1/embeddings`

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

`POST /v1/search`

`POST /v1/search/news`

`POST /v1/search/images`

`POST /v1/crawl`