n8n Automation: подключение SpeShu.AI к workflow

n8n — визуальный конструктор автоматизаций: триггер запускает цепочку узлов, а узлы между собой передают данные. В связке с AI-узлами n8n работает как агентный пайплайн — вызов модели, разбор ответа, вызов инструментов, запись результата в CRM, таблицу или мессенджер — и всё это в одном редактируемом графе. SpeShu.AI подключается к такому графу через стандартный OpenAI-совместимый путь: меняется только базовый адрес и ключ.

От n8n нужны ровно две вещи: base_url = "https://speshu.ai/api/v1" и API-ключ в Authorization: Bearer. Больше ничего менять не нужно — n8n говорит с /chat/completions обычным OpenAI-совместимым запросом. Ключ создаётся на speshu.ai/profile.

Установка

n8n работает в двух видах: облачный n8n Cloud и self-hosted. Дальше по странице подразумевается self-hosted — только у него есть переменные окружения.

cURL

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_HOST=localhost \
  -e N8N_PORT=5678 \
  -e WEBHOOK_URL=http://localhost:5678/ \
  -v n8n_data:/home/node/.n8n \
  -e SPESHU_API_KEY="sk-ваш-ключ" \
  n8nio/n8n

Редактор откроется на http://localhost:5678. Разбор установки n8n целиком — в документации n8n.

Переменная SPESHU_API_KEY попадает в контейнер, но не в базу n8n. Если вы предпочитаете править credentials вручную, объявите её на хосте и подставьте при запуске — так ключ не останется в слое образа.

Конфигурация

Шаг 1 — идентификатор модели

Идентификатор текстовой модели берётся из каталога GET /api/v1/models и кладётся в переменную окружения. Зашивать его в код нельзя: состав каталога меняется, а зашитый в конфиг идентификатор начинает падать с 404 model_not_found без предупреждения.

cURL

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')

export MEDIA_MODEL=$(curl -s https://speshu.ai/api/v1/media/models \
  | jq -r '.data[] | select(.media_type == "image") | .id' | head -1)

Обе переменные передайте в контейнер через -e или запишите в .env рядом с ним. Дальше они используются только как $env.SPESHU_MODEL и $env.MEDIA_MODEL.

В n8n Cloud переменных окружения нет — там то же самое делается через Settings → Variables, а в выражениях пишется $vars.SPESHU_MODEL. На self-hosted доступ $env в выражениях регулируется флагом N8N_BLOCK_ENV_ACCESS_IN_NODE; при значении true переменные в выражениях не читаются, и тогда идентификатор модели задают прямо в узле.

Шаг 2 — credentials

Создайте credentials типа OpenAI account:

Поле	Значение
API key	`={{ $env.SPESHU_API_KEY }}`
Base URL	`https://speshu.ai/api/v1`
Organization ID	пусто
Time Out	600

Ключ внедряйте через {{ }} — тогда он не хранится открытым текстом в самой записи credentials, а подставляется из окружения при выполнении.

Поле Base URL есть не во всех сборках n8n. В версиях, где его нет, узел пойдёт на api.openai.com. Проверьте его наличие сразу после создания credentials; если поля нет, работайте через узел HTTP Request, где адрес задаётся явно в поле URL.

Адрес пишите без завершающего слэша: https://speshu.ai/api/v1. Со слэшем на конце n8n склеит его с /chat/completions и получит двойной разделитель, на котором сервер отвечает 404 — при том, что ключ и модель верные.

Первый работающий пример

Соберите три узла: Webhook → AI Agent → Respond to Webhook.

Триггер

Узел Webhook, метод POST, путь /support. Он отдаёт тело запроса в $json.body, а не в $json напрямую — обычное отличие n8n от REST-фреймворков.

Модель

В узле AI Agent добавьте под-узел OpenAI Chat Model:

Поле	Значение
Credential	созданные выше credentials
Model	`={{ $env.SPESHU_MODEL }}`
Temperature	0.2
Options → Response Format	оставьте пустым

Если ваша версия n8n загружает список моделей по адресу из credentials, выпадающий список моделей заполнится сам из GET /api/v1/models — можно выбрать нужную оттуда. Это надёжнее, чем вписывать идентификатор руками.

Промпт

Поле Prompt агента — выражение:

Ты ассистент службы поддержки.
Ответь клиенту кратко и предложи следующий шаг.

Сообщение клиента: {{ $json.body.message }}

Маркер {{ }} в поле вставляется как Expression — тип поля переключается переключателем слева, а не вводом текста вместе с фигурными скобками.

Запустите Execute Workflow и отправьте тестовый запрос:

cURL

curl -X POST http://localhost:5678/webhook/support \
  -H "Content-Type: application/json" \
  -d '{"message": "Не приходит подтверждение оплаты"}'

Ответ придёт текстом. Чтобы забрать из ответа ещё и списание, добавьте между агентом и вебхуком узел Code:

// Code, режим "Run Once for All Items"
const items = $input.all();

return items.map((item) => {
  const body = item.json ?? {};

  return {
    json: {
      reply: body.choices?.[0]?.message?.content ?? '',
      charged_rub: body.usage?.cost?.total_cost ?? null,
      finish_reason: body.choices?.[0]?.finish_reason ?? null,
    },
  };
});

usage.cost.total_cost — сумма, списанная с кошелька в рублях, в формате OpenAI-ответа. Подробности — в разделе Тарификация и оплата.

Дополнительные возможности

Инструменты агента

AI Agent вызывает инструменты через узлы Tools: Code Tool, HTTP Request Tool, Google Sheets Tool, подключённые к вашим сервисам. Схема каждого инструмента уходит в поле tools запроса, а выбранный инструмент возвращается в choices[0].message.tool_calls — это тот же протокол, что и в обычном чате. Полный цикл, разбор аргументов и обработка параллельных вызовов — в гайде Вызов функций.

Структурированный вывод

Под-узел Structured Output Parser в связке с параметром узла агента Format → Output Schema заставляет модель вернуть JSON по схеме. Формат совпадает с response_format вида json_schema, который поддерживает /chat/completions. Разбор того, что модель делает со схемой, и когда нужен парсер с починкой — в гайде Структурированный вывод.

Изображения во входе

Узел OpenAI Chat Model вместе с узлом AI Message умеет передавать изображение по ссылке — задайте у сообщения тип imageUrl и укажите публичный адрес файла. Так проще всего отдать в модель скриншот из CRM или аватар из таблицы. Требования к ссылке и все четыре типа блоков контента разобраны в гайде Медиаввод.

Генерация медиа

Медиа-API не OpenAI-совместимый, поэтому для него нужен явный вызов через узел HTTP Request. Создайте задачу:

Узел	Настройка
HTTP Request (создание)	Method `POST`, URL `https://speshu.ai/api/v1/async/media/tasks`, Authentication → Predefined Credential Type → Bearer token (те же credentials), Body → JSON
Header	`Idempotency-Key` = `={{ $execution.id }}` — уникально на каждое выполнение workflow
Code	достать идентификатор из конверта: `return [{ json: { taskId: $input.first().json.data.taskId } }]`
Wait	5 секунд
HTTP Request (опрос)	Method `GET`, URL `={{ $json.taskId }}` с префиксом `https://speshu.ai/api/v1/async/media/tasks/`, те же credentials
IF	условие `{{ $json.data.state }}` равно `"success"` — иначе возвращайтесь в Wait

Точный состав запроса и формат конверта:

cURL

curl -s https://speshu.ai/api/v1/async/media/tasks \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "'"$MEDIA_MODEL"'",
    "input": { "prompt": "Кот в смокинге, студийный свет" }
  }'

Деньги списываются при создании задачи, а не при успешном результате. В цикле опроса привязывайте Idempotency-Key к одному выполнению workflow — иначе повтор создаст вторую задачу и спишет дважды. Формат конверта, статусы и скачивание файла — в разделе Создать задачу.

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

AI-узлы n8n ждут полного ответа и отдают его в следующий узел целиком — инкрементального вывода в редакторе не будет. Потоковая передача пригодится, если вы вызываете /chat/completions напрямую из узла HTTP Request и хотите отдавать текст в собственный интерфейс по мере генерации. Учтите, что сервер не пишет поле event: и заканчивает поток строкой data: [DONE] — клиент, который разбирает SSE по event:, покажет пустой результат. Формат кадров и кадр со списанием — в гайде Потоковая передача.

Про векторный поиск

SpeShu.AI не отдаёт эмбеддинги: эндпоинта /embeddings в API нет. Если вы добавили в workflow узлы Embeddings OpenAI или vector store, они будут обращаться к адресу из credentials и не найдут эндпоинта. Заменить его нечем — векторный шаг нужно увести на другого провайдера.

Два честных варианта. Вариант A — отдельный провайдер эмбеддингов. Создайте вторые credentials типа OpenAI account с адресом и ключом другого сервиса и укажите их только в узлах эмбеддингов и векторного хранилища. Генерация остаётся на SpeShu.AI.

Переменная	Что в ней
`SPESHU_API_KEY`	генерация — этот ключ
`SPESHU_BASE_URL`	генерация — `https://speshu.ai/api/v1`
`EMBEDDINGS_BASE_URL`	отдельный провайдер, не SpeShu.AI
`EMBEDDINGS_API_KEY`	отдельный провайдер, не SpeShu.AI
`EMBEDDINGS_MODEL`	отдельный провайдер, не SpeShu.AI

cURL

# генерация — SpeShu.AI
SPESHU_API_KEY="sk-ваш-ключ"
SPESHU_BASE_URL="https://speshu.ai/api/v1"
SPESHU_MODEL="<идентификатор из GET /api/v1/models>"

# эмбеддинги — другой сервис, отдельные значения
EMBEDDINGS_BASE_URL="https://<другой-провайдер>/v1"
EMBEDDINGS_API_KEY="<ключ-другого-провайдера>"
EMBEDDINGS_MODEL="<модель-эмбеддингов-того-провайдера>"

Расход за два сервиса считается раздельно: в workflow полезно положить узел Code, который берёт usage.cost.total_cost из ответа генерации, и векторному шагу добавить свою метку с соответствующего сервиса. Вариант B — без эмбеддингов. Уберите узлы эмбеддингов и vector store и соберите обычный пайплайн: узел HTTP Request или Postgres отдаёт релевантные строки по обычным условиям, AI Agent отвечает на их основе, результат уходит дальше по графу. Для коротких баз знаний и структурированных таблиц этого обычно хватает, и весь расход остаётся в одном месте.

Частые проблемы

404 на запросе, хотя ключ и модель верны

Проверьте адрес в credentials: без завершающего слэша и без потерянного /v1. https://speshu.ai/api и https://speshu.ai/api/v1/ — обе частые причины, обе дают 404. Подробнее — в разделе Введение в API.

401 invalid_api_key на первом же выполнении

Ключ не подставился: в поле credentials стоит $env.SPESHU_API_KEY без обрамляющих {{ }}, либо в контейнер не передан SPESHU_API_KEY через -e. Проверьте значение в логе узла и командой curl https://speshu.ai/api/v1/balance -H "Authorization: Bearer $SPESHU_API_KEY".

404 model_not_found после обновления каталога

В узле модели зашит идентификатор, которого больше нет в GET /api/v1/models. Замените его на $env.SPESHU_MODEL и обновите переменную: без этого каждое выполнение workflow будет падать. Почему так — в разделе Модели и цены.

AI-узел молчит, а HTTP Request с теми же данными отвечает

Различия в двух местах. Первое: узел Webhook отдаёт тело в $json.body, а не в $json — выражение промпта на пустом объекте даёт пустой запрос. Второе: в узле AI Agent подключите под-узел модели именно к полю модели агента, а не оставляйте его висеть рядом отдельным узлом.

400 invalid_request на запросе с изображением

Выбранная модель не принимает зрение — такой запрос отвергается целиком, а не игнорируется. Возьмите другую модель из каталога. Разбор — в гайде Медиаввод.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Модели и цены

Как выбрать модель под задачу

Запрос чату

Поля запроса и формат ответа

Вызов функций

Как AI Agent вызывает инструменты

Создать задачу

Медиа-конверт и Idempotency-Key

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

n8n Automation: подключение SpeShu.AI к workflow

Установка

Конфигурация

Шаг 1 — идентификатор модели

Шаг 2 — credentials

Первый работающий пример

Дополнительные возможности

Инструменты агента

Структурированный вывод

Изображения во входе

Генерация медиа

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

Про векторный поиск

Частые проблемы

Что дальше

Модели и цены

Запрос чату

Вызов функций

Создать задачу

​Установка

​Конфигурация

​Шаг 1 — идентификатор модели

​Шаг 2 — credentials

​Первый работающий пример

​Дополнительные возможности

​Инструменты агента

​Структурированный вывод

​Изображения во входе

​Генерация медиа

​Потоковая передача

​Про векторный поиск

​Частые проблемы

​Что дальше

Модели и цены

Запрос чату

Вызов функций

Создать задачу

Установка

Конфигурация

Шаг 1 — идентификатор модели

Шаг 2 — credentials

Первый работающий пример

Дополнительные возможности

Инструменты агента

Структурированный вывод

Изображения во входе

Генерация медиа

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

Про векторный поиск

Частые проблемы

Что дальше