n8n-nodes-xtai

Xuantong AI n8n Community Nodes - A powerful n8n integration package for Xuantong AI platform, providing 32 AI capabilities including SKU recognition, scene detection, fake detection, area estimation, and more.

Table of Contents

• Features
• Installation
• Uninstallation
• Operations
• Credentials
• Usage
• Configuration
• Examples
• Compatibility
• Troubleshooting
• License
• Support

Features

This package provides a unified node that integrates 36 AI operations from Xuantong AI platform across 10 functional categories:

• Security (1 operation): User authentication and token management
• SKU Recognition (3 operations): Shelf detection, async detection, result retrieval
• Combined Recognition (3 operations): Combined async detection, result lookup, SKU combined sync detection
• Scene Recognition (2 operations): Store header detection, display detection
• Fake Detection (7 operations): Multiple fake detection methods including LVMO, TBC, and accurate detection
• Image Merge (5 operations): Merge prediction, image splice, result retrieval, deduplication
• Duplicate Check (6 operations): Picture check, similarity sync search, async similarity search, fetch similarity result, similarity collect, delete history image
• Area Detection (3 operations): Area detection, carton estimation, carton fullness
• Image Quality (1 operation): Blur detection
• Other Detection (2 operations): Person count detection, shelf section detection
• Super Model (3 operations): Sync/async detection, result retrieval

Installation

Prerequisites

• n8n version 1.0.0 or higher
• npm or yarn package manager

Install via npm

npm install n8n-nodes-xtai

Install via n8n CLI

n8n node install n8n-nodes-xtai

Install Manually

1. Navigate to your n8n user directory:

   cd ~/.n8n

2. Install the package:

   npm install n8n-nodes-xtai

3. Restart n8n

Uninstallation

Remove via npm

npm uninstall n8n-nodes-xtai

Remove via n8n CLI

n8n node remove n8n-nodes-xtai

Manual Removal

1. Navigate to your n8n user directory:

   cd ~/.n8n

2. Uninstall the package:

   npm uninstall n8n-nodes-xtai

3. Clean up node_modules:

   rm -rf node_modules/n8n-nodes-xtai

4. Restart n8n

Operations

Security Operations

| Operation | Description | |-----------|-------------| | Login | Authenticate with username/password and retrieve access token. Supports saving token to workflow variables for subsequent operations. |

SKU Recognition Operations

| Operation | Description | |-----------|-------------| | Shelf Sync Detect | Synchronously detect SKUs from shelf image. | | Shelf Async Detect | Asynchronously detect SKUs from shelf image. | | Fetch Shelf Detect Result | Retrieve results from async shelf detection. |

Combined Recognition Operations

| Operation | Description | |-----------|-------------| | Combined Async Detect | Asynchronously detect using combined model. | | Find Combined Detect Result | Query results from async combined detection. | | SKU Combined Sync Detect | Synchronously detect SKUs using combined model. |

Scene Recognition Operations

| Operation | Description | |-----------|-------------| | Store Header Detect | Detect store header in image. | | Display Detect | Detect product displays in image. |

Fake Detection Operations

| Operation | Description | |-----------|-------------| | Fake Sync Detect | Synchronously detect fake products. | | Fake Async Detect | Asynchronously detect fake products. | | Find Fake Detect Result | Retrieve async fake detection results. | | LVMO Fake Sync Detect | Detect fake products using LVMO algorithm. | | TBC Fake Sync Detect | Detect fake products using TBC algorithm. | | Accurate Fake Sync Detect | High-accuracy fake product detection (sync). | | Accurate Fake Async Detect | High-accuracy fake product detection (async). |

Image Merge Operations

| Operation | Description | |-----------|-------------| | Merge Prediction | Predict merged image results. | | Image Splice | Splice multiple images together. | | Find Image Splice Result | Retrieve async image splice results. | | Deduplication | Remove duplicate images. | | Find Deduplication Result | Retrieve async deduplication results. |

Duplicate Check Operations

| Operation | Description | |-----------|-------------| | Picture Check | Real-time duplicate check for multiple images. | | Similarity Sync Search | Synchronous similarity search against historical library. | | Async Similarity Search | Asynchronous similarity search returning batch ID. | | Fetch Similarity Result | Retrieve async similarity search results by batch ID. | | Similarity Collect | Submit images to similarity query library. | | Delete History Image | Delete images from historical library. |

Area Detection Operations

| Operation | Description | |-----------|-------------| | Area Detect | Detect floor display area. | | Carton Estimation | Estimate carton quantity. | | Carton Fullness | Estimate carton fullness. |

Image Quality Operations

| Operation | Description | |-----------|-------------| | Blur Detect | Detect if image is blurry. |

Other Detection Operations

| Operation | Description | |-----------|-------------| | Num Person Detect | Count number of people in image. | | Shelf Section Detect | Detect shelf sections. |

Super Model Operations

| Operation | Description | |-----------|-------------| | Super Model Sync Detect | Synchronously detect using super model. | | Super Model Async Detect | Asynchronously detect using super model. | | Find Super Model Result | Retrieve super model detection results. |

Credentials

Xuantong AI Platform Configuration

This node requires credentials to authenticate with the Xuantong AI platform.

Credential Name: xuantongai-credential

Fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | Server Address | String | ✅ Yes | API server address (e.g., https://ai.xtion.net) | | Username | String | ❌ No | Login username (optional) | | Password | String | ❌ No | Login password (optional) | | Long-lived Token | String | ❌ No | Permanent access token for API calls |

Setup Instructions:

1. In n8n, go to Credentials → New Credential
2. Search for "Xuantong AI" or "玄瞳AI"
3. Select Xuantong AI Platform Configuration (玄瞳AI平台配置)
4. Fill in the required fields:
   • Server Address: Your Xuantong AI platform URL
   • Optionally, add username/password for login operations
   • Optionally, add a long-lived token for direct API access
5. Click Save

Usage

Basic Usage

1. Add the Node: Drag the "Xuantong AI" node to your workflow
2. Configure Credentials: Select your configured credentials
3. Select Category: Choose from 10 functional categories
4. Select Operation: Choose the specific operation
5. Configure Parameters: Fill in the required parameters for the operation
6. Execute: Run the workflow

Token Management

The node supports flexible token management with three priority levels:

1. Node Parameters (Highest Priority)

   • Directly input token in node parameters
   • Useful for one-time or testing workflows

2. Workflow Variables (Medium Priority)

   • Use $workflow.token expression
   • Login node can save token to workflow variables
   • Shared across multiple operations in the same workflow

3. Credentials (Lowest Priority)

   • Long-lived token stored in credentials
   • Best for production environments

Login Workflow Example

// 1. Login Operation
- Operation: Security → Login
- Save Token to Workflow: ✅ Yes
- Result: Token saved to $workflow.token

// 2. Use Token in Subsequent Operations
- Operation: SKU Recognition → Shelf Sync Detect
- Leave token parameter empty
- Node will automatically use $workflow.token

Configuration

Node Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | Server Address | String | ❌ No | - | Platform API URL (overrides credential) | | Authentication Token | String | ❌ No | - | API token (overrides credential and workflow) | | Resource Category | Options | ✅ Yes | security | Select functional category | | Operation | Options | ✅ Yes | - | Select specific operation | | Operation Parameters | Fixed Collection | ⚠️ Varies | - | Parameters for selected operation |

Parameter Priority

For Server Address and Authentication Token:

1. Node instance parameters (highest)
2. Credentials configuration (lowest)

For Authentication Token (additional):

3. Workflow variable $workflow.token (medium)

Note: Login operation does not require token. All other operations require token from one of the three sources.

Examples

Example 1: Login and Detect SKUs

[
  {
    "nodeName": "Login",
    "category": "security",
    "operation": "login",
    "parameters": {
      "username": "your_username",
      "password": "your_password",
      "saveTokenToWorkflow": true
    }
  },
  {
    "nodeName": "Detect SKUs",
    "category": "skudetect",
    "operation": "shelfSyncDetect",
    "parameters": {
      "imageUrl": "https://example.com/shelf.jpg"
    }
  }
]

Example 2: Fake Detection with Workflow Token

{
  "nodeName": "Detect Fake Products",
  "category": "fakedetect",
  "operation": "fakeSynchDetect",
  "parameters": {
    "url": "https://example.com/product.jpg"
  },
  "token": "{{ $workflow.token }}"
}

Example 3: Batch Processing

{
  "nodeName": "Batch Area Detection",
  "category": "areadetect",
  "operation": "areaDetect",
  "parameters": {
    "frontImageUrl": "https://example.com/front.jpg",
    "sideImageUrl": "https://example.com/side.jpg"
  }
}

Compatibility

• Minimum n8n Version: 1.0.0
• Tested n8n Versions: 1.x, latest
• Node.js Versions: Compatible with n8n requirements (v16+)
• Platform: Windows, Linux, macOS

Troubleshooting

Common Issues

Issue: "Authentication token cannot be empty"

Solution:

• Ensure you've configured credentials
• Or provide token in node parameters
• Or use login operation to save token to workflow variables

Issue: "Parameter dependencies cannot be resolved"

Solution:

• Try selecting a different resource category first
• Then select your desired operation
• Or restart n8n

Issue: "Could not get parameter"

Solution:

• Ensure all required parameters are filled
• Check if parameter names match exactly

Debug Mode

Enable debug logging in n8n:

export NODE_ENV=development
export DEBUG=n8n:*
n8n start

License

MIT License - see LICENSE file for details

Support

• Documentation: https://ai.xtion.net
• Issues: GitHub Issues
• Email: [email protected]

Changelog

Version 0.1.2 (2026-01-21)

New Features

• ✅ Added 4 new similarity operations in Duplicate Check category
• ✅ Similarity Sync Search - Synchronous similarity search
• ✅ Async Similarity Search - Asynchronous search with batch ID
• ✅ Fetch Similarity Result - Retrieve async search results
• ✅ Similarity Collect - Submit images to library
• ✅ Delete History Image - Remove images from library
• ✅ Enhanced result parsing with JSON string to object conversion
• ✅ Improved error handling and validation

Version 0.1.1 (2026-01-20)

Bug Fixes

• ✅ Fixed response parsing to use JSON.parse(JSON.stringify(response))
• ✅ Enhanced type safety by replacing any with proper types
• ✅ Updated deprecated request to httpRequest
• ✅ Fixed lint errors across all operation files

Version 0.1.0 (2026-01-20)

Initial Release

• ✅ 32 AI operations across 10 categories
• ✅ Unified node architecture
• ✅ Flexible credential management
• ✅ Workflow variable support for tokens
• ✅ Comprehensive error handling
• ✅ Full TypeScript support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with ❤️ for the n8n community by Xuantong Technology.

中文文档 / Chinese Documentation