n8n

O n8n é uma ferramenta de automação de workflows. A SpicyAPI oferece a ele modelos de imagem, vídeo, áudio e chat por trás de uma única API e de um único saldo pré-pago. Há três formas de conectá-los, e elas podem ser combinadas em um mesmo workflow:

As três usam a mesma conta, chave, modelos e preços. Para mídia, o nó e os templates de HTTP Request verificam o preço antes de enviar a requisição. Reenviar a mesma requisição de mídia aceita com o Idempotency-Key original retorna a tarefa existente.

Para começar um workflow de imagens, veja o guia de workflows de imagens NSFW com n8n: escolha de modelos, edição com referência, primeiro retrato e exemplos de custo. As etapas abaixo conectam o workflow à sua instância do n8n.

Antes de começar

• Uma chave de API. Crie uma no console; ela começa com sk-spicy-. Veja Prepare sua conta se ainda não tem conta.
• Saldo. Adicione fundos em Billing no console antes da primeira geração. Seus workflows do n8n, Studio e API usam o mesmo saldo da conta. Veja Cobrança para entender a liquidação.
• Uma chave por automação. Workflows podem rodar bem mais vezes do que uma pessoa clica. Crie uma chave separada para o n8n e defina um limite de gasto diário ou mensal nela, para que um erro em um loop tenha um teto. Veja Autenticação.
• O n8n precisa alcançar api.spicyapi.ai. As chamadas são feitas pelo servidor do n8n, não pelo seu navegador.

Opção 1: o community node da SpicyAPI

O node é de código aberto (MIT) em github.com/spicyapi-ai/n8n-nodes-spicyapi e publicado no npm como @spicyapi/n8n-nodes-spicyapi. Ele não tem dependências em tempo de execução e se comunica apenas com api.spicyapi.ai.

Outros pacotes do npm têm nomes parecidos, mas pertencem a serviços sem relação. Este é o pacote chamado @spicyapi/n8n-nodes-spicyapi, e a credencial dele se chama SpicyAPI (spicyapi.ai) API.

Instalação

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

Operações

Gere imagens, vídeo e áudio

As três operações Generate compartilham os mesmos campos:

1. Model. Escolha na lista, que mostra os modelos do recurso selecionado com o preço inicial, ou informe um ID de modelo manualmente. Todos os modelos e seus parâmetros estão listados em spicyapi.ai/models.
2. Prompt. A principal entrada de texto do modelo. Para modelos de fala, é o texto a ser falado. Deixe vazio para modelos sem prompt, como os de ampliação.
3. Media Inputs. Imagens, vídeos ou áudio que o modelo lê. Escolha o campo (a lista mostra as entradas de arquivo do modelo selecionado) e use um campo binário do node anterior ou uma URL. Os arquivos binários são enviados à SpicyAPI automaticamente. Adicione várias entradas para o mesmo campo para preencher campos de lista, como imagens de referência.
4. Model Parameters. Um formulário gerado a partir do schema do modelo selecionado: proporção, resolução, duração, seed e assim por diante. Campos deixados vazios não são enviados, então o modelo usa o próprio padrão.
5. Additional Parameters (JSON). Quaisquer outros campos de entrada como um objeto JSON. Eles se sobrepõem aos campos acima.

A saída contém o registro da tarefa (taskId, state, cost, settled, output). Com Download Output ativado, que é o padrão, os arquivos também são anexados como dados binários em data, data_1 e assim por diante. Os links em output.assets[].url expiram após cerca de 20 minutos; as cópias binárias não.

Vídeos grandes ficam na memória, a menos que o n8n guarde dados binários em disco. No n8n auto-hospedado, defina N8N_DEFAULT_BINARY_DATA_MODE=filesystem quando trabalhar com vídeo.

Controle de custo e novas tentativas

• Cada item é cotado antes. O node pede uma cotação. Se ela passar de Max Cost per Item (USD), que por padrão é $2, ele para com um erro antes de criar qualquer coisa, e nada é cobrado. Defina o limite como 0 para removê-lo.
• A tarefa é criada com o preço cotado. Se o preço mudar entre a cotação e o envio, o node cota de novo, confere o limite de novo e reenvia.
• Novas tentativas não cobram duas vezes. Veja Limites de custo e novas tentativas.

Tarefas demoradas

Veja Tarefas de vídeo demoradas para as opções e quando usar cada uma.

Opção 2: templates de HTTP Request

Dois workflows importáveis usam apenas nodes nativos do n8n, então rodam no n8n auto-hospedado e no n8n Cloud, sem community node. Eles estão na pasta de exemplos do repositório do node.

Como o template de imagem é construído

Os mesmos passos servem para qualquer modelo de mídia, então você pode copiar o padrão para o seu próprio workflow.

Os formatos de requisição e resposta estão em Tarefas, Cotações e compatibilidade e Entradas e saídas de mídia. Arquivos que um modelo lê, como uma imagem inicial, podem ser uma URL pública ou um arquivo spicy:// enviado.

Opção 3: modelos de chat em AI Agent e outros nodes de IA

O endpoint de chat da SpicyAPI é compatível com OpenAI, então os nodes OpenAI do próprio n8n podem usá-lo. Você não precisa do community node para isso, e funciona no n8n Cloud.

https://api.spicyapi.ai/v1

O que você precisa saber:

• A lista de modelos inclui modelos de imagem e vídeo. Com uma Base URL personalizada, o n8n mostra tudo o que /v1/models retorna, e a lista da SpicyAPI cobre todos os modelos dela. Escolha um que termine em /chat ou digite o ID no modo de expressão. Modelos de imagem e vídeo não são modelos de chat e falham em um agente.
• Use Responses API. Versões recentes do node OpenAI Chat Model podem enviar requisições para /v1/responses em vez de /v1/chat/completions. A SpicyAPI suporta /v1/responses, mas não previous_response_id. Se uma requisição de agente falhar com a Responses API ativada, desative Use Responses API no node.
• Configurações de amostragem. Se você definir uma opção que o modelo não declara, como temperature em um modelo de raciocínio, a SpicyAPI a ignora em vez de falhar e lista os nomes ignorados no cabeçalho de resposta X-Spicy-Ignored-Params; um valor fora da faixa do modelo é trocado pelo valor aceito mais próximo e listado em X-Spicy-Adjusted-Params. Outros campos não declarados continuam retornando 400.
• Ferramentas e saída em JSON dependem do modelo. Confira o supported_parameters do modelo em /v1/models.
• Modelos de raciocínio contam os tokens de raciocínio no max_tokens. Com um valor muito pequeno, como 20, um modelo de raciocínio pode gastar todo o orçamento pensando e não devolver texto (upstream_failed: "the output budget was spent on reasoning"). Aumente max_tokens ou reduza reasoning_effort. Os valores de reasoning_effort variam por modelo.
• Streaming e custo. O chat é cobrado por tokens depois da chamada. A página Texto e streaming traz os detalhes, e Receitas de chat traz exemplos de requisição.

Limites de custo e novas tentativas

Limites de gasto

• Use uma chave separada para o n8n com um limite de gasto diário ou mensal no console e uma lista de modelos permitidos se o workflow precisar de apenas alguns modelos. Quando um limite é atingido, a chamada falha com 40202 e nada é cobrado por ela.
• Para modelos de mídia, cote primeiro. O node faz isso por você; os templates fazem com os nodes Get Quote e If. A cotação é o preço exato daquela requisição, incluindo extras como cobranças por imagem de referência, então uma checagem de preço baseada em uma cotação é confiável e uma baseada na tabela do catálogo não é.
• Falhas comuns e tarefas expiradas liberam toda a retenção. Algumas recusas de conteúdo só são cobradas quando a página do modelo informa isso explicitamente. Consulte settled e cost para o valor final; veja Cobrança.

Por que uma nova tentativa não cobra duas vezes

Toda chamada que cria tarefa leva um Idempotency-Key. Se a mesma chave chegar de novo com a mesma requisição, a SpicyAPI retorna a tarefa que já criou em vez de criar uma segunda, então não há segunda retenção nem segunda cobrança. Isso importa no n8n porque uma requisição pode ser enviada duas vezes sem você fazer nada: Retry On Fail em um node, ou um timeout em que a primeira requisição na verdade passou.

• O community node monta a chave a partir da execução, do node, do item e da entrada dele. Uma nova tentativa do node reutiliza a mesma chave. Uma nova execução, uma entrada alterada ou outra passagem por um loop é trabalho novo e recebe uma chave nova.
• Os templates a montam a partir do ID da execução e do índice do item, por exemplo n8n-<execution id>-<item index>. Se você copiar o padrão para um loop, adicione o contador do loop à chave; senão, cada passagem retorna a tarefa da primeira.
• Não use um valor aleatório que muda a cada tentativa, como $now: ele faz cada nova tentativa parecer trabalho novo.

Mais em Idempotência.

Tarefas de vídeo demoradas

Modelos de imagem e áudio costumam terminar em uma única requisição. Vídeo pode levar minutos. Há três formas de lidar com isso, da mais simples à mais leve para o n8n:

Se o node parar de esperar, a tarefa continua em execução na SpicyAPI e é cobrada se der certo. Busque-a depois com Task > Get; não a envie de novo. Você também a encontra em Logs no console.

Os resultados são mantidos por tempo limitado e os links de download duram cerca de 20 minutos. Salve os arquivos no workflow, por exemplo em um armazenamento na nuvem, se precisar deles por mais tempo. Veja Retenção e destruição.

Solução de problemas

Os erros da SpicyAPI terminam com um request_id ou um ID de tarefa. Informe-o ao suporte para que a requisição seja localizada com exatidão. Os códigos de erro estão explicados em Erros, e há uma lista de verificação mais ampla em Solução de problemas.

O uso dos modelos está sujeito aos termos da SpicyAPI e aos termos da edição do n8n que você executa.