n8n

n8n is a workflow automation tool. SpicyAPI gives it image, video, audio and chat models behind one API and one prepaid balance. There are three ways to connect them, and they can be mixed in one workflow:

All three use the same account, key, models and prices. For media, the node and HTTP Request templates check the request price before submission. Replaying the same accepted media request with its original Idempotency-Key returns the existing task.

For a starting image workflow, see the n8n NSFW image workflow guide: it covers model selection, reference editing, a first portrait and example costs. Use the steps below to connect it to your n8n instance.

Before you start

• An API key. Create one in the console; it starts with sk-spicy-. See Account setup if you do not have an account yet.
• A balance. Add funds in console Billing before your first generation. Your n8n workflows, Studio and API use the same account balance. See Billing for how charges are settled.
• One key per automation. Workflows can run far more often than a person clicks. Create a separate key for n8n and set a daily or monthly spend cap on it, so a mistake in a loop has a ceiling. See Authentication.
• n8n can reach api.spicyapi.ai. The calls are made by the n8n server, not by your browser.

Option 1: the SpicyAPI community node

The node is open source (MIT) at github.com/spicyapi-ai/n8n-nodes-spicyapi and published on npm as @spicyapi/n8n-nodes-spicyapi. It has no runtime dependencies and talks only to api.spicyapi.ai.

Other npm packages have similar names but belong to unrelated services. This one is the package named @spicyapi/n8n-nodes-spicyapi, and its credential is called SpicyAPI (spicyapi.ai) API.

Install

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

Operations

Generate images, video and audio

The three Generate operations share the same fields:

1. Model. Pick from the list, which shows the models for the selected resource with their starting price, or enter a model ID by hand. Every model and its parameters are listed at spicyapi.ai/models.
2. Prompt. The model's main text input. For speech models this is the text to speak. Leave it empty for models that have no prompt, such as upscalers.
3. Media Inputs. Images, videos or audio that the model reads. Pick the field (the list shows the selected model's file inputs), then use a binary field from the previous node or a URL. Binary files are uploaded to SpicyAPI automatically. Add several inputs for the same field to fill list fields such as reference images.
4. Model Parameters. A form generated from the selected model's schema: aspect ratio, resolution, duration, seed and so on. Fields you leave empty are not sent, so the model uses its own default.
5. Additional Parameters (JSON). Any other input fields as a JSON object. They override the fields above.

The output contains the task record (taskId, state, cost, settled, output). With Download Output on, which is the default, the files are also attached as binary data in data, data_1 and so on. The links in output.assets[].url expire after about 20 minutes; the binary copies do not.

Large videos are held in memory unless n8n stores binary data on disk. On self-hosted n8n, set N8N_DEFAULT_BINARY_DATA_MODE=filesystem when you work with video.

Cost control and retries

• Every item is priced first. The node asks for a quote. If the quote is above Max Cost per Item (USD), which defaults to $2, it stops with an error before anything is created, and nothing is charged. Set the limit to 0 to remove it.
• The task is created with the quoted price. If the price changes between the quote and the submission, the node quotes again, checks the limit again and resubmits.
• Retries do not charge twice. See Cost limits and retries.

Long-running tasks

See Long-running video tasks for the options and when to use each one.

Option 2: HTTP Request templates

Two importable workflows use only built-in n8n nodes, so they run on self-hosted n8n and on n8n Cloud, with no community node. They are in the examples folder of the node's repository.

How the image template is built

The same steps work for any media model, so you can copy the pattern into your own workflow.

The request and response shapes are in Tasks, Quotes and compatibility and Media inputs and outputs. Files that a model reads, such as a start image, can be a public URL or an uploaded spicy:// file.

Option 3: chat models in AI Agent and other AI nodes

SpicyAPI's chat endpoint is OpenAI-compatible, so n8n's own OpenAI nodes can use it. You do not need the community node for this, and it works on n8n Cloud.

https://api.spicyapi.ai/v1

Things to know:

• The model list includes image and video models. With a custom Base URL n8n shows everything /v1/models returns, and SpicyAPI's list covers all its models. Pick one that ends in /chat, or type the ID in expression mode. Image and video models are not chat models and will fail in an agent.
• Use Responses API. Recent versions of the OpenAI Chat Model node can send requests to /v1/responses instead of /v1/chat/completions. SpicyAPI supports /v1/responses, but not previous_response_id. If an agent request fails with the Responses API on, turn Use Responses API off in the node.
• Sampling settings. If you set an option the model does not declare, such as temperature on a reasoning model, SpicyAPI ignores it instead of failing and lists the ignored names in the X-Spicy-Ignored-Params response header; a value outside the model's range is changed to the nearest accepted one and listed in X-Spicy-Adjusted-Params. Other undeclared fields still return 400.
• Tools and JSON output depend on the model. Check the supported_parameters of the model in /v1/models.
• Reasoning models count reasoning tokens toward max_tokens. With a very small value, such as 20, a reasoning model can spend the whole budget thinking and return no text (upstream_failed: "the output budget was spent on reasoning"). Raise max_tokens or lower reasoning_effort. The values for reasoning_effort differ per model.
• Streaming and cost. Chat is billed by tokens after the call. The text and streaming page has the details, and Chat recipes has request examples.

Cost limits and retries

Limits on spending

• Use a separate key for n8n with a daily or monthly spend cap in the console, and a model allowlist if the workflow only needs a few models. When a cap is reached the call fails with 40202 and nothing is charged for it.
• For media models, quote first. The node does this for you; the templates do it with the Get Quote and If nodes. The quote is the exact price of that request, including extras such as per-reference-image charges, so a price check based on a quote is reliable and one based on the catalogue table is not.
• Ordinary failed tasks and expired tasks release the full hold. Certain content refusals are charged only when the model page explicitly says so. Read settled and cost for the final charge; see Billing.

Why a retry does not charge twice

Every task-creating call carries an Idempotency-Key. If the same key arrives again with the same request, SpicyAPI returns the task it already created instead of creating a second one, so no second hold or charge happens. This matters in n8n because a request can be sent twice without you doing anything: Retry On Fail on a node, or a timeout where the first request actually went through.

• The community node builds the key from the execution, the node, the item and its input. A node retry reuses the same key. A new execution, a changed input or another pass through a loop is new work and gets a new key.
• The templates build it from the execution ID and the item index, for example n8n-<execution id>-<item index>. If you copy the pattern into a loop, add the loop counter to the key, or every pass will return the first pass's task.
• Do not use a random value that changes on every attempt, such as $now: it makes every retry look like new work.

More in Idempotency.

Long-running video tasks

Image and audio models usually finish within one request. Video can take minutes. You have three ways to deal with that, from simplest to lightest on n8n:

If the node stops waiting, the task keeps running on SpicyAPI and is charged if it succeeds. Fetch it later with Task > Get; do not submit it again. You can also find it under Logs in the console.

Results are kept for a limited time and download links last about 20 minutes. Save the files in the workflow, for example to cloud storage, if you need them for longer. See Retention.

Troubleshooting

Errors from SpicyAPI end with a request_id or a task ID. Quote it to support and the request can be found exactly. Error codes are explained in Errors, and there is a wider checklist in Troubleshooting.

Use of the models is subject to the SpicyAPI terms and to the terms of the n8n edition you run.