n8n-nodes-grok-official

Official-style n8n community nodes for the Grok API from xAI — everything the platform offers, wrapped for your workflows:

• Text — chat completions and summarization with thinking (reasoning) mode, via either the modern Responses API or the legacy Chat Completions API.
• Image — text-to-image generation and image editing with the Grok Imagine models.
• Video — text-to-video and image-to-video generation, with built-in asynchronous polling and optional video download.
• Voice — text-to-speech (raw audio out), speech-to-text (transcription with words, timings, diarization), and listing built-in voices.

Every node talks to an OpenAI-compatible Base URL. By default that is https://api.x.ai/v1, but you can point any of the nodes at any OpenAI-compatible endpoint (OpenAI, OpenRouter, Together, Azure OpenAI, a local vLLM / Ollama bridge, a corporate proxy, …) simply by entering your own Base URL in the credential. No code changes — just configuration.

Licensing note: the package is licensed under the MIT License, mirroring the official community-node starter. It is not affiliated with or endorsed by xAI; “official” in the package name follows the npm naming convention for n8n community node packages.

---

Table of Contents

• Why Grok in n8n?
• Features
• Installation
• Credentials
• The Four Nodes
  • Grok Text
  • Grok Image
  • Grok Video
  • Grok Voice
• Examples
• OpenAI Compatibility
• Compatibility
• Development
• Resources
• License

---

Why Grok in n8n?

This package turns the full Grok API from xAI into four visual, drag-and-drop nodes — so text, image, video and voice automation can be built on an n8n canvas in minutes, without writing or maintaining custom integration code.

Business value

• One integration, four capabilities. Chat & reasoning, image generation and editing, video generation, and voice (TTS/STT) all share a single credential — simpler setup, fewer moving parts, one place to manage your API key.
• No lock-in, one field away. Every node is OpenAI-compatible through the credential's Base URL: start on xAI today and point the same workflows at OpenAI, OpenRouter, a self-hosted vLLM / Ollama, or a corporate proxy whenever you need to.
• Faster media pipelines. Asynchronous video generation with in-node polling, and images / video / audio delivered straight into n8n as binary data — multi-step production workflows without glue code.
• Production-ready by default. Reasoning summaries surfaced as data, error handling with item indices, continueOnFail, correct paired items, strict TypeScript and a publishing pipeline — built to be maintained, not hacked on.

What you can build with it

Use case	Nodes
Support copilot — reason over a customer email and draft a reply	Grok Text
Content studio — turn a brief into image and video assets, downloaded as binary	Grok Image · Grok Video
Podcast → shownotes → an AI-narrated recap	Grok Voice · Grok Text
Brand voice at scale — render marketing lines in every built-in voice	Grok Voice
Privacy-first local stack — route everything through your own vLLM / Ollama endpoint	All nodes, custom Base URL

---

Features

🧠 Thinking / reasoning mode	Choose a reasoning effort (low, medium, high) for models that support it and read the model’s reasoning summaries right out of the output — no hidden chains-of-thought, everything surfaced as data.
🔗 OpenAI-compatible	Credentials include a Base URL field. Point the nodes at xAI or any OpenAI-compatible provider.
🖼️ Image generation & editing	Generate 1–10 images, choose aspect ratio and resolution, receive URLs or base64, and optionally download the results straight into binary data.
🎬 Video generation	Text-to-video and image-to-video (binary or URL input), 1–15 s clips, 13 aspect ratios, 480p/720p/1080p. Asynchronous generation is polled in-node (wait for completion) or delegated to a separate Get Status operation.
🔉 Text-to-speech	Raw audio bytes out — MP3, WAV, PCM, µ-law or A-law, with language, speed, text normalization and optional per-character timestamps.
🎤 Speech-to-text	Multipart transcription with word-level timings, speaker diarization, key-term biasing and a voice-activity gate, from binary data or a public URL.
📦 Binary data everywhere	Download images/videos and produce audio natively in n8n’s binary ecosystem; consume incoming binary for editing, animation and transcription.
🧯 Error handling	NodeOperationError with item indices, continueOnFail support and correct pairedItem mappings on every output.
💼 Professional packaging	Strict TypeScript, ESLint 9 flat config, Prettier, CHANGELOG, code of conduct, security policy and an npm-publishing GitHub Action — all mirroring the official n8n-nodes-starter.

---

Installation

n8n Cloud / self-hosted community node

1. Copy the package name: n8n-nodes-grok-official.
2. In n8n, go to Settings → Community Nodes.
3. Click Install a community node, paste the name and install it.
4. Add any of the Grok nodes to your canvas and connect them to the Grok API credential.

Manual install on a self-hosted n8n

If you prefer to install the package directly — for example in an air-gapped environment, or when you manage n8n with npm or Docker — install it into your n8n installation and enable it as a custom extension:

# run inside the directory where n8n is installed
npm install n8n-nodes-grok-official

Then start n8n with the package enabled:

N8N_CUSTOM_EXTENSIONS=n8n-nodes-grok-official n8n start

Or add it permanently to your n8n .env file and restart n8n:

N8N_CUSTOM_EXTENSIONS=n8n-nodes-grok-official

Docker users: pass the same environment variable to the container and make sure the package lands inside the container's node_modules (mount it into the image, or bake it into a custom image).

Local development install

# Clone and install
git clone https://github.com/mehrdadashtari/n8n-nodes-grok-official.git
cd n8n-nodes-grok-official
npm install

# Symbolically link so an n8n project can find your local build
npm link

Inside your n8n project root:

npm link n8n-nodes-grok-official

For a full walkthrough of the development workflow (including build:watch usage), see docs/DEVELOPMENT.md.

---

Credentials

The Grok API credential has exactly two fields:

Field	Type	Default	Description
API Key	Password	—	Your xAI API key (xai-...). Get one at console.x.ai.
Base URL	String	https://api.x.ai/v1	Any OpenAI-compatible API root, including the /v1 suffix.

Using a custom Base URL

The credential’s Base URL lets you send the same node configuration to any OpenAI-compatible endpoint:

https://api.x.ai/v1                                    ← xAI (default)
https://api.openai.com/v1                              ← OpenAI
https://openrouter.ai/api/v1                            ← OpenRouter
https://grok-vllm.mycompany.internal/v1                ← your own inference proxy
http://localhost:8000/v1                                ← local vLLM / llama.cpp / Ollama

Setting it is optional — leave it empty to use xAI. The API key is always sent as a Bearer token via the Authorization header, and the credential is tested against GET /models when you click Test in n8n.

---

The Four Nodes

Search the node panel for “Grok” to find all four. Each node emits one output item per API result, with the operation and input echoed back into the JSON so downstream expressions never depend on hidden state.

Grok Text

Handles the text side of the API.

Operations

• Message POST /responses (Responses API) or POST /chat/completions — chat with a Grok model.
• Summarize — a convenient wrapper that builds a task-specific system prompt and turns your text into a short, medium or long summary in paragraph or bullet form.

Key settings

Setting	Purpose
API Mode	Responses API (recommended) or Chat Completions. Model defaults and parameter names adapt automatically (e.g. max_output_tokens vs max_tokens).
Model	Defaults to grok-4.5. Change it to any model offered by your Base URL (e.g. grok-3.9-reasoning, grok-4-20-mini).
Thinking/Reasoning effort	model default, low, medium or high. Sent as reasoning: { effort } on the Responses API.
Include reasoning output	When enabled, the model’s reasoning summaries are extracted and exposed as reasoningText on the output.
Temperature	0–2, default 1.
Max output tokens	0 lets the model run to completion.
Store conversation	Whether the conversation is retained by the provider (sent as store).

Output fields per item

{
  "operation": "message",
  "apiMode": "responses",
  "model": "grok-4.5",
  "outputText": "…the assistant's answer…",
  "reasoningText": "…the model's thinking summary, if requested…",
  "response": { }
}

Grok Image

Generates and edits images with the Grok Imagine models.

Operations

• Generate POST /images/generations — text-to-image.
• Edit POST /images/edits — edit an existing image from binary data or a URL.

Highlights

• Up to 10 images per request; every result becomes its own output item.
• Full aspect-ratio palette (1:1 → cinematic 9:20) and resolution control (auto / 1K / 2K).
• Response format: temporary URL or base64 — combine with Download Image(s) to attach the PNG to the item as binary (data, data1, data2, …).

Grok Video

Generates videos with the Grok Imagine Video models. Video generation is asynchronous — the node is built around that.

Operations

• Generate POST /videos/generations — submit a job from a text prompt or by animating an image (binary data or a public URL / data URI).
• Get Status GET /videos/{request_id} — check a job you submitted earlier (e.g. in a separated workflow step or previous run).

Key settings

Setting	Purpose
Duration	1–15 seconds (default 8).
Aspect Ratio	7 presets (1:1 … 2:3); image-to-video keeps the source framing unless overridden.
Resolution	480p (default), 720p, 1080p.
Wait for Completion	true (default): poll in-node until done, fetch the result, and optionally download the video into binary. false: return immediately with the request_id to poll later.
Max Wait Time / Poll Interval	Timeout and cadence for the in-node polling loop.
Download Video	Attach the finished .mp4 to the output as binary data.

Grok Voice

The audio side — speech in, text out, and text in, audio out.

Operations

• Text to Speech POST /tts — synthesize text into audio. The response is written straight to binary data in your node.
• Speech to Text POST /stt — transcribe audio (binary data or URL) into text with word-level timings.
• List Voices GET /tts/voices — emit one output item per built-in voice (voice_id, name, language) — handy as the basis for a “voice picker”.

Text to Speech options

• Codec — MP3, WAV, PCM, µ-law or A-law; sample rate (8–48 kHz) and bit rate (MP3 only).
• Speed — 0.25×–4×.
• Include timestamps — returns per-character timing metadata alongside the audio.
• Text normalization — spell numbers/abbreviations as they should be spoken.
• Expressive tags work in the prompt itself: [pause], [laugh], <whisper>, <slow>, <emphasis>, …

Speech to Text options

• Language (+ Format Transcription) — written-form numbers, currencies and units.
• Speaker Diarization — each word gains a speaker index.
• Key Terms — comma-separated vocabulary to bias toward.
• Filler words, voice-activity threshold, format hint and sample rate for raw audio.

Speech-to-text output includes the merged transcript, detected language, total duration and the full words[] array (and channels[] for multichannel audio).

---

Examples

Complete, copy-pasteable workflows live in docs/EXAMPLES.md. A taste:

1. Reasoning assistant — trigger on an email, ask Grok with reasoningEffort = high, read reasoningText to log the model’s line of thinking, then store outputText.
2. Bulk image-to-video — read images from a folder, Grok Video → Generate with Download Video = on, save the .mp4s.
3. Podcast → shownotes — Grok Voice → Speech to Text (with diarization) feeds Grok Text → Summarize; TTS reads the summary back and posts the audio to Slack.
4. Brand voice at scale — List Voices → loop → Text to Speech a marketing line in every available voice_id.

---

OpenAI Compatibility

• Every node resolves its endpoint from the credential’s Base URL and authenticates with Authorization: Bearer <api-key>.
• The Text node sends standards-compliant payloads that OpenAI-compatible providers understand:
  • Responses API: POST /responses with input, model, reasoning, store, max_output_tokens.
  • Chat Completions: POST /chat/completions with messages, model, temperature, max_tokens.
• Image, video and voice use the same hosted media workflows (URL / base64 / multipart) as the ResNet roster of OpenAI-compatible APIs, so they work against mirrors that implement them.
• When you supply a different Base URL, pass the model identifiers that that provider accepts — the node makes no assumptions about which models exist.

---

Compatibility

n8n	v1.0+ (community-node API version 1)
Node.js	v18+
xAI API	Responses API, Chat Completions, Images, Videos, TTS, STT (as documented at docs.x.ai)
OpenAI-compatible	Any provider exposing the /responses or /chat/completions / media APIs — see OpenAI Compatibility.

---

Development

Node development is exactly the standard n8n flow — see docs/DEVELOPMENT.md.

npm install          # install dependencies
npm run build        # compile TypeScript → dist/
npm run lint         # lint (ESLint 9 flat config) + type-checks
npm run dev          # build:watch + run a local n8n instance against your nodes
npm run release      # semantic-release via release-it (uses .github/workflows/publish.yml)

Before you contribute, please read CODE_OF_CONDUCT.md and CONTRIBUTING.md.

---

Resources

• xAI Documentation
• n8n Community Nodes documentation
• n8n-nodes-starter — the template this package follows
• xAI API platform

---

License

MIT © your-organization