n8n

n8n — инструмент автоматизации рабочих процессов. SpicyAPI даёт ему модели изображений, видео, звука и чата за одним API и одним предоплаченным балансом. Подключить их можно тремя способами, и в одном рабочем процессе их можно сочетать:

Во всех трёх случаях используются те же аккаунт, ключ, модели и цены. При генерации медиа узел и шаблоны HTTP Request проверяют цену перед отправкой. Повторная отправка того же принятого медиазапроса с исходным Idempotency-Key возвращает уже созданную задачу.

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

Перед началом

• API-ключ. Создайте его в консоли; он начинается с sk-spicy-. Если аккаунта ещё нет, см. Подготовка аккаунта.
• Баланс. Пополните счёт в разделе Billing консоли перед первой генерацией. Процессы n8n, Studio и API используют общий баланс аккаунта. Порядок расчёта описан в разделе Оплата.
• Один ключ на одну автоматизацию. Рабочие процессы могут запускаться гораздо чаще, чем человек нажимает кнопку. Создайте отдельный ключ для n8n и задайте для него суточный или месячный лимит расходов, чтобы у ошибки в цикле был потолок. См. Аутентификация.
• n8n должен иметь доступ к api.spicyapi.ai. Вызовы выполняет сервер n8n, а не ваш браузер.

Вариант 1: community-узел SpicyAPI

Узел имеет открытый исходный код (MIT): github.com/spicyapi-ai/n8n-nodes-spicyapi, опубликован в npm как @spicyapi/n8n-nodes-spicyapi. У него нет зависимостей времени выполнения, и он обращается только к api.spicyapi.ai.

Другие пакеты npm имеют похожие названия, но относятся к посторонним сервисам. Нужен именно пакет @spicyapi/n8n-nodes-spicyapi, а его учётные данные называются SpicyAPI (spicyapi.ai) API.

Установка

cd ~/.n8n/nodes
npm install @spicyapi/n8n-nodes-spicyapi

Операции

Создание изображений, видео и звука

Три операции Generate используют одни и те же поля:

1. Model. Выберите из списка, в котором показаны модели выбранного ресурса с начальной ценой, или введите идентификатор модели вручную. Все модели и их параметры перечислены на spicyapi.ai/models.
2. Prompt. Основной текстовый ввод модели. Для моделей речи это текст, который нужно произнести. Оставьте пустым для моделей без промпта, например для апскейлеров.
3. Media Inputs. Изображения, видео или звук, которые читает модель. Выберите поле (в списке показаны файловые входы выбранной модели), затем используйте бинарное поле из предыдущего узла или URL. Бинарные файлы загружаются в SpicyAPI автоматически. Добавьте несколько входов для одного и того же поля, чтобы заполнять списковые поля, например референсные изображения.
4. Model Parameters. Форма, сгенерированная по схеме выбранной модели: соотношение сторон, разрешение, длительность, seed и так далее. Поля, которые вы оставили пустыми, не отправляются, и модель использует своё значение по умолчанию.
5. Additional Parameters (JSON). Любые другие входные поля в виде JSON-объекта. Они переопределяют поля выше.

Вывод содержит запись задачи (taskId, state, cost, settled, output). При включённом Download Output (по умолчанию) файлы также прикрепляются как бинарные данные в data, data_1 и так далее. Ссылки в output.assets[].url действуют около 20 минут; бинарные копии не истекают.

Большие видео хранятся в памяти, если n8n не хранит бинарные данные на диске. В n8n на собственном сервере при работе с видео задайте N8N_DEFAULT_BINARY_DATA_MODE=filesystem.

Контроль стоимости и повторные попытки

• Каждый элемент сначала оценивается по цене. Узел запрашивает расчёт. Если он превышает Max Cost per Item (USD) (по умолчанию $2), узел останавливается с ошибкой до создания чего-либо, и ничего не списывается. Задайте лимит 0, чтобы снять его.
• Задача создаётся с рассчитанной ценой. Если цена изменилась между расчётом и отправкой, узел делает расчёт заново, снова проверяет лимит и отправляет повторно.
• Повторные попытки не списывают деньги дважды. См. Лимиты расходов и повторные попытки.

Долгие задачи

Варианты и случаи, когда использовать каждый из них, см. в разделе Долгие видеозадачи.

Вариант 2: шаблоны HTTP Request

Два импортируемых рабочих процесса используют только встроенные узлы n8n, поэтому работают в n8n на собственном сервере и в n8n Cloud без community-узла. Они находятся в папке с примерами репозитория узла.

Как устроен шаблон изображений

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

Форматы запросов и ответов описаны в разделах Tasks, Quotes and compatibility и Media inputs and outputs. Файлы, которые читает модель, например начальное изображение, могут быть публичным URL или загруженным файлом spicy://.

Вариант 3: чат-модели в AI Agent и других AI-узлах

Чат-эндпоинт SpicyAPI совместим с OpenAI, поэтому его могут использовать собственные узлы OpenAI в n8n. Для этого community-узел не нужен, и это работает в n8n Cloud.

https://api.spicyapi.ai/v1

Что нужно знать:

• В списке моделей есть модели изображений и видео. С пользовательским Base URL n8n показывает всё, что возвращает /v1/models, а список SpicyAPI охватывает все его модели. Выберите ту, что оканчивается на /chat, или введите ID в режиме выражения. Модели изображений и видео не являются чат-моделями и в агенте будут завершаться ошибкой.
• Use Responses API. Последние версии узла OpenAI Chat Model могут отправлять запросы на /v1/responses вместо /v1/chat/completions. SpicyAPI поддерживает /v1/responses, но не previous_response_id. Если запрос агента завершается ошибкой при включённом Responses API, выключите Use Responses API в узле.
• Настройки сэмплирования. Если вы зададите параметр, который модель не объявляет, например temperature для модели с рассуждением, SpicyAPI проигнорирует его вместо ошибки и перечислит проигнорированные имена в заголовке ответа X-Spicy-Ignored-Params; значение за пределами диапазона модели заменяется ближайшим допустимым и перечисляется в X-Spicy-Adjusted-Params. Другие необъявленные поля по-прежнему возвращают 400.
• Инструменты и вывод в JSON зависят от модели. Проверьте supported_parameters модели в /v1/models.
• Модели с рассуждением считают токены рассуждения в max_tokens. При очень маленьком значении, например 20, модель с рассуждением может потратить весь бюджет на размышления и не вернуть текст (upstream_failed: «the output budget was spent on reasoning»). Увеличьте max_tokens или снизьте reasoning_effort. Значения reasoning_effort у разных моделей различаются.
• Потоковая передача и стоимость. Чат тарифицируется по токенам после вызова. Подробности на странице Text and streaming, а примеры запросов — в Chat recipes.

Лимиты расходов и повторные попытки

Ограничение расходов

• Используйте отдельный ключ для n8n с суточным или месячным лимитом расходов в консоли и списком разрешённых моделей, если рабочему процессу нужно лишь несколько моделей. Когда лимит достигнут, вызов завершается ошибкой 40202, и за него ничего не списывается.
• Для медиамоделей сначала делайте расчёт. Узел делает это за вас; шаблоны делают это узлами Get Quote и If. Расчёт — это точная цена именно этого запроса, включая дополнительные начисления вроде платы за каждое референсное изображение, поэтому проверка цены по расчёту надёжна, а по таблице каталога — нет.
• При обычном сбое или истечении срока задачи весь резерв освобождается. Некоторые отказы по содержимому оплачиваются только тогда, когда это прямо указано на странице модели. Итоговая сумма указана в settled и cost; см. Оплата.

Почему повторная попытка не списывает деньги дважды

Каждый вызов, создающий задачу, несёт Idempotency-Key. Если тот же ключ приходит снова с тем же запросом, SpicyAPI возвращает уже созданную задачу вместо создания второй, поэтому второго резерва или списания не происходит. В n8n это важно, потому что запрос может быть отправлен дважды без вашего участия: Retry On Fail на узле или тайм-аут, когда первый запрос на самом деле прошёл.

• Community-узел строит ключ из выполнения, узла, элемента и его входных данных. Повторная попытка узла использует тот же ключ. Новое выполнение, изменённые входные данные или другой проход цикла — это новая работа, и ей достаётся новый ключ.
• Шаблоны строят его из ID выполнения и индекса элемента, например n8n-<execution id>-<item index>. Если вы копируете этот шаблон в цикл, добавьте в ключ счётчик цикла, иначе каждый проход будет возвращать задачу первого прохода.
• Не используйте случайное значение, меняющееся при каждой попытке, например $now: из-за него каждая повторная попытка выглядит как новая работа.

Подробнее в разделе Идемпотентность.

Долгие видеозадачи

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

Если узел перестаёт ждать, задача продолжает выполняться в SpicyAPI и оплачивается, если завершится успешно. Заберите её позже через Task > Get; не отправляйте её заново. Её также можно найти в разделе Logs в консоли.

Результаты хранятся ограниченное время, а ссылки для скачивания действуют около 20 минут. Если файлы нужны дольше, сохраняйте их в рабочем процессе, например в облачном хранилище. См. Хранение и удаление данных.

Устранение неполадок

Ошибки SpicyAPI заканчиваются на request_id или идентификатор задачи. Сообщите его в поддержку, и запрос можно будет найти точно. Коды ошибок описаны в разделе Ошибки и повторы, а более широкий контрольный список — в Troubleshooting.

Использование моделей регулируется условиями SpicyAPI и условиями той редакции n8n, которую вы используете.