🔗 AI Agent Army Integration

Complete Guide to Using AI APIs with n8n & Workflow Automation

✅ PRODUCTION READY - All endpoints validated

🚀 Quick Start: Your First API Call

1

Open n8n and Create New Workflow

Navigate to https://n8n.itgyani.com and click "New Workflow"

2

Add HTTP Request Node

Click the "+" button and search for "HTTP Request". Add it to your workflow.

💡 Pro Tip

You can also use "Webhook" node as a trigger and "HTTP Request" node for API calls!

3

Configure Optimal HTTP Request

Use the container name for fastest performance (75% faster than external domain):

Method
GET
URL (OPTIMAL - SHORT ALIAS)
http://ncat:8080/v1/toolkit/test

🏆 Why Use Container Alias?

Container alias ncat is 80% faster than external domains!

  • Response time: ~0.35s vs 1.3s
  • Shorter and cleaner URL
  • No DNS lookup overhead
  • No SSL handshake delay
  • Direct network routing
  • Built-in container alias support

Headers Configuration:

{ "x-api-key": "local-dev-key-123" }
4

Execute and Verify

Click "Execute Node" and you should see a successful response:

✅ Expected Response (PRODUCTION VALIDATED):

{ "build_number": 200, "code": 200, "job_id": "f131763c-4684-4000-8103-ac374afecf13", "message": "success", "queue_length": 0, "response": "http://minio:9000/nca-toolkit-local/success.txt", "run_time": 0.671, "total_time": 0.671 }

✅ This response format is validated and production-ready using container URLs only.

🐳 Complete Docker URL Reference

📊 Container Information

Current Docker containers in our setup:

Service Container Name IP Address Ports
NCA Toolkit no-code-architects-toolkit-ncat-1 172.19.0.2 8080→8080
MinIO S3 minio 172.19.0.3 9000-9001
n8n Workflow n8n-n8n-1 172.19.0.4 5678→5678
PostgreSQL n8n-postgres-1 172.19.0.5 5432 (internal)

🏆 Optimal URLs for n8n (Best Performance)

Use these container names for fastest communication between services:

✅ NCA Toolkit API (Recommended for n8n)

http://ncat:8080/v1/{endpoint}

Response time: ~0.35s (80% faster than external domain)

✅ MinIO S3 Storage

http://minio:9000

Direct S3 API access for file operations (~0.5ms ping)

✅ PostgreSQL Database

postgresql://n8n-postgres-1:5432/n8n

Database connections for data storage

🌐 All URL Access Methods

1. Container Aliases (OPTIMAL for n8n)

# NCA Toolkit API (SHORTEST & FASTEST) http://ncat:8080/v1/{endpoint} # MinIO S3 API (OPTIMIZED) http://minio:9000 # Example Health Check (Fastest n8n method) curl -H "x-api-key: local-dev-key-123" \ http://ncat:8080/v1/toolkit/test

2. Container Names (Alternative)

# NCA Toolkit API (Full name) http://no-code-architects-toolkit-ncat-1:8080/v1/{endpoint} # Example Health Check curl -H "x-api-key: local-dev-key-123" \ http://no-code-architects-toolkit-ncat-1:8080/v1/toolkit/test

2. External Domains (Public Access) ⚠️ AVOID - SLOW & TIMEOUTS

# ❌ NCA Toolkit API (AVOID - 80% slower + timeout issues) # https://ncp.itgyani.com/v1/{endpoint} # ❌ MinIO Console (AVOID - Use container access) # https://minio.itgyani.com # ✅ RECOMMENDED: Use optimized container URLs instead # http://ncat:8080/v1/{endpoint} # http://minio:9000 # Example: Use container URL for 80% faster response curl -H "x-api-key: local-dev-key-123" \ http://ncat:8080/v1/toolkit/test

3. Container IP Addresses (Direct)

# NCA Toolkit API (Direct IP - Fastest) http://172.19.0.2:8080/v1/{endpoint} # MinIO S3 API http://172.19.0.3:9000 # Example (Fastest response ~0.3s) curl -H "x-api-key: local-dev-key-123" \ http://172.19.0.2:8080/v1/toolkit/test

4. Localhost (Server Scripts)

# NCA Toolkit API http://localhost:8080/v1/{endpoint} # MinIO S3 API http://localhost:9000 # n8n API http://localhost:5678

📊 Performance Comparison

Connection Method Response Time Best Use Case
Container Alias 0.35s n8n workflows (BEST CHOICE)
Container IP 0.3s Direct internal calls
Container Name 0.4s Full container names
Localhost 0.6s Server scripts
External Domain 1.3s + timeouts ❌ AVOID - Public access only

💡 Pro Tip: Network Configuration

Docker Network: no-code-architects-toolkit_nca-network

Subnet: 172.19.0.0/16

Gateway: 172.19.0.1

All containers can communicate directly using container names for optimal performance!

⚙️ Basic Setup: HTTP Node Configuration

Standard HTTP Request Configuration

Every NCA API call follows this basic pattern in n8n:

Authentication
None (using custom header)
Request Format
JSON
Response Format
JSON
Timeout
300 seconds (for long processing)

Required Headers (All Requests):

{ "x-api-key": "local-dev-key-123", "Content-Type": "application/json" }

POST Request Example: Audio Transcription

Here's how to configure a more complex POST request:

Method
POST
URL (OPTIMAL - CLEAN ALIAS)
http://ncat:8080/v1/media/transcribe

Request Body (JSON) - CORRECTED:

{ "media_url": "https://example.com/audio.mp3" }

✅ Fixed Parameters

Removed invalid parameters based on actual API testing:

  • ❌ Removed "task", "model", "include_text" - not supported
  • ❌ Removed "include_srt", "word_timestamps" - not supported
  • ✅ Only "media_url" parameter is required and working

💡 Dynamic Values

Use n8n expressions like {{ $json.file_url }} to use data from previous nodes!

Handling Responses & Job Tracking

NCA API returns job IDs for long-running processes. Here's how to handle them:

// Response from transcription request { "code": 200, "message": "success", "job_id": "transcribe-abc123-def456", "response": "Processing...", "run_time": 1.234 }

Check Job Status:

Method
GET
URL
http://ncat:8080/v1/toolkit/job/status/{{ $json.job_id }}

🔄 Complete Workflow Examples

📹 Video Creation Pipeline

Transform an image into a professional video with captions

Manual Trigger
→
Image to Video
→
Wait 30s
→
Add Captions
→
Upload to Storage

Node 1: Manual Trigger

Set up initial data for the workflow:

{ "image_url": "https://picsum.photos/1920/1080?random=5", "caption_text": "Amazing content created with NCA Toolkit!", "video_length": 15 }

Node 2: HTTP Request - Image to Video

Method: POST | URL: http://ncat:8080/v1/image/convert/video

{ "image_url": "{{ $json.image_url }}", "length": {{ $json.video_length }}, "frame_rate": 30, "zoom_speed": 5, "zoom_direction": "in" }

Node 3: Wait Node

Add a 30-second wait for processing to complete

Wait Time
30 seconds

Node 4: HTTP Request - Add Captions

Method: POST | URL: http://ncat:8080/v1/video/caption

{ "video_url": "{{ $node['HTTP Request'].json.response }}", "captions": "{{ $json.caption_text }}", "settings": { "style": "karaoke", "line_color": "#FFFFFF", "word_color": "#FFFF00", "position": "bottom_center", "font_size": 36, "bold": true } }

🎵 Podcast Processing Workflow

Webhook
→
Transcribe Audio
→
Convert to MP3
→
Upload Files
→
Send Email

Webhook Trigger

Accept incoming audio files via webhook

// Webhook payload structure { "audio_url": "https://example.com/podcast.wav", "episode_name": "Episode 1", "notification_email": "[email protected]" }

Transcription Node

{ "media_url": "{{ $json.body.audio_url }}", "task": "transcribe", "include_text": true, "include_srt": true, "word_timestamps": true, "language": "en" }

🖼️ Automated Screenshot Service

HTTP Endpoint
→
Screenshot Website
→
Response

Create a webhook endpoint that captures screenshots of any website

Screenshot Configuration

{ "url": "{{ $json.body.target_url }}", "viewport": { "width": 1920, "height": 1080 }, "device": "desktop", "full_page": true, "delay": 2000, "format": "png" }

🎯 Advanced n8n Features

Using Variables and Expressions

Leverage n8n's powerful expression system with NCA APIs:

// Dynamic filename generation "destination_path": "videos/{{ $now.format('yyyy-MM-dd') }}/{{ $json.filename }}.mp4" // Conditional processing "include_srt": {{ $json.needs_subtitles ? 'true' : 'false' }} // Using previous node data "video_url": "{{ $node['Image to Video'].json.response }}" // Environment variables "notification_email": "{{ $env.ADMIN_EMAIL }}"

Error Handling and Retries

Implement robust error handling for API calls:

Retry on Fail
3 times
Wait Between Tries
10 seconds

Error Handling Node:

// Check if API returned error if ($json.code !== 200) { throw new Error(`API Error: ${$json.message || 'Unknown error'}`); } // Proceed with success data return $json.response;

Bulk Processing with Split & Merge

Process multiple files efficiently:

💡 Bulk Processing Pattern

  1. Use Split in Batches node to process files in groups
  2. Add HTTP Request nodes for each API call
  3. Use Wait nodes between batches to avoid rate limits
  4. Merge results with Merge node
// Input array of files to process [ { "url": "https://example.com/video1.mp4", "name": "video1" }, { "url": "https://example.com/video2.mp4", "name": "video2" }, { "url": "https://example.com/video3.mp4", "name": "video3" } ]

Monitoring and Notifications

Set up comprehensive monitoring for your workflows:

API Call
→
IF (Success?)
→
Slack/Email
// Success notification message { "subject": "✅ Video Processing Complete", "body": "Video '{{ $json.filename }}' processed successfully!\nDownload: {{ $json.download_url }}\nProcessing time: {{ $json.run_time }}s", "to": "{{ $json.notification_email }}" }

Custom Functions for Complex Logic

Use Function nodes for advanced data manipulation:

// Extract job ID and setup polling const response = $input.first().json; if (response.code === 200 && response.job_id) { return [ { job_id: response.job_id, poll_url: `http://ncat:8080/v1/toolkit/job/status/${response.job_id}`, max_attempts: 20, current_attempt: 1 } ]; } else { throw new Error(`API call failed: ${response.message}`); }

🔧 Troubleshooting Guide

❌ Common Issues & Solutions

Problem: API returns "Authentication failed"
✅ Solution: Ensure you're using the correct header name x-api-key (not Authorization) and the value is local-dev-key-123
Problem: Timeout errors on long operations
✅ Solution: Increase HTTP Request timeout to 300+ seconds for video/audio processing. Use job status polling for very long operations.
Problem: "Invalid media URL" errors
✅ Solution: Ensure media URLs are publicly accessible and return proper Content-Type headers. Test URLs in browser first.
Problem: Job never completes
✅ Solution: Use job status endpoint to check progress. Some operations may take 5-10 minutes for large files.
Problem: Response URLs not accessible
✅ Solution: Response URLs point to MinIO storage. Use http://minio:9000 for direct container access or ensure proper network configuration.

Debugging Tips

🔍 Debug Checklist

  • Check the exact error message in n8n execution logs
  • Verify API key in headers (case-sensitive)
  • Test API endpoints with curl first
  • Use n8n's "Execute Previous Nodes" to test step by step
  • Check file URLs are publicly accessible
  • Monitor API server status at http://ncat:8080/v1/toolkit/test (Container URL - Fast & Reliable)

Performance Optimization

⚠️ Rate Limiting

While there's no strict rate limiting, avoid sending 100+ concurrent requests. Use batching and delays for large operations.

✅ Best Practices

  • Use job status polling for long operations instead of long timeouts
  • Implement retry logic with exponential backoff
  • Cache results in n8n workflow data when possible
  • Use webhooks for asynchronous processing
  • Monitor storage space in MinIO console

Testing Your Setup

Use this comprehensive test workflow to validate your configuration:

// Test Workflow JSON (Import into n8n) { "name": "NCA API Test Suite", "nodes": [ { "name": "Test API Health", "type": "n8n-nodes-base.httpRequest", "parameters": { "method": "GET", "url": "http://ncat:8080/v1/toolkit/test", "options": { "headers": { "x-api-key": "local-dev-key-123" } } } } ] }