Обращение через конверт

Метод POST /v1/<код клиента>/ask принимает запрос в собственном формате Ainergy: тело запроса к нейросети вкладывается в конверт с именем нексуса и служебными полями, а ответ возвращается в таком же конверте.

Способ применяется в трех случаях:

• путь конечной точки нексуса вам неизвестен – в конверте он не нужен, достаточно имени нексуса;
• в запросе передаются файлы;
• у нексуса параметризованный путь, и вы передаете значения подстановок отдельным полем, не собирая путь самостоятельно.

В остальных случаях используется Обращение к нексусу по пути нейросети – оно совместимо с клиентскими библиотеками.

Метод принимает только POST.

Код клиента в пути

---

<код клиента> – код вашей инсталляции. Он состоит из строчных латинских букв, цифр, дефиса, подчеркивания и точки и указан в профиле настроек Ainergy.

Запрос

---

{
  "id": "req-42",
  "nexus": "<имя нексуса>",
  "data": {
    "messages": [{"role": "user", "content": "Привет"}]
  }
}

Поля запроса

Поле	Обязательно	Описание
nexus	Да	Укажите имя нексуса. Получить список доступных имен можно методом из статьи Доступные нексусы.
data	Да	Укажите тело запроса к нейросети. Содержимое передается без изменений, его формат определяет сама нейросеть.
id	Нет	Укажите собственный идентификатор обращения. Значение возвращается в ответе и попадает в журнал обращений.
tags	Нет	Укажите метки, по которым связанные обращения группируются в журнале.
username	Нет	Укажите имя пользователя вашей системы, от лица которого выполняется запрос. Если поле не заполнено, в журнале указывается владелец токена.
files	Нет	Добавьте файлы, которые уходят в нейросеть вместе с запросом. Каждый элемент массива описывает один файл.
variables	Нет	Укажите значения подстановок, если у нексуса параметризованный путь. Ключ объекта – имя подстановки из пути нексуса без фигурных скобок, значение – строка. Для пути /status/poll/{task_id} это {"task_id": "abc123"}.

Поля элемента массива files

Поле	Обязательно	Описание
form_name	Да	Укажите имя поля формы, в котором нейросеть ожидает файл.
base64	Да/Нет	Укажите содержимое файла в кодировке base64, без префикса data:<тип>;base64,. Для каждого файла заполняется либо это поле, либо url.
url	Да/Нет	Укажите адрес файла. Поле игнорируется, если заполнено base64.
file_name	Нет	Укажите имя файла. Значение по умолчанию: noname.
mime_type	Нет	Укажите тип содержимого файла. Значение по умолчанию: application/octet-stream.

note

Ограничение на размер тела запроса – 50 МБ – действует и на этот метод. Файлы, переданные в поле base64, считаются в размере уже закодированными, то есть примерно на треть больше исходных.

Ответ

---

{
  "id": "req-42",
  "nexus": "<имя нексуса>",
  "data": {
    "choices": [{"index": 0, "finish_reason": "stop",
      "message": {"role": "assistant", "content": "..."}}],
    "usage": {"prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46}
  },
  "error": "",
  "code": 200,
  "stream": false
}

Ответ с ошибкой приходит в том же конверте: код нейросети или платформы попадает в поле code и становится кодом HTTP-ответа, текст – в поле error.

{
  "id": "req-42",
  "nexus": "<имя нексуса>",
  "data": {},
  "error": "invalid endpoint",
  "code": 400,
  "stream": false
}

Поля ответа

Поле	Описание
id	Идентификатор обращения из запроса.
nexus	Имя нексуса, обработавшего запрос.
data	Ответ нейросети. Если ответ пришел не в формате JSON, он целиком помещается в ключ __raw__, а его тип – в __content_type__. Если нексус настроен на возврат файла, содержимое помещается в ключ __base64__.
error	Текст ошибки. При успешном ответе – пустая строка.
code	Код ответа нейросети или платформы. Это же значение становится кодом HTTP-ответа.
stream	Признак потокового ответа. Метод потоковую передачу не выполняет, поэтому значение всегда false.
pii	Результат поиска чувствительных данных. Поле возвращается, если для нексуса настроена защита персональной информации. Состав поля определяется настройкой нексуса.

note

Потоковую передачу метод не выполняет: ответ приходит одним фрагментом. Для потоковых ответов используйте Обращение к нексусу.

Пример

---

curl https://<адрес инсталляции>/v1/<код клиента>/ask \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "demo-002",
        "nexus": "<имя нексуса>",
        "data": {"messages": [{"role": "user", "content": "Привет"}]}
      }'