# 1688 → AliExpress AI Product Matcher (Vision + LLM Verified) (`crawleast/1688-aliexpress-product-matcher`) Actor

For each 1688 product, get ONE AI-verified AliExpress equivalent — not a raw candidate list to sort. A vision model (OpenCLIP) + an LLM (DeepSeek) run a two-pass match judgment. Official AliExpress Affiliate API only. Pay only for delivered results.

- **URL**: https://apify.com/crawleast/1688-aliexpress-product-matcher.md
- **Developed by:** [Kyle Wang](https://apify.com/crawleast) (community)
- **Categories:** E-commerce, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $21.00 / 1,000 delivered product results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 1688 → AliExpress AI Product Matcher (Vision + LLM Verified)

Give this Actor a **1688 product** (title + image) and it returns **ONE AI-verified AliExpress equivalent** — the single product you can actually use as a supplier or competitor — not a raw list of look-alikes for you to sort through.

Every candidate is put through a **two-stage AI pipeline**: a vision model (OpenCLIP) scores visual + title similarity, then an LLM (DeepSeek) runs a **two-pass judgment** to confirm the match is genuinely the same or a close substitute. Only a product that survives both stages is returned.

Retrieval runs **only** through the official **AliExpress Affiliate API** — no scraping, no reverse-engineered endpoints, no CAPTCHA bypass, no proxy chains.

Built for cross-border **sourcing agents, dropshippers, and resellers** who need a decision, not a search result.

***

### This is a matcher, not a scraper

Most 1688 / AliExpress Actors are **scrapers**: you give a keyword or an image and get back 20–100 candidates, then you spend your own time filtering out the false positives.

This Actor is a **matcher**. It does the filtering for you with AI and commits to an answer:

| | Typical scraper / image-search Actor | **This AI matcher** |
| --- | --- | --- |
| Output | 20–100 candidates to sort yourself | **ONE** `selectedCandidate` (or an honest `null`) |
| Match verification | None — you decide | **Vision (OpenCLIP) + LLM (DeepSeek) two-pass judgment** |
| Chinese-title handling | Weak (queries on Chinese keywords) | English `searchQuery` override built in |
| Retrieval source | Often reverse-engineered mobile APIs / proxies | **Official AliExpress Affiliate API only** |
| What you do with it | More manual work | Drop the pair straight into sourcing |

Use a scraper if you want candidates and will sort them yourself. Use **this** if you want **one verified supplier equivalent per SKU** and don't want to hunt through false positives.

***

### What you get

For every source SKU you send in, the Actor returns one result row containing:

- **`selectedCandidate`** — the single AliExpress product accepted as a high-confidence match (or `null` if none passed the AI judgment).
- **`candidates`** — up to 20 AliExpress candidates retrieved for the SKU (id, title, image, product URL).
- **`openClipRanking`** — image+title similarity ranking (OpenCLIP ViT-B/32) for the candidates.
- **`top5Judgments`** — the AI dual-judgment verdict for the top 5 candidates.
- **`retrievalOutcome`** — `success`, `no-result`, `failed`, `skipped`, or `stop-no-go`.
- **`complete`**, **`stopReason`**, **`degradations`** — per-SKU status and diagnostics.

Run-level records are written to the key-value store: `SUMMARY`, `CALL_LEDGER`, `CHARGE_LEDGER`, and `OUTPUT`.

***

### Coverage — read this before you run

**Roughly half of 1688 products have a usable AliExpress equivalent.** On a frozen 100-SKU cross-category test, about **50%** of source SKUs produced a usable AliExpress candidate in the top 5.

This is **not a limitation of the AI** — 1688 and AliExpress are different catalogs. 1688 carries many white-label, factory, and China-domestic items that simply are not listed on AliExpress (a retail-facing subset). Coverage depends on whether the product actually exists on AliExpress.

What the AI **does** guarantee:

- **Match quality** — when a match is returned, it has passed a vision + LLM dual judgment, so you get very few false positives.
- **Honest nulls** — when no candidate is good enough, you get `selectedCandidate: null` with a clear reason instead of a forced, low-quality guess.
- **Retrieval stability** — the AliExpress query layer returns a terminal answer (a match, or a confirmed "no equivalent") for essentially every SKU.

We never claim "guaranteed same product" or a near-100% hit rate. **You only pay for SKUs we actually deliver a result for** (see Pricing).

**AliExpress search works best in English.** 1688 titles are usually Chinese, and a Chinese query returns loosely related results. For best recall, send a short **English** `searchQuery` (e.g. `"baking tools"`) — it overrides the title as the search term. If you only send a Chinese `title` with no `searchQuery`, recall drops well below the ~50% above.

***

### Input

```json
{
  "products": [
    {
      "sourceSkuId": "1688-974333356844",
      "title": "Silicone Scraper Integrated Spatula Spatula Food Grade Baking Tools Cake Cutter Cream Scraper Home Shovel",
      "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01FLMKAx25xePqKFZFQ_!!2218359047593-0-cib.jpg",
      "searchQuery": "baking tools",
      "leafCategory": "baking-tools"
    }
  ]
}
```

| Field | Required | Notes |
| --- | --- | --- |
| `products` | yes | 1–100 items. |
| `products[].sourceSkuId` | yes | Stable identifier for the source 1688 product. |
| `products[].title` | yes | Source product title (Chinese is fine — see the note above). |
| `products[].imageUrl` **or** `products[].imageBase64` | yes | Provide **exactly one**. `imageUrl` must be HTTPS. |
| `products[].searchQuery` | no | Overrides the query used to search AliExpress. Recommended for best recall. |
| `products[].leafCategory` | no | Category hint used by the category-fallback retrieval step. |

`maxTotalCostUsd` is an internal safety ceiling for the run's own external cost — it is **not** your bill.

***

### How the AI pipeline works

1. **Retrieve** — query the official AliExpress Affiliate API (`aliexpress.affiliate.product.query`), 1 request/sec, with a category-fallback step, capped at 20 candidates per SKU.
2. **Rank (vision)** — score every candidate against the source image and title with OpenCLIP ViT-B/32 (`0.8 × image similarity + 0.2 × title overlap`).
3. **Judge (LLM)** — send the top 5 to a vision-capable LLM for a **two-pass judgment** (first read + independent confirmation); only a candidate both passes agree on is marked "high".
4. **Select** — the first high-confidence candidate becomes `selectedCandidate`; if none qualifies, the result is an honest `null`.

The run checkpoints continuously and resumes safely after a migration or timeout without re-charging or re-doing completed SKUs.

***

### Pricing (pay-per-event)

- **No startup fee. Failed runs cost $0.**
- On a successfully completed run you pay a small **base fee** once, plus a **per-delivered-result fee**.
- A SKU is a *delivered result* only when we return a terminal answer for it (a match, or a confirmed "no AliExpress equivalent"). SKUs we could not process are **not** charged.

| Event | When it's charged |
| --- | --- |
| `run-base-fee` | Once per successful run that delivered at least one result. |
| `sku-result` | Once per delivered SKU result — **this includes a confirmed "no AliExpress equivalent"**, because you are paying for the AI-verified decision (match or no-match), not for a match. SKUs we could not process are never charged. |

You are paying for an **AI-verified decision per SKU** (vision + LLM), not for raw scraped rows. Charges settle only at the end of a completed run and are idempotent across resume.

***

### Limits & compliance

- Up to **100 SKUs per run**.
- AliExpress data comes **only** from the official Affiliate API.
- Source images must be HTTPS URLs or Base64.
- Results reflect the AliExpress catalog at run time; availability and prices change.

***

### FAQ

**How is this different from a reverse image search on AliExpress?** Reverse image search hands you 20–100 visually similar products and leaves the filtering to you. This Actor uses image similarity as just one signal (OpenCLIP), then asks an LLM (DeepSeek) to actually verify whether a candidate is the *same* product — same features, same function, same target user — and returns a single verified match.

**Why didn't SKU X find a match?** The product likely isn't listed on AliExpress, or the title/image was too generic. Add a focused English `searchQuery` to improve recall.

**Do I pay if nothing matches?** You pay per *delivered result* (which includes a confirmed "no equivalent" — itself useful information). You never pay for a failed run or for SKUs that couldn't be processed.

**Why can `selectedSkuCount` be lower than `completeSkuCount`?** `completeSkuCount` counts every SKU that reached a reliable terminal answer: either a verified match or a confirmed no-equivalent. `selectedSkuCount` counts only the subset with a non-null `selectedCandidate`. For example, `completeSkuCount: 1` with `selectedSkuCount: 0` means the SKU was fully processed and no suitable AliExpress equivalent passed verification.

**Is AliExpress scraped?** No. Retrieval is 100% the official AliExpress Affiliate API — no scraping, no CAPTCHA bypass, no reverse-engineered endpoints.

**My 1688 titles are in Chinese — will this work?** Yes, that's the intended case. Pass the Chinese `title` and a short English `searchQuery`. The English query drives AliExpress retrieval; the Chinese title and image drive AI verification.

**Can I send images directly?** Yes — use `imageBase64` instead of `imageUrl`.

#### How do I find the AliExpress equivalent of a 1688 product?

Send the 1688 product's title + image and the Actor returns the single AI-verified AliExpress equivalent (or a confirmed no-equivalent), not a candidate list to sort.

#### Can I match a 1688 product photo to AliExpress?

Yes. The photo drives OpenCLIP image ranking and the LLM confirmation. If you only have a photo and no 1688 source yet, the **[1688 Image Search Scraper](https://apify.com/crawleast/1688-image-search-scraper)** finds the 1688 product first; then this Actor maps it to AliExpress.

#### Can I bulk match 1688 SKUs to AliExpress?

Yes. Submit up to 100 source products in `products`. Each SKU receives an independent terminal result: one verified equivalent or a confirmed no-equivalent.

#### Can I check whether a private-label product already sells on AliExpress?

Yes. Provide the source product's title and image. A verified match indicates that the same or a genuinely substitutable product is already listed; a no-equivalent result means none of the retrieved candidates passed the dual judgment.

#### Does this return an AliExpress price band?

No. This Actor verifies product identity; it does not calculate a price band. The selected result includes the AliExpress product URL so you can inspect current listing prices directly.

#### Can I use this as an AliExpress product finder?

Yes, when you start with a known 1688 product. It is not a general keyword scraper: it finds and verifies the closest AliExpress equivalent to the supplied source product.

# Changelog

This Actor's version history is a separate document: https://apify.com/crawleast/1688-aliexpress-product-matcher/changelog.md

# Actor input Schema

## `products` (type: `array`):

Each product must provide exactly one image field: imageUrl or imageBase64. Providing neither or both is invalid.

## `maxTotalCostUsd` (type: `number`):

Internal safety limit for the run's own external processing cost. The run stops before it could exceed this. This is not your bill.

## Actor input object example

```json
{
  "products": [
    {
      "sourceSkuId": "1688-541368916646",
      "title": "Bakery Baking Tools Pineapple Printing/Pineapple Bread Mould Engraving Mould West Point Printing Mould Wholesale",
      "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01m7BY4E1N0FdgZ5Pws_!!2711711507-0-cib.jpg",
      "searchQuery": "baking tools",
      "leafCategory": "baking-tools"
    }
  ],
  "maxTotalCostUsd": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `callLedger` (type: `string`):

No description

## `chargeLedger` (type: `string`):

No description

## `output` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "products": [
        {
            "sourceSkuId": "1688-541368916646",
            "title": "Bakery Baking Tools Pineapple Printing/Pineapple Bread Mould Engraving Mould West Point Printing Mould Wholesale",
            "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01m7BY4E1N0FdgZ5Pws_!!2711711507-0-cib.jpg",
            "searchQuery": "baking tools",
            "leafCategory": "baking-tools"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawleast/1688-aliexpress-product-matcher").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "products": [{
            "sourceSkuId": "1688-541368916646",
            "title": "Bakery Baking Tools Pineapple Printing/Pineapple Bread Mould Engraving Mould West Point Printing Mould Wholesale",
            "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01m7BY4E1N0FdgZ5Pws_!!2711711507-0-cib.jpg",
            "searchQuery": "baking tools",
            "leafCategory": "baking-tools",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("crawleast/1688-aliexpress-product-matcher").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "products": [
    {
      "sourceSkuId": "1688-541368916646",
      "title": "Bakery Baking Tools Pineapple Printing/Pineapple Bread Mould Engraving Mould West Point Printing Mould Wholesale",
      "imageUrl": "https://cbu01.alicdn.com/img/ibank/O1CN01m7BY4E1N0FdgZ5Pws_!!2711711507-0-cib.jpg",
      "searchQuery": "baking tools",
      "leafCategory": "baking-tools"
    }
  ]
}' |
apify call crawleast/1688-aliexpress-product-matcher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawleast/1688-aliexpress-product-matcher"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NLd6DVscTbCNfh4vE/builds/Yp8w61CgQcB0Bazzj/openapi.json