# n8n

> Connect n8n to MirAPI by pointing the OpenAI node at the MirAPI base URL, adding your key, and running chat workflows on deepseek-chat.

n8n is a workflow automation platform whose OpenAI node accepts a custom base URL in its credentials. Point that node at MirAPI and your chat workflows run on your MirAPI key and prepaid balance.

## What you need

| Element | Value |
|---|---|
| Base URL | `https://api.mirapi.ai/v1` |
| API key | Your MirAPI key (`sk-...`) |
| Model | `deepseek-chat` |
| Protocol | OpenAI-compatible (`/v1`) |

## Configure

1. Create a MirAPI key in https://console.mirapi.ai → **API Keys** and copy it (it is shown only once).
2. In n8n, create **OpenAI credentials** (Credentials → New → OpenAI) and set the **Base URL** and **API Key**:

```text
Base URL: https://api.mirapi.ai/v1
API Key:  sk-...
```

3. Add an **OpenAI → Chat Model** node and set its **Model** to `deepseek-chat`.

:::note
Keep `/v1` in the base URL — n8n appends the request path (`/chat/completions`) itself.
:::

## Verify with a workflow

Build a minimal workflow: **Webhook → OpenAI Chat Model → Respond to Webhook**.

1. **Webhook** node: add a **Message** parameter.
2. **OpenAI Chat Model** node: set the model to `deepseek-chat` and the system prompt to `You are a helpful assistant`.
3. **Respond to Webhook** node: output `{{ $json.message }}`.

Call the webhook URL:

```bash
curl -X POST "<webhook-url>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Reply with exactly: connected to MirAPI"}'
```

The response should contain `connected to MirAPI`. The first request draws a small amount from your prepaid balance; confirm it later in the console billing log or via `GET /api/usage/token`.

## How it works

n8n's OpenAI Chat Model node speaks the OpenAI Chat Completions protocol. MirAPI serves that protocol at `https://api.mirapi.ai/v1`, so the node's requests land on `POST /v1/chat/completions`. Responses stream as standard SSE — `data:` lines ending with `data: [DONE]` — and reasoning content arrives before the final answer.

MirAPI serves the same models over three protocols. The OpenAI node described here uses the OpenAI-compatible row; the same key also works over the other two protocols if you use n8n's Anthropic or Gemini nodes:

| Protocol | Base URL | Authentication |
|---|---|---|
| OpenAI-compatible | `https://api.mirapi.ai/v1` | `Authorization: Bearer` |
| Anthropic | `https://api.mirapi.ai` | `x-api-key` or `Authorization: Bearer` |
| Gemini | `https://api.mirapi.ai` or `https://api.mirapi.ai/v1beta` | `x-goog-api-key` or `?key=` |

## Errors and billing

| Status | Meaning | What to do |
|---|---|---|
| `401` | Key missing, invalid, or unknown | Fix the key in the OpenAI credentials |
| `403` | Key valid but rejected — balance exhausted, model not whitelisted, quota reached, or IP not allowed | Resolve the cause, then retry |
| `413` | Request too large | Reduce the payload |
| `429` | Rate limited (no `Retry-After` header) | Retry with jittered exponential backoff (1s → 2s → 4s, cap ~30s) |
| `500` | Server error | Safe to retry idempotent requests |

Every error message ends with a request ID; include it in any support ticket.

Chat usage is billed per token — input, output, and cache read, per 1M tokens. Reasoning tokens count as output, and cache reads cost less than normal input. Prompt caching is automatic on OpenAI-compatible models; confirm hits via `usage.prompt_tokens_details.cached_tokens`. The balance is prepaid USD and never expires — no subscription or minimum spend. When it runs out you get 403, and the same key resumes immediately after a top-up. Reconcile usage in the console billing log or via `GET /api/usage/token` (summary) and `GET /api/log/token` (per-request detail).

## Tool-specific pitfalls

- **Keep `/v1`.** n8n appends `/chat/completions` to the base URL; omitting `/v1` breaks the request path.
- **The model list is manual.** n8n cannot auto-discover MirAPI models, so type `deepseek-chat` if it is not listed. Use the exact id from `GET /v1/models` and drop any `vendor/` prefix.
- **403 with a valid key** usually means the model is not whitelisted for that key or the balance is exhausted. Top up or adjust the key's whitelist, then retry.
- **Streaming needs nothing special.** Newer n8n versions stream chat output by default; the gateway's stream is standard SSE, so the node handles it without extra configuration.

## Related links

- [Quickstart](/docs/quickstart)
- [OpenAI compatibility](/docs/openai-compat)
- [Models](/docs/models)
- [Billing](/docs/billing)
- [Authentication](/docs/api-reference/authentication)
- [Errors](/docs/api-reference/errors)