workflows/n8n/README.md

n8n Workflows

Docker Compose n8n

The project Docker Compose stack includes n8n at:

http://localhost:5678

Copy .env.example to .env, then set at least:

MAESTER_API_KEY=your_maester_api_key
N8N_ENCRYPTION_KEY=generate_a_long_stable_random_value
PEXELS_API_KEY=your_pexels_api_key

The compose file injects these values into n8n:

MAESTER_BASE_URL=http://maester-enterprise:7860
MAESTER_API_KEY=your_maester_api_key
OPENAI_API_KEY=your_openai_api_key
GEMINI_API_KEY=your_gemini_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
AI_PROVIDER=openai
LLM_PROVIDER=openai
PEXELS_API_KEY=your_pexels_api_key
LLM_MODEL=gpt-4o-mini
KTTS_MODEL=kokoro-v0_19.onnx
KTTS_VOICE=af_bella.pt

Import any workflow JSON from this folder into n8n after the stack is running.

AI Provider Smoke Test

Import:

ai_provider_smoke_test.json

Set AI_PROVIDER or LLM_PROVIDER in .env to one of:

openai
gemini
openrouter

The workflow uses these provider-specific variables:

OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-1.5-flash

OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_SITE_URL=http://localhost:5678
OPENROUTER_APP_NAME=Maester Enterprise

OpenRouter uses the OpenAI-compatible chat completions format. Gemini uses the generateContent endpoint and returns a Gemini-shaped response.

Webhook TikTok Storytelling With Pexels

Import:

webhook_tiktok_storytelling_pexels.json

This workflow exposes an n8n webhook at:

POST /webhook/maester/create-tiktok-story

Example payload:

{
  "topic": "a founder saves 10 hours a week with automation",
  "series_title": "Automation Proof",
  "audience": "small business owners",
  "scene_count": 5,
  "scene_duration": 5,
  "output_name": "automation_proof_episode_01.mp4"
}

The webhook creates a TikTok render payload, searches Pexels for portrait clips, submits the job to /services/render/render, and returns Maester's job_id, status_url, and download_url. Poll MAESTER_BASE_URL + status_url until the job state is complete, then download from MAESTER_BASE_URL + download_url.

TikTok Storytelling Mini Series With Pexels

Import tiktok_storytelling_pexels.json into n8n.

For the full autonomous version from the project specification, import:

autonomous_tiktok_storytelling_miniseries.json

Required n8n environment variables:

MAESTER_BASE_URL=https://your-maester-space.hf.space
MAESTER_API_KEY=your_maester_api_key
PEXELS_API_KEY=your_pexels_api_key
OPENAI_API_KEY=your_openai_api_key
LLM_MODEL=gpt-4o-mini
KTTS_MODEL=kokoro-v0_19.onnx
KTTS_VOICE=af_bella.pt

What the workflow does:

1. Builds a five-scene TikTok storytelling episode.
2. Searches Pexels videos for each scene query.
3. Picks portrait MP4 assets when available.
4. Creates a Maester render payload with scene captions, text overlays, blur background, and per-scene effects.
5. Submits the render job to /services/render/render.

The workflow expects all services to be enabled in Maester:

MAESTER_MOUNT_SERVICES=true
MAESTER_ENABLE_RENDER_ENGINE=true

The final node returns the render job response. Add a Wait node and an HTTP Request node against the returned status_url if you want automatic polling.

Pexels attribution metadata is included in each scene under metadata.pexels so you can preserve attribution data in downstream reports.

Autonomous Mini-Series Workflow

autonomous_tiktok_storytelling_miniseries.json implements this production pipeline:

1. Configures the topic: The Girl Who Disappeared Every Midnight.
2. Calls OpenAI Chat Completions and requests strict JSON story output.
3. Validates the returned story schema.
4. Creates a Maester campaign record through /automation/campaigns.
5. Runs Maester quality and compliance checks.
6. Loops through scenes inside an n8n Code node.
7. Searches Pexels portrait videos with retry queries.
8. Generates KTTS narration for every scene through /services/ktts/v1/audio/speech.
9. Uploads scene narration files to /services/render/upload.
10. Generates and uploads a full episode narration track for the final render engine voiceover.
11. Builds a 1080x1920 TikTok render payload with captions, blur background, scene effects, animated subtitle settings, and Pexels attribution metadata.
12. Submits the final render to /services/render/render.

The render engine accepts one global voiceover track, so the workflow generates per-scene narration artifacts for traceability and also creates one combined narration track for final video rendering.

Islamic Motivation TikTok Automation Pipeline

Import:

islamic_motivation_tiktok_pipeline.json

This workflow implements the Islamic motivation pipeline:

1. Runs once per day from an n8n Schedule Trigger.
2. Calls GPT-4o for a respectful Islamic motivational topic and narration.
3. Calls GPT-4o again for exactly five cinematic Pexels-optimized scenes.
4. Searches Pexels portrait videos scene by scene, with nature fallback.
5. Downloads each clip and sends it to Maester FFmpeg automation.
6. Trims and resizes each clip to 1080x1920 / 9:16.
7. Concats clips in deterministic scene order.
8. Searches Archive.org for an Islamic nasheed and continues without music if none is found.
9. Burns TikTok-style ASS captions into the video.
10. Merges nasheed audio at low volume.
11. Normalizes the final MP4 for TikTok compatibility.
12. Uploads the final file to Maester render inspection and validates duration, size, audio, and video stream metadata.
13. Uploads to TikTok if TIKTOK_UPLOAD_ENABLED=true; otherwise returns a dry-run render result.
14. Sends Google Sheets and Telegram status updates.

Required environment variables:

MAESTER_BASE_URL=https://your-maester-space.hf.space
MAESTER_API_KEY=your_maester_api_key
OPENAI_API_KEY=your_openai_api_key
PEXELS_API_KEY=your_pexels_api_key

Optional publishing/logging variables:

TELEGRAM_BOT_TOKEN=123456:telegram_bot_token
TELEGRAM_CHAT_ID=123456789
GOOGLE_SHEETS_WEBHOOK_URL=https://script.google.com/macros/s/your-script-id/exec
TIKTOK_UPLOAD_ENABLED=false
TIKTOK_ACCESS_TOKEN=your_tiktok_content_posting_access_token

Required Maester services:

MAESTER_MOUNT_SERVICES=true
MAESTER_ENABLE_FFMPEG_AUTOMATION=true
MAESTER_ENABLE_RENDER_ENGINE=true

The workflow uses these Maester endpoints:

• /automation/campaigns
• /automation/compliance/check
• /services/ffmpeg/n8n/execute/trim
• /services/ffmpeg/n8n/execute/resize_916
• /services/ffmpeg/n8n/execute/concat
• /services/ffmpeg/n8n/execute/add_subtitles
• /services/ffmpeg/n8n/execute/merge_music
• /services/ffmpeg/n8n/execute/normalize
• /services/render/upload
• /services/render/inspect

TikTok upload is intentionally dry-run by default. Enable it only after your TikTok Content Posting API app is approved and tested.