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: zhongguanhui@wxchina.com

---

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