Возможности F5AI API для бизнеса

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

Рекомендация: для новых проектов используйте концепции Conversations + Responses. Устаревшие методы (Threads, Messages, Runs и Chat Completions) оставлены только для обратной совместимости и не получают новых возможностей.

Единая спецификация

Объекты Response, Conversation, Item и события SSE унифицированы и расширены для F5AI.

Мультипровайдерность

Доступные модели определяются динамически через реестр — вы всегда работаете с актуальным списком.

Локальное состояние

Вся история диалогов, ответы и метрики использования хранятся на стороне F5AI; данные не передаются провайдерам.

Быстрый старт

1. Получите API-ключ

Для доступа к F5AI API необходим персональный токен.

Зарегистрируйтесь на https://f5ai.ru
Перейдите в личный кабинет → вкладка API
Скопируйте токен (например: eyJ0************QI4o)

Важно: храните токен безопасно — он открывает полный доступ к вашему аккаунту. Строки вида sk-f5ai-... не являются корректным форматом для текущей версии API.

2. Базовая точка входа

https://app.f5ai.ru/v2

Все запросы направляются на этот адрес. В каждом конкретном вызове вы добавляете нужный путь (например, /conversations).

3. Создайте Conversation

curl -X POST "https://app.f5ai.ru/v2/conversations" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "external_user_id": "user-42"
    }
  }'

После создания Conversation сохраните его id в переменную.

export F5AI_CONVERSATION_ID='66e8904a03f74e4d9a6b1234'

Поле	Обязательное	Тип	По умолчанию	Описание
`metadata`	Нет	object	{}	Произвольные метаданные диалога: например, ID клиента или сделки. До 16 пар «ключ—значение».
`items`	Нет	array	[]	Начальная история диалога. До 20 сообщений.

4. Отправьте запрос модели

curl -X POST "https://app.f5ai.ru/v2/responses" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5-mini",
    "conversation": "'$F5AI_CONVERSATION_ID'",
    "input": "Кратко опиши статус заказа"
  }'

По умолчанию запрос выполняется в фоне, поэтому API сразу вернёт Response со статусом queued. Сохраните его id и периодически запрашивайте результат.

5. Получите результат

curl "https://app.f5ai.ru/v2/responses/$F5AI_RESPONSE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Готово! Вы успешно получили ответ от модели через F5AI API.

Аутентификация

Все публичные эндпоинты версии 2 требуют передачи JWT-ключа в заголовке X-Auth-Token. Ключ выдаётся в личном кабинете и должен храниться на серверной стороне вашего приложения.

Заголовок	Тип	Описание
X-Auth-Token обязательно	JWT	Трёхчастный подписанный API key F5AI.
Content-Type conditional	string	`application/json` для JSON body; multipart boundary для загрузки аудио.
Idempotency-Key необязательно	string ≤ 255	Поддерживается при создании Response и предотвращает повторное выполнение.

Важно: строки вида sk-f5ai-... не являются корректным форматом. Никогда не передавайте ключ в URL, логи или клиентский код.

Ошибки

Ошибки возвращаются с подходящим HTTP статусом и единым конвертом. Поле code может отсутствовать для некоторых устаревших действий.

{
  "error": {
    "code": "response.invalid_request",
    "message": "input must be a string or an array"
  }
}

статус	Значение	Рекомендуемые действия
400	`invalid_request`	Проверьте синтаксис JSON, типы данных, обязательные поля и совместимость параметров.
401	`unauthorized`	Убедитесь в наличии, формате, сроке действия и подписи JWT.
402	`payment_required`	Пополните баланс аккаунта.
403	`forbidden`	Ключ отключён или операция недоступна для вашего аккаунта.
404	`not_found`	Ресурс не существует или принадлежит другому аккаунту.
500	`execution_failed`	Повторите идемпотентный запрос; при повторении ошибки обратитесь в поддержку.

Беседы (Conversations)

Беседа — это локальный контейнер для истории диалога. Все сообщения, вызовы функций и результаты инструментов хранятся в ней.

Создать беседу

POST /v2/conversations

curl -X POST "https://app.f5ai.ru/v2/conversations" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "crm_dialog_id": "dialog-901"
    },
    "items": [
      { "type": "message", "role": "user", "content": "Здравствуйте" },
      { "type": "message", "role": "assistant", "content": "Здравствуйте! Чем могу помочь?" }
    ]
  }'

Ответ:

{
  "id": "66e8904a03f74e4d9a6b1234",
  "object": "conversation",
  "created_at": 1753794000,
  "metadata": { "external_user_id": "user-42" }
}

Список бесед

GET /v2/conversations?limit=20&order=desc

curl "https://app.f5ai.ru/v2/conversations?limit=20&order=desc" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Query-параметр	Обязательное	Тип	По умолчанию	Описание
`limit`	Нет	integer	20	Число Conversations в ответе: от 1 до 100.
`order`	Нет	string	desc	Порядок: `asc` или `desc`.
`after`	Нет	string	—	Cursor для следующей страницы. Нельзя использовать вместе с `before`.
`before`	Нет	string	—	Cursor для предыдущей страницы. Нельзя использовать вместе с `after`.

Получить конкретную беседу

GET /v2/conversations/{conversation_id}

curl "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Обновить метаданные

POST /v2/conversations/{conversation_id}

curl -X POST "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "external_user_id": "user-42",
      "crm_dialog_id": "dialog-901",
      "status": "closed"
    }
  }'

Удалить беседу

DELETE /v2/conversations/{conversation_id}

curl -X DELETE "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "66e8904a03f74e4d9a6b1234",
  "object": "conversation.deleted",
  "deleted": true
}

Элементы беседы (Conversation Items)

Items представляют сообщения, function calls и результаты tools. Response автоматически добавляет свой input и output в связанную Conversation.

Добавить элементы

POST /v2/conversations/{conversation_id}/items

curl -X POST "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID/items" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": "Контекст от CRM"
      }
    ]
  }'

Список элементов

GET /v2/conversations/{conversation_id}/items?limit=20&order=asc

curl "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID/items?limit=20&order=asc" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "66e8904a03f74e4d9a6b9012",
      "object": "conversation.item",
      "type": "message",
      "role": "user",
      "status": "completed",
      "content": [
        {
          "type": "input_text",
          "text": "Подскажите статус заказа №42"
        }
      ],
      "created_at": 1753794001,
      "metadata": []
    }
  ],
  "first_id": "66e8904a03f74e4d9a6b9012",
  "last_id": "66e8904a03f74e4d9a6b9012",
  "has_more": false
}

Получить элемент

GET /v2/conversations/{conversation_id}/items/{item_id}

curl "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID/items/$F5AI_ITEM_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Удалить элемент

DELETE /v2/conversations/{conversation_id}/items/{item_id}

curl -X DELETE "https://app.f5ai.ru/v2/conversations/$F5AI_CONVERSATION_ID/items/$F5AI_ITEM_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "66e8904a03f74e4d9a6b9012",
  "object": "conversation.item.deleted",
  "deleted": true
}

Удаление Item не меняет уже завершённые Responses.

Ответы (Responses)

Response — один сохраняемый запуск модели. Он может быть связан с Conversation, продолжать предыдущий Response или работать независимо.

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

POST /v2/responses

curl -X POST "https://app.f5ai.ru/v2/responses" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-42-answer-1' \
  --data @- <<JSON
{
    "model": "gpt-5-mini",
    "conversation": "$F5AI_CONVERSATION_ID",
    "input": "Кратко опиши статус заказа",
    "background": true
}
JSON

По умолчанию запрос выполняется в фоне, поэтому API сразу вернёт Response со статусом queued.

{
  "id": "66e8904a03f74e4d9a6b5678",
  "object": "response",
  "status": "queued",
  "background": true,
  "model": "gpt-5-mini",
  "output": [],
  "conversation": {
    "id": "66e8904a03f74e4d9a6b1234"
  },
  "metadata": {}
}

Поле	Обязательное	Тип	По умолчанию	Описание
`input`	Да	string/array	—	Новый текст пользователя или массив элементов диалога.
`model`	Условно	string	Из Assistant	Код модели. Обязателен, если не передан `assistant_id`.
`assistant_id`	Условно	integer	—	ID F5AI Assistant. Можно использовать вместо `model`.
`conversation`	Нет	string/object	—	ID Conversation.
`background`	Нет	boolean	true	`true` — поставить в очередь; `false` — ждать результат синхронно.
`stream`	Нет	boolean	false	Потоковый ответ по SSE. Требует `background: false`.
`tools`	Нет	array	[]	Описание доступных модели инструментов.
`temperature`	Нет	number	1	Степень вариативности ответа: от 0 до 2.
`max_output_tokens`	Нет	integer	Лимит модели	Максимальное число токенов в ответе.

Стоимость ответа указана в поле usage.cost и выражена в копейках.

Получить статус и результат

GET /v2/responses/{response_id}

curl "https://app.f5ai.ru/v2/responses/$F5AI_RESPONSE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "66e8904a03f74e4d9a6b5678",
  "object": "response",
  "created_at": 1753794001,
  "status": "completed",
  "background": true,
  "model": "gpt-5-mini",
  "output": [
    {
      "id": "66e8904a03f74e4d9a6b9012",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Заказ собран и передан в доставку."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 10,
    "total_tokens": 28,
    "cost": 1
  },
  "conversation": {
    "id": "66e8904a03f74e4d9a6b1234"
  },
  "metadata": {}
}

Получить ответ синхронно

curl -X POST "https://app.f5ai.ru/v2/responses" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5-mini",
    "input": "Напиши краткое резюме встречи",
    "background": false
  }'

{
  "id": "$F5AI_RESPONSE_ID",
  "object": "response",
  "status": "completed",
  "background": false,
  "model": "gpt-5-mini",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "На встрече согласовали сроки, ответственных и следующий этап работ."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 16,
    "total_tokens": 28,
    "cost": 1
  },
  "error": null
}

Потоковая передача (SSE)

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Привет","sequence_number":2}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed"},"sequence_number":5}

Основные события: response.created, response.in_progress, response.output_item.added, response.output_text.delta, response.output_text.done, response.output_item.done, response.completed или response.failed.

Важно: если клиент разорвёт соединение, генерация не остановится — ответ продолжит выполняться на сервере. Вы всегда сможете получить его результат через GET /v2/responses/{response_id}.

Отменить выполняющийся ответ

POST /v2/responses/{response_id}/cancel

curl -X POST "https://app.f5ai.ru/v2/responses/$F5AI_RESPONSE_ID/cancel" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "$F5AI_RESPONSE_ID",
  "object": "response",
  "status": "cancelled",
  "background": true,
  "model": "gpt-5-mini",
  "output": [],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "cost": 0
  },
  "error": null
}

Безопасно повторяйте запросы

Передавайте уникальный Idempotency-Key в каждом логическом запросе на создание Response.

Idempotency-Key: order-42-answer-1

{
  "id": "$F5AI_RESPONSE_ID",
  "object": "response",
  "status": "queued",
  "background": true,
  "model": "gpt-5-mini",
  "output": [],
  "metadata": {}
}

Продолжить цепочку без Conversation

curl -X POST "https://app.f5ai.ru/v2/responses" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<JSON
{
    "model": "gpt-5-mini",
    "previous_response_id": "$F5AI_PREVIOUS_RESPONSE_ID",
    "input": "Сократи ответ до одного предложения",
    "background": false
}
JSON

{
  "id": "$F5AI_RESPONSE_ID",
  "object": "response",
  "status": "completed",
  "previous_response_id": "$F5AI_PREVIOUS_RESPONSE_ID",
  "model": "gpt-5-mini",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Согласовали сроки и ответственных."
        }
      ]
    }
  ],
  "error": null
}

Удалить ответ

DELETE /v2/responses/{response_id}

curl -X DELETE "https://app.f5ai.ru/v2/responses/$F5AI_RESPONSE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "66e8904a03f74e4d9a6b5678",
  "object": "response.deleted",
  "deleted": true
}

Жизненный цикл ответа

При создании ответ он сначала попадает в очередь (queued), затем обрабатывается (in_progress), и в конце переходит в один из терминальных статусов.

queued → in_progress → completed / incomplete / failed / cancelled

Совет: Используйте уникальный Idempotency-Key для бизнес-операции. Повтор с тем же ключом возвращает сохранённый Response вместо повторного запуска.

Вызов функций (Function Calling)

Внешняя функция выполняется вашим приложением. F5AI возвращает function_call, после чего клиент создаёт новый Response с function_call_output.

{
  "model": "gpt-5-mini",
  "conversation": "$F5AI_CONVERSATION_ID",
  "input": "Проверь статус клиента 42",
  "tools": [
    {
      "type": "function",
      "name": "lookup_customer",
      "description": "Возвращает клиента по ID",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          }
        },
        "required": ["id"]
      }
    }
  ],
  "background": false
}

Если модели нужны данные, в output появится элемент function_call.

{
  "type": "function_call",
  "call_id": "call_1",
  "name": "lookup_customer",
  "arguments": "{\"id\":42}",
  "status": "completed"
}

Выполните функцию на своей стороне и создайте новый Response с результатом.

curl -X POST "https://app.f5ai.ru/v2/responses" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<JSON
{
  "model": "gpt-5-mini",
  "conversation": "$F5AI_CONVERSATION_ID",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_1",
      "output": "{\"id\":42,\"name\":\"Иван\"}"
    }
  ],
  "background": false
}
JSON

Для продолжения без Conversation вместо поля conversation передайте previous_response_id.

{
  "model": "gpt-5-mini",
  "previous_response_id": "$F5AI_PREVIOUS_RESPONSE_ID",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_1",
      "output": "{\"id\":42,\"name\":\"Иван\"}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "lookup_customer",
      "parameters": { "type": "object" }
    }
  ]
}

Важно: не доверяйте arguments без проверки типов, прав доступа и бизнес-правил на стороне вашей системы.

Поиск по файлам (Local file search)

F5AI выполняет поиск локально по существующим Storage и передаёт модели найденные фрагменты. Для Responses используются числовые F5AI storage IDs.

{
  "model": "gpt-5-mini",
  "conversation": "$F5AI_CONVERSATION_ID",
  "input": "Какие условия возврата указаны в базе знаний?",
  "tools": [
    {
      "type": "file_search",
      "max_num_results": 5
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": [17]
    }
  },
  "background": false
}

Поле	Обязательное	Тип	Описание
`tools[].type`	Да	string	Для поиска всегда `file_search`.
`tools[].max_num_results`	Нет	integer	Максимум результатов: от 1 до 50; по умолчанию 5.
`tool_resources.file_search.vector_store_ids`	Да	array<integer>	ID созданных в F5AI векторных хранилищ.

Примечание: это интеграция с существующим локальным Storage F5AI, а не обещание готовности публичного CRUD /v2/vector_stores.

MCP-инструменты (Remote MCP)

MCP (Model Context Protocol) позволяет подключать к модели внешние серверы с инструментами. F5AI связывается с вашим MCP-сервером, получает список доступных функций и выполняет их по требованию модели.

{
  "model": "gpt-5-mini",
  "input": "Получить данные клиента 42 из CRM",
  "background": false,
  "tools": [
    {
      "type": "mcp",
      "server_label": "crm",
      "server_url": "https://mcp.example.com/mcp",
      "authorization": "",
      "allowed_tools": ["get-customer"],
      "require_approval": "never"
    }
  ],
  "tool_choice": {
    "type": "mcp",
    "server_label": "crm"
  }
}

Поле	Обязательное	Тип	Описание
`server_label`	Да	string	Уникальная метка сервера в пределах запроса.
`server_url`	Да	HTTPS URL	Адрес вашего MCP-сервера.
`authorization`	Нет	string	Токен авторизации (без префикса Bearer).
`allowed_tools`	Нет	array	Список имён функций, которые разрешено вызывать.
`require_approval`	Да	never	Единственный поддерживаемый режим MVP.
`headers`	Нет	object	Дополнительные заголовки.

Безопасность: MCP должен быть активирован администратором F5AI. Убедитесь, что ваш MCP-сервер защищён, а токены не попадают в логи или метаданные.

Вебхуки (Webhooks)

Укажите webhook_url в метаданных Response. Когда ответ перейдёт в финальное состояние, F5AI отправит POST-запрос на ваш URL.

{
  "model": "gpt-5-mini",
  "conversation": "$F5AI_CONVERSATION_ID",
  "input": "Подготовь ответ клиенту",
  "metadata": {
    "webhook_url": "https://client.example.com/f5ai/webhook"
  }
}

Тело webhook-запроса:

Поле	Тип	Описание
`response_id`	string	ID завершившегося Response.
`conversation_id`	string	ID Conversation, если Response был с ней связан.
`status`	string	Финальный статус Response.
`status_at`	integer	Unix timestamp отправки уведомления.

Ограничения: текущая реализация не поддерживает подпись запросов и автоматические повторные попытки. Webhook не содержит полный ответ — для получения полных данных используйте GET /v2/responses/{response_id}.

Ассистенты (Assistants)

Ассистенты — это сохранённый набор настроек: модель, инструкции, инструменты и ресурсы. Новый Response подключает профиль через assistant_id.

Создать ассистента

POST /v2/assistants

curl -X POST "https://app.f5ai.ru/v2/assistants" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Помощник службы поддержки",
    "model": "gpt-5-mini",
    "temperature": 0.3,
    "instructions": "Отвечай кратко и вежливо на русском языке.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Возвращает статус заказа по номеру",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "integer"
              }
            },
            "required": ["order_id"]
          }
        }
      }
    ],
    "metadata": {
      "department": "support"
    }
  }'

Поле при создании	Обязательное	Тип	Описание
`model`	Да	string	Код модели.
`name`	Да	string 1–256	Название профиля.
`description`	Нет	string ≤ 512	Краткое описание.
`instructions`	Нет	string ≤ 256000	Системные инструкции.
`reasoning_effort`	Нет	low/medium/high	Уровень рассуждений по умолчанию.
`temperature`	Да	number 0–2	Температура по умолчанию.
`tools`	Нет	array	Инструменты (function, file_search, code_interpreter).
`tool_resources`	Нет	object	Ресурсы для инструментов (например, ID файлов).
`metadata`	Нет	object	До 16 пар ключ-значение.

Список ассистентов

GET /v2/assistants

curl "https://app.f5ai.ru/v2/assistants?limit=20&order=desc" \
  -H "X-Auth-Token: $F5AI_API_KEY"

[
  {
    "id": 123,
    "name": "Помощник службы поддержки",
    "model": "gpt-5-mini",
    "vendor": "openai"
  }
]

Получить ассистента

GET /v2/assistants/{assistant_id}

curl "https://app.f5ai.ru/v2/assistants/$F5AI_ASSISTANT_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Обновить ассистента

POST /v2/assistants/{assistant_id} — все поля обязательны (полная замена).

curl -X POST "https://app.f5ai.ru/v2/assistants/$F5AI_ASSISTANT_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Помощник службы поддержки",
    "model": "gpt-5-mini",
    "temperature": 0.2,
    "instructions": "Отвечай кратко, вежливо и только на русском языке.",
    "tools": [],
    "metadata": {
      "department": "support"
    }
  }'

При обновлении помощника все поля, включая model и name, обязательны — это полная замена, а не частичное обновление.

Удалить ассистента

DELETE /v2/assistants/{assistant_id}

curl -X DELETE "https://app.f5ai.ru/v2/assistants/$F5AI_ASSISTANT_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": 123,
  "deleted": true
}

Модели и поставщики (Models & Vendors)

F5AI агрегирует модели от разных поставщиков. Чтобы узнать, какие модели доступны в данный момент, используйте эти эндпоинты. Не зашивайте коды моделей в коде — они могут меняться.

Список всех моделей

GET /v2/models?type=llm

curl "https://app.f5ai.ru/v2/models?type=llm" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "code": "gpt-5-mini",
  "name": "GPT-5 mini",
  "available": true,
  "vendor": "openai",
  "type": "llm",
  "vision": true,
  "streaming": true,
  "function_calling": true,
  "structured_outputs": true,
  "max_output": 128000,
  "context_window": 400000,
  "default": false,
  "web_visible": true,
  "protocols": ["responses", "chat_completions"]
}

Информация о модели

GET /v2/models/{model_code}

curl "https://app.f5ai.ru/v2/models/gpt-5-mini" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Цены на модели

GET /v2/models/prices

curl "https://app.f5ai.ru/v2/models/prices?type=llm" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "gpt-5-mini": {
    "unit": "tokens",
    "count": 1000,
    "input": 0.25,
    "output": 2
  }
}

Список поставщиков

GET /v2/vendors

curl "https://app.f5ai.ru/v2/vendors?type=llm" \
  -H "X-Auth-Token: $F5AI_API_KEY"

[
  {
    "code": "openai",
    "name": "OpenAI",
    "available": true,
    "model_types": ["llm", "tts", "stt", "tti", "embed"]
  }
]

Информация о поставщике

GET /v2/vendors/{vendor_code}

curl "https://app.f5ai.ru/v2/vendors/openai" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Модели конкретного поставщика

GET /v2/vendors/{vendor_code}/models

curl "https://app.f5ai.ru/v2/vendors/openai/models?type=llm" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Вы можете отфильтровать модели по типу с помощью параметра type: llm, tts, stt, tti, ttv, embed. Vendors не поддерживает ttv.

Векторные представления (Embeddings)

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

Создать embedding

POST /v2/embeddings

curl -X POST "https://app.f5ai.ru/v2/embeddings" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Текст для векторизации"
  }'

Поле тела	Обязательное	Тип	Описание
`model`	Да	string	Код embedding-модели.
`input`	Да	string	Текст для векторизации. Пока только одна строка (массив не поддерживается).

{
  "embedding": [0.012, -0.045, 0.008, ...],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Аудио (Audio)

Синтез речи (TTS)

POST /v2/audio/speech — возвращает MP3-файл.

curl -X POST "https://app.f5ai.ru/v2/audio/speech" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tts-1",
    "voice": "alloy",
    "text": "Здравствуйте! Ваш заказ уже передан в доставку."
  }' \
  --output speech.mp3

Поле	Обязательное	Тип	Описание
`model`	Да	string	Код доступной модели синтеза речи.
`voice`	Да	string	Голос, поддерживаемый выбранной моделью.
`text`	Да	string	Текст для озвучивания.

Распознавание речи (STT)

POST /v2/audio/transcription — принимает multipart/form-data.

curl -X POST "https://app.f5ai.ru/v2/audio/transcription" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  --form 'file=@./meeting.mp3' \
  --form 'model=whisper-1' \
  --form 'language=ru'

Поле формы	Обязательное	Тип	Описание
`file`	Да	file	Аудио- или видеофайл. Поддерживаются flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm.
`model`	Да	string	Код доступной модели транскрибации.
`language`	Нет	string	Язык аудиозаписи. Если не передан, значение определяет провайдер.
`prompt`	Нет	string	Подсказка для распознавания; используется асинхронными моделями.
`beam_size`	Нет	integer	Параметр распознавания для асинхронных моделей.
`source`	Нет	string	Источник записи, до 64 символов.
`callback_url`	Нет	string	URL клиентского webhook для асинхронной транскрибации.
`meta`	Нет	object	Пользовательские метаданные асинхронной задачи.

Синхронная модель возвращает JSON с текстом, сегментами и стоимостью. Асинхронная модель возвращает request_id и status.

{
  "text": "Добрый день. Обсудим план работ на следующую неделю.",
  "language": "ru",
  "duration": 123.45,
  "segments": [
    {
      "text": "Добрый день.",
      "start": 0,
      "end": 1250,
      "speaker_id": 1
    }
  ],
  "usage": {
    "cost": 61.725
  }
}

{
  "request_id": "a1b2c3d4-e5f6-7890",
  "status": "queued"
}

Для асинхронной используйте GET /v2/audio/transcription/check/{request_id} и GET /v2/audio/transcription/result/{request_id}.

curl "https://app.f5ai.ru/v2/audio/transcription/check/$F5AI_TRANSCRIPTION_REQUEST_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "request_id": "a1b2c3d4-e5f6-7890",
  "status": "processing"
}

curl "https://app.f5ai.ru/v2/audio/transcription/result/$F5AI_TRANSCRIPTION_REQUEST_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "meta": {
    "client_request_id": "meeting-2026-08-14"
  },
  "text": "Добрый день. Обсудим план работ на следующую неделю.",
  "language": "ru",
  "duration": 123.45,
  "segments": [
    {
      "text": "Добрый день.",
      "start": 0,
      "end": 1250,
      "speaker_id": 1
    }
  ],
  "usage": {
    "cost": 61.725
  }
}

Разрешённые расширения: flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm.

Баланс и транзакции (Account)

Текущий баланс

GET /v2/organization/balance

curl "https://app.f5ai.ru/v2/organization/balance" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{ "balance": 1250.5 }

История транзакций

GET /v2/organization/transactions?limit=20

curl "https://app.f5ai.ru/v2/organization/transactions?limit=20" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Query-параметр	Обязательное	Тип	Ограничения	Описание
`limit`	Да	integer	От 1 до 200	Максимальное число транзакций в ответе.
`after_id`	Нет	string	ID транзакции	Cursor для следующей страницы.

{
  "transactions": [
    {
      "id": "66e8904a03f74e4d9a6b7777",
      "type": "debit",
      "amount": 200,
      "currency": "RUB",
      "metadata": {
        "source": "api",
        "vendor": "openai",
        "model": "gpt-5-mini",
        "service": "crm"
      },
      "usage": {
        "prompt_tokens": 18,
        "completion_tokens": 10,
        "total_tokens": 28
      },
      "created_at": "2025-08-29T09:00:00+00:00"
    }
  ]
}

Устаревшие API (Legacy API)

Эти эндпоинты оставлены для поддержки уже работающих интеграций. Для новых проектов настоятельно рекомендуется использовать новый стек (Conversations, Responses). Новые функции и инструменты добавляются только в новый API.

Legacy Backward compatibility

Threads

POST /v2/threads — создать Thread

curl -X POST "https://app.f5ai.ru/v2/threads" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "external_dialog_id": "dialog-42"
    },
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Здравствуйте"
          }
        ]
      }
    ]
  }'

{
  "id": "66e8904a03f74e4d9a6b1234",
  "metadata": {
    "external_dialog_id": "dialog-42"
  },
  "tool_resources": null
}

GET /v2/threads/{thread_id} — получить Thread

curl "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

POST /v2/threads/{thread_id} — обновить Thread

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{"external_dialog_id":"dialog-42","status":"closed"}}'

DELETE /v2/threads/{thread_id} — удалить Thread

curl -X DELETE "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

{
  "id": "$F5AI_THREAD_ID",
  "deleted": true
}

Thread Messages

POST /v2/threads/{thread_id}/messages — добавить сообщение

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/messages" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "user",
    "content": "Какие условия возврата товара?"
  }'

{
  "id": "$F5AI_MESSAGE_ID",
  "thread_id": "$F5AI_THREAD_ID",
  "role": "user",
  "status": "completed",
  "content": "Какие условия возврата товара?"
}

GET /v2/threads/{thread_id}/messages — список сообщений

curl "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/messages?limit=20&order=desc" \
  -H "X-Auth-Token: $F5AI_API_KEY"

GET /v2/threads/{thread_id}/messages/{message_id} — получить сообщение

curl "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/messages/$F5AI_MESSAGE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

POST /v2/threads/{thread_id}/messages/{message_id} — обновить метаданные сообщения

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/messages/$F5AI_MESSAGE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"metadata": {"tag": "important"}}'

DELETE /v2/threads/{thread_id}/messages/{message_id} — удалить сообщение

curl -X DELETE "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/messages/$F5AI_MESSAGE_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

Массовые операции: POST /v2/threads/{thread_id}/messages/bulk-create и DELETE /v2/threads/{thread_id}/messages/bulk-delete.

Thread Runs

POST /v2/threads/{thread_id}/runs — запустить Assistant

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "assistant_id": 123,
    "additional_instructions": "Отвечай не длиннее трёх предложений.",
    "message_limit": 20
  }'

{
  "id": "$F5AI_RUN_ID",
  "thread_id": "$F5AI_THREAD_ID",
  "assistant_id": 123,
  "status": "queued",
  "model": "gpt-5-mini",
  "required_action": null,
  "usage": null
}

GET /v2/threads/{thread_id}/runs — список Runs

curl "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs" \
  -H "X-Auth-Token: $F5AI_API_KEY"

GET /v2/threads/{thread_id}/runs/{run_id} — получить Run

curl "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs/$F5AI_RUN_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY"

POST /v2/threads/{thread_id}/runs/{run_id} — обновить метаданные Run

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs/$F5AI_RUN_ID" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"metadata": {"priority": "high"}}'

POST /v2/threads/{thread_id}/runs/{run_id}/cancel — отменить Run

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs/$F5AI_RUN_ID/cancel" \
  -H "X-Auth-Token: $F5AI_API_KEY"

POST /v2/threads/{thread_id}/runs/{run_id}/submit_tool_outputs — передать результат внешнего tool

curl -X POST "https://app.f5ai.ru/v2/threads/$F5AI_THREAD_ID/runs/$F5AI_RUN_ID/submit_tool_outputs" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_1",
        "output": "{\"order_id\":42,\"status\":\"delivered\"}"
      }
    ]
  }'

POST /v2/threads/runs — создать Thread и Run одним запросом

curl -X POST "https://app.f5ai.ru/v2/threads/runs" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "assistant_id": 123,
    "thread": {
      "messages": [
        {"role": "user", "content": "Привет"}
      ]
    }
  }'

Chat Completions

POST /v2/chat/completions — синхронный чат (legacy)

curl -X POST "https://app.f5ai.ru/v2/chat/completions" \
  -H "X-Auth-Token: $F5AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {
        "role": "user",
        "content": "Кратко расскажи, что такое F5AI."
      }
    ],
    "temperature": 0.3
  }'

Поле	Обязательное	Тип	Описание
`model`	Да	string	Код доступной chat-модели.
`messages`	Да	array	Массив сообщений с полями `role` и `content`. Минимум одно сообщение.
`instructions`	Нет	string	Системные инструкции.
`max_tokens`	Нет	integer	Лимит выходных токенов.
`temperature`	Нет	number	От 0 до 2.
`tools`	Нет	array	Function, file search или code interpreter tools.

{
  "created": 1753794000,
  "model": "gpt-5-mini",
  "message": {
    "role": "assistant",
    "content": "F5AI — платформа для работы с AI-моделями через единый API."
  },
  "tools_calls": [],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 15,
    "total_tokens": 27,
    "cost": 1
  },
  "finish_reason": "stop"
}