# 1688 Image Search — Find Suppliers & Factories by Photo (`crawleast/1688-image-search-scraper`) Actor

1688 reverse image search for Amazon FBA sourcing, dropshipping and private label. Supplier prices and MOQ; optional English titles and landed-cost estimates.

- **URL**: https://apify.com/crawleast/1688-image-search-scraper.md
- **Developed by:** [Kyle Wang](https://apify.com/crawleast) (community)
- **Categories:** E-commerce, Lead generation, Agents
- **Features:** Limited permissions
- **Stats:** 5,488 total users, 831 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $4.50 / 1,000 image searches

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 Image Search Scraper — Find Suppliers by Photo

> **Photo → visually similar 1688 supplier candidates.**
> Find visually similar 1688 listings and supplier candidates for **Amazon FBA sourcing**. This reverse image search supports Amazon sourcing and product sourcing workflows, including China sourcing, dropshipping, private label and Shopify. Get up to **20 candidate listings per image**, with available card-level prices, MOQ and supplier signals. Results are **Chinese search cards by default**; visual similarity does not confirm the same product or its original factory. Enable `enrichDetails` for best-effort available details, English titles and landed-cost estimates; supplier legal names remain Chinese. **$0.005 per image returning matches + a $0.01 run base fee** (FREE/BRONZE; see [Pricing](#pricing-pay-per-event) for both modes).

### 🚀 Try this example

The current Store example searches two photos in card-only mode, with up to 5 candidates per photo. The input form itself is pre-filled with **one photo in card-only mode** (`enrichDetails: false`); its `maxResultsPerImage` default remains **20**, not 5:

```json
{
  "imageUrls": [
    "https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg",
    "https://cbu01.alicdn.com/img/ibank/O1CN01FCwJrl29btzNvQkHM_!!2235628087-0-cib.jpg_270x270xzq60.jpg"
  ],
  "maxImages": 2,
  "maxResultsPerImage": 5,
  "enrichDetails": false
}
```

At FREE/BRONZE prices, if both images return matches: $0.01 base fee + 2 × $0.005 = **$0.02**.

`enrichDetails` defaults to **false**. Set it to **true** to attempt detail retrieval for matched offers, including available SKUs, English titles, dropship scores and landed-cost estimates. Fields and translations are best-effort, not guaranteed for every match; supplier legal names stay Chinese. Successful details cost **$0.003 each at FREE tier until `2026-11-22T02:48:53.080Z`, then $0.0045**; undelivered details are not charged. The applied mode is recorded in `SUMMARY.enrichment` (`enriched` vs `card-only (enrichDetails=false)`).

**Optional single-photo enrichment example:**

```json
{
  "imageUrls": ["https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg"],
  "maxImages": 1,
  "maxResultsPerImage": 5,
  "enrichDetails": true
}
```

If the image returns matches and 5 details are delivered, the FREE-tier total is **$0.03 before `2026-11-22T02:48:53.080Z`** ($0.01 + $0.005 + 5 × $0.003) and **$0.0375 from that time** ($0.01 + $0.005 + 5 × $0.0045).

### 💸 Batch your photos: one run, one base fee

Searching several products? Put every photo into **one** run and set `maxImages` to the number of photos (up to 20; the default is 10, and extra images are dropped, never searched and never charged):

```json
{
  "imageUrls": [
    "https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg",
    "https://cbu01.alicdn.com/img/ibank/O1CN01FCwJrl29btzNvQkHM_!!2235628087-0-cib.jpg_270x270xzq60.jpg",
    "https://cbu01.alicdn.com/img/ibank/O1CN012OIY472D07vhk87GY_!!936828546-0-cib.jpg_270x270xzq60.jpg"
  ],
  "maxImages": 3,
  "maxResultsPerImage": 5,
  "enrichDetails": false
}
```

The $0.01 run base fee is charged once when at least one image actually delivers matches, not per image, so batching lowers your price per photo. Card-only, at FREE/BRONZE prices, when every image returns matches:

| How you call it | You pay | Per matched image |
| --- | --- | --- |
| 1 image per run | $0.005 + $0.01 base fee = $0.015 | **$0.015** |
| 20 images in one run | 20 × $0.005 + $0.01 base fee = $0.11 | **$0.0055** (~63% less) |

A successful single-image run also carries a `batchingTip` field in its dataset row and in `SUMMARY` as a reminder.

### ✅ What you get / ❌ what you avoid

| ✅ You get | ❌ What others charge you for (or fail at) |
| --- | --- |
| Pay-per-success: only images returning ≥1 match are billed ($0.005) | **Per-row billing from $3.00/1k rows elsewhere** — you pay for every row, even useless ones |
| Best-effort enrichment at **$0.003 per delivered detail until `2026-11-22T02:48:53.080Z`, then $0.0045** — undelivered details are not charged | Hidden start fees (`apify-actor-start`) on top of item pricing |
| Decision-support estimates when enriched: landed cost, dropship score, compliance hints | Field-stuffed dumps you still have to analyze by hand |
| **No 1688 account, no login, no cookies to babysit** | Solutions that break when your session expires |
| Undelivered searches/details and unprocessed overflow are **not billed**; partial runs pay only for successful deliveries | Reverse-image-search endpoints that quietly fail on a sizeable share of calls — you gamble on every call |
| Automatic compensation retry for transient detail failures (see Limits) | Silent partial deliveries you discover days later |

### Who it's for

- 📸 **Dropshipping, TikTok Shop & Shopify sellers** — screenshot a trending product, shortlist visually similar 1688 supplier listings and compare available prices
- 🛒 **Amazon FBA & private label sellers** — search a product photo (your own shot or the main image of a competitor's ASIN), compare up to 20 supplier candidates per photo; opt into enrichment for available MOQ ladders and landed-cost estimates before buying samples
- 🕵️ **Sourcing agents & China sourcing teams** — turn client photos into supplier shortlists with trust signals (years on 1688, Super Factory badge, repeat-buyer rate)
- 🤖 **AI agents & pipelines** — clean JSON in/out, API-first, built to be called by your automation (see [Copy to your AI assistant](#copy-to-your-ai-assistant))
- 🔍 **Price intelligence** — track factory prices of products you already sell via `offerIds` detail-only mode

### Trust at a glance

| What we commit to | How it works here |
| --- | --- |
| Pay only for delivered results | No matched images in image mode, or no delivered details in `offerIds` mode, costs **$0.00**. Partial success is billed only for successful deliveries |
| No hidden usage fees | Pure pay-per-event pricing; proxy and platform compute costs are included, never passed through |
| Honest degradation | Check `SUMMARY` for per-image status, billing-event records and reported shortfalls |
| Subscriber discounts | Up to **−10%** on image-search events (SILVER −4%, GOLD and above −10%) |
| MCP / agentic-payment ready | Input, dataset, key-value-store and output schemas are all declared — machines can validate the contract before calling |
| Issue support | Open an Issue with the run ID and symptoms for troubleshooting |
| Live reliability stats | See this Store page's live platform run success rate and volume; run success is not a per-image or full-delivery guarantee |

### One-click examples

Skip the input form — these public tasks run proven configurations in one click:

- **[Quick Start — photo to suppliers](https://apify.com/crawleast/1688-image-search-scraper/1688-image-search-quick-start)** — one photo, up to 20 visually similar listings with available prices
- **[Offer ID quick lookup](https://apify.com/crawleast/1688-image-search-scraper/1688-offer-quick-lookup)** — available enriched details for known 1688 product IDs, no image needed
- **[Find 1688 Supplier by Photo](https://apify.com/crawleast/1688-image-search-scraper/find-1688-supplier-by-photo)** — product shot in, supplier shortlist out
- **[TikTok Product Reverse Search](https://apify.com/crawleast/1688-image-search-scraper/tiktok-product-reverse-search)** — find visually similar 1688 listings for a viral product and compare prices
- **[Factory Price Check by Image](https://apify.com/crawleast/1688-image-search-scraper/1688-factory-price-check-by-image)** — compare available supplier prices from a screenshot

### Sample output

> **Reading the dataset:** with `enrichDetails: true`, runs write progressive snapshots into the append-only dataset as details arrive — **take the LAST `imageResult` block per query image** (the latest snapshot). Card-only runs flush once per image.

Results are grouped by query image (`type: "imageResult"`), with matches embedded in `results`; enriched runs can append multiple snapshots per image. Best-effort enrichment can produce an object like this (real output, arrays trimmed); available fields vary by listing:

```json
{
  "offerId": "692120494348",
  "detailLevel": true,
  "titleCn": "厂家批发 平板电脑保护套肩带 相机背带 音响背带",
  "titleEn": "Manufacturer Wholesale Tablet Case Shoulder Strap Camera Strap Speaker Strap",
  "detailUrl": "https://detail.1688.com/offer/692120494348.html",
  "price": { "min": 1.9, "max": 2.2, "currency": "CNY", "unit": "piece" },
  "moq": 1000,
  "quantityPrices": [
    { "price": 2.2, "minQuantity": 1000 },
    { "price": 2.0, "minQuantity": 5000 },
    { "price": 1.9, "minQuantity": 10000 }
  ],
  "stock": { "total": 1325250 },
  "city": "广东省深圳市",
  "supplier": {
    "companyName": "深圳市光明区兴凯鸿纺织商行",
    "sellerType": "superFactory",
    "isSuperFactory": true,
    "scores": { "service": "4.5", "repeatRate3m": "29.41%" }
  },
  "supplierRepeatRate3m": 0.2941,
  "weightKg": null,
  "dropshipReadyScore": 44,
  "dropshipGrade": "F",
  "dataQuality": "minimal",
  "estLandedCostUsd": {
    "unitCostUSD": 0.26,
    "internationalShippingUSD": 2.72,
    "totalLandedCostUSD": 3.35,
    "suggestedRetailPriceUSD": 10.05,
    "estimatedMarginPercent": 66.7
  },
  "compliance": {
    "targetMarket": "US",
    "suggestedCertifications": ["CPSC compliance"],
    "riskFlags": []
  },
  "scrapedAt": "2026-08-23T17:23:17.977Z"
}
```

Without enrichment you get **Chinese search cards**. Available card fields can include `offerId`, `similarityRank`, `title` (Chinese), `priceYuan`, `consignPriceYuan` (dropship price), `moq`, `bookedCount` (demand), `supplier` (years on platform, factory flags, composite score), `imageUrl`, `detailUrl`.

Every field is documented in the **dataset schema** (see the *Overview* view in the Console results table).

### How to run

1. **Paste a product photo URL** into `imageUrls` (or upload base64 via `imagesBase64`).
2. Set `maxResultsPerImage` (up to 20 matches per image).
3. Optional: switch on `enrichDetails` for best-effort available details and estimates.
4. Start the run — results land in the default dataset, grouped by image; enriched runs can append snapshots.
5. Re-fetch known products via `offerIds` (detail-only mode, up to 400).

API:

```bash
curl -X POST "https://api.apify.com/v2/acts/crawleast~1688-image-search-scraper/runs" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrls": ["https://example.com/product-photo.jpg"],
    "maxResultsPerImage": 20,
    "enrichDetails": true,
    "targetMarket": "US"
  }'
```

### Input reference

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `imageUrls` | string\[] | — | Public product photo URLs (jpg/png/webp). Each yields up to `maxResultsPerImage` matches. |
| `imagesBase64` | array | — | Base64 alternative: raw string or `{"base64": "...", "fileName": "x.jpg"}`. Mixable with `imageUrls`. |
| `offerIds` | string\[] | — | Detail-only mode: fetch available details for up to 400 known 1688 offer IDs. Overrides images; see Pricing for the base fee and delivered-detail fees. |
| `maxImages` | int | `10` | Cap on input images (max 20). Extras are dropped and never charged. |
| `maxResultsPerImage` | int | `20` | Matches per image (1–20), in similarity order. |
| `enrichDetails` | bool | `false` | Attempt best-effort detail enrichment ($0.003 per delivered detail at FREE tier until `2026-11-22T02:48:53.080Z`, then $0.0045). |
| `targetMarket` | enum | `US` | `US` / `EU` / `UK` / `AU` / `global` — drives landed cost & compliance hints. |
| `maxTotalChargeUsd` | number | `2` | Charge budget (min 0.04). Check `SUMMARY` for budget stops and delivered results. |

**Migrating from another actor?** Common aliases get minimal support: `imageUrl` and `images` are mapped to `imageUrls`; `imageFile` is routed by value shape (data:URI / pure base64 → `imagesBase64`, URL → `imageUrls`). Keyword fields like `query` are dropped with a logged warning — this Actor searches by **image**, not keywords. Unknown legacy fields are dropped with a logged warning, so old inputs never crash a run.

### Pricing (pay-per-event)

All-inclusive usage pricing: **$0.005 per image that actually delivers ≥1 match** (FREE/BRONZE), plus the delivered-detail price in the schedule below when requested. The **$0.01 run base fee** is charged once at completion: in image mode when ≥1 query image actually delivers matches; in `offerIds` mode when ≥1 detail is actually delivered. **No successful delivery = $0.00.** Partial runs pay only for successful deliveries; an overall `FAILED` status does not make already delivered work free.

> The "from $4.50 / 1,000" price shown on the Store page is the **GOLD subscription-tier** rate; on the FREE tier you pay $5 per 1,000 image-search events. This Store badge is unchanged because `image-search` remains the primary event and its prices do not change.

**Scheduled detail-price change:** the changeover is **`2026-11-22T02:48:53.080Z`**. Until then, the existing detail prices still apply; from that timestamp, only `detail-item` moves to the new schedule below. `image-search`, the $0.01 `run-base-fee`, the $0.04 minimum charge budget and the Store's primary event are unchanged. Each run's `SUMMARY.eventPricesUsd` records the actual unit prices applied, and `SUMMARY.eventPricesSource` records their source.

| Event | Price | When it's charged |
| --- | --- | --- |
| `run-base-fee` | **$0.01** | Once at completion if image mode delivers ≥1 matched image, or `offerIds` mode delivers ≥1 detail |
| `image-search` | **$0.005** | Per image search that actually delivers ≥1 match; never applies to `offerIds` mode |
| `detail-item` | **$0.003 → $0.0045** at FREE tier | Per enriched detail **actually delivered**; see the changeover and tier schedule |

**No platform start fee** — the only per-run charge is the $0.01 base fee under the delivery conditions above. **No charge** for failed image downloads, zero-match searches, risk-control blocks, undelivered details or unprocessed overflow. `offerIds` mode pays the base fee plus delivered-detail fees, not an image-search fee. Subscription discounts (image-search): SILVER −4%, GOLD/PLATINUM/DIAMOND −10% (discount depth capped at 10%).

**Detail-item subscription tiers** (per delivered detail):

| Tier | Before the changeover | From the changeover |
| --- | --- | --- |
| FREE | $0.003 | **$0.0045** |
| BRONZE | $0.0027 | **$0.00405** |
| SILVER | $0.0024 | **$0.0036** |
| GOLD | $0.0021 | **$0.00315** |
| PLATINUM | $0.0021 | **$0.00315** |
| DIAMOND | $0.0021 | **$0.00315** |

**Worked examples** (FREE tier; all stated searches/details delivered):

| Order | Before the changeover | From the changeover |
| --- | --- | --- |
| 1 image (card-only) | $0.01 + 1 × $0.005 = **$0.015** | **$0.015** (unchanged) |
| 10 images (card-only) | $0.01 + 10 × $0.005 = **$0.06** | **$0.06** (unchanged) |
| 20 images (card-only, the per-run maximum) | $0.01 + 20 × $0.005 = **$0.11** | **$0.11** (unchanged) |
| 1 offer ID (detail-only) | $0.01 + 1 × $0.003 = **$0.013** | $0.01 + 1 × $0.0045 = **$0.0145** |

The flat $0.01 base fee amortizes across the batch — the larger the run, the closer your effective per-image price gets to the raw $0.005.

**Optional enriched example — sourcing 10 products by photo** (FREE tier): if 10 images return matches ($0.05) and 200 unique details are delivered, the $0.01 base fee plus search and detail events totals **$0.66 before the changeover** (200 × $0.003 = $0.60) and **$0.96 from the changeover** (200 × $0.0045 = $0.90).

Compare: one hour of a sourcing agent browsing 1688 manually covers perhaps 5–10 products — and tells you nothing about landed cost or dropship readiness.

> **Best value: batch 10–20 images per run** (set `maxImages` to match; the default is 10) — one base fee when matches are delivered, one image-search charge per matched image, details only when you opt in. Larger successful batches amortize the base fee and the fixed cold-start cost over more results.

#### How this compares to typical reverse-image-search Actors

Other Actors also search 1688 by photo; the differences are structural:

| | **This Actor** | Typical single-image reverse-image-search |
| --- | --- | --- |
| Input per run | Up to **20 images** in one batch | Single image per call |
| Billing | Per delivered event ($0.005 matched image / delivered detail at the tier schedule above), plus the conditional $0.01 base fee; partial success is billed for delivered work | Per-row billing (commonly from $3.00 / 1k rows) |
| Run success rate | See live platform Store stats; a run-level metric, not a per-image or full-delivery guarantee | Judge from each Store page's live stats |
| Budget control | `maxTotalChargeUsd` per-run charge budget | Usually not offered |
| Enrichment | Optional best-effort available details and estimates: landed cost, dropship score, compliance hints | Search results only |

### Limits & caveats (read once, trust us more)

- **Dataset snapshot semantics.** Enrich-mode image runs write progressive full snapshots into the append-only dataset as details arrive. **Consumers should take the last `imageResult` block per query image**, not the last 20 rows globally. `SUMMARY.imageFlushCount` tells you how many snapshots were written. Card-only runs flush once per image.
- **Cross-image dedup & billing.** Detail targets are deduplicated by `offerId` across query images (measured on our 20-image benchmark: 20 images × 20 matches → **371 unique targets, 371/371 delivered and billed**, run MrWX8o2ZcMFXC2ZQ0). `detail-item` billing counts **unique delivered offers**, so when one offer appears under several of your photos, the card-level enriched count can exceed the billed count. Do not sum repeated enriched cards as billed details; the benchmark is not a zero-loss delivery guarantee.
- **Compensation retry.** If some details fail in the parallel pass, ONE automatic serial retry targets only the failed `offerIds` (deadline-permitting). It is billed only on actual delivery and reported in `SUMMARY.compensationRetry` (`triggered`, `offered`, `delivered`, `failed`).
- **Budget-aware stopping.** When `maxTotalChargeUsd` is reached, the run stops scheduling new work. Check dataset snapshots for delivered results and `SUMMARY.chargedEvents` / `SUMMARY.intendedEvents` for billing-event records; use platform charge records to verify actual charges. In-flight delivery is not guaranteed.
- **1688 risk control is real.** Rarely, 1688's anti-bot layer refuses queries (`status: "RISK_CONTROL"`). Those images are never charged; the run reports per-image status honestly instead of silently retrying forever.
- **Estimates are heuristics.** `estLandedCostUsd` (duty/shipping/platform rates) and `compliance` hints are informational starting points, not quotes or legal advice. Read `dropshipReadyScore` alongside `dataQuality` when listings omit evidence.
- **Chinese-first source.** 1688 is a domestic Chinese marketplace: original titles are Chinese (`titleCn`) and that field is authoritative. English titles (`titleEn`) are best-effort machine translations (free translation services with a domain dictionary fallback); `translationMethod` tells you which path produced each title. Supplier names stay in Chinese (as registered).
- **Run window.** Up to 20 images × 20 matches per run; large enriched orders (hundreds of details) take several minutes and run under a 40-minute platform window with budget-aware graceful stop.

### FAQ

**How much does it cost to search by image on 1688?**
In image mode, $0.005 per image that actually delivers at least one match (FREE/BRONZE), plus a $0.01 run base fee charged once at completion if any image delivered matches. No matched images means $0.00; partial success pays only for successful deliveries, even if the overall run ends `FAILED`. Optional enrichment is $0.003 per delivered detail at FREE tier until `2026-11-22T02:48:53.080Z`, then $0.0045. One matched image plus 5 delivered details costs **$0.03 before / $0.0375 after** that changeover; 10 matched images plus 200 unique delivered details costs **$0.66 before / $0.96 after**.

**Do I need a 1688 account or Chinese phone number?**
No. The Actor handles access internally; you provide only the photos (or offer IDs).

**Can I use it for Amazon FBA product research?**
Yes — reverse image search a product photo to shortlist visually similar 1688 supplier candidates and compare available prices and MOQ. With `enrichDetails`, available details may include landed-cost and margin estimates for your target market. A typical FBA / private label flow: photo → supplier shortlist → verify product identity and supplier → sample orders.

**Can I search by Amazon ASIN?**
Not directly — this Actor searches by image. Paste the main image URL of the ASIN's listing into `imageUrls` to search for visually similar 1688 supplier listings.

**What image formats work?**
JPEG, PNG and WebP up to ~1 MB each, via public URL (`imageUrls`) or base64 (`imagesBase64`). Screenshots from TikTok/Amazon/AliExpress work fine.

**What if an image returns no matches?**
`status: "OK"` with `matchCount: 0` and zero charge. Try a cleaner crop — product-only, plain background images match best.

**Why are some details missing fields?**
`dataQuality` tells you (`full` / `partial` / `minimal`). 1688 listings genuinely differ in what they publish (SKU tables, weight, video). What isn't published isn't invented.

**Can I fetch details for products I already found?**
Yes — `offerIds` mode takes up to 400 IDs and attempts available enriched details without image search. If at least one detail is delivered, it adds the $0.01 base fee once plus delivered-detail fees; no `image-search` charges. One delivered detail at FREE tier costs **$0.013 before `2026-11-22T02:48:53.080Z` and $0.0145 from that time**; no delivered details costs $0.00.

**How do I control spend?**
Set `maxTotalChargeUsd` (default $2). At the budget stop, inspect the dataset for delivered results. `SUMMARY.chargedEvents` and `SUMMARY.intendedEvents` record billing events; verify actual charges against platform charge records rather than assuming the summary is an exact invoice.

**How long does a run take?**
Card-only scans finish in ~30–90 seconds. Enriched runs add ~1 detail/second per identity pool; a 200-detail order typically completes in a few minutes.

**Is this legal?**
The Actor reads publicly available 1688.com listing data at normal browsing rates. Respect 1688's terms and applicable laws; you are responsible for how you use the data.

### For AI agents

Built to be called by software, not just clicked by people:

- **Complete output schema** — every delivered field (prices, MOQ, supplier signals, dropship score, landed cost, compliance) is typed and documented, so tool-calling loops can parse results without guesswork.
- **API-first** — one POST to `run-sync-get-dataset-items` returns the final dataset in a single call; no browser session, login or captcha step.
- **Batch by default** — put every photo you need into ONE run (`imageUrls`, up to 20) and set `maxImages` to that count; each extra run with matched images pays its own $0.01 base fee.
- **Agentic payments ready** — `maxTotalChargeUsd` sets a per-run charge budget, with machine-readable failure semantics in `SUMMARY`. No successful delivery costs $0; an overall failed run can still incur charges for delivered results. Inspect delivery and platform charge records when automating spend.

### Copy to your AI assistant

This Actor is **API-first and agent-ready**: JSON input/output, per-event billing with a charge budget, and machine-readable failure semantics — useful for MCP servers, n8n/Make flows, LangChain tools and autonomous sourcing agents.

Paste this into your AI assistant:

```text
Use the Apify Actor crawleast/1688-image-search-scraper to find Chinese
wholesale supplier candidates for product photos. Put ALL photos into ONE
run (up to 20) and set maxImages to the number of photos; each run pays a
$0.01 base fee only if matches are delivered. POST this JSON to
https://api.apify.com/v2/acts/crawleast~1688-image-search-scraper/run-sync-get-dataset-items?token=<APIFY_TOKEN>
body: {"imageUrls": ["<photo-url-1>", "<photo-url-2>"], "maxImages": 2,
"maxResultsPerImage": 20, "enrichDetails": true, "targetMarket": "US",
"maxTotalChargeUsd": 2}.
Take the last imageResult row per query image (the latest snapshot).
Report available landed-cost estimates, dropship grades and compliance
risk flags; do not assume every field is present or similar means identical.
```

`runs-sync-get-dataset-items` returns the final dataset in one call — perfect for tool-calling loops. For large enriched orders (hundreds of details), append `?timeout=900` (seconds) to the sync endpoint, or set your HTTP client timeout ≥ 15 minutes — otherwise the gateway may return 408 while the run keeps working in the background (poll `runs/{runId}` to recover).

### Related Actors

- **[1688 Product Scraper](https://apify.com/crawleast/1688-product-scraper)** — keyword research across any 1688 category: English titles, MOQ price ladders, landed cost, dropship scores and supplier signals. Found a factory by photo? Pull the whole category around it by English keyword.
- **[TikTok Shop Scraper](https://apify.com/crawleast/tiktok-shop-product-scraper)** — find TikTok Shop's viral products by keyword, then photo-search the winners here to find matching 1688 suppliers.

Pipeline: spot winners (TikTok Shop Scraper, or keyword research with 1688 Product Scraper) → screenshot them → source suppliers by photo (this Actor) → re-check finalists via `offerIds`.

### Reviews & changelog

Found a bug or have a wishlist? Open an **Issue** with the run ID and relevant symptoms so we can investigate.

If this run saved you time, a quick review on the Store page helps other buyers find it — 10 seconds, hugely appreciated.

Release history lives in the **Changelog** tab.

***

*Data is provided "as is" for research and sourcing decisions. Pricing, scores and compliance hints are heuristic estimates; verify independently before committing funds. Not affiliated with 1688.com / Alibaba Group.*

# Changelog

This Actor's version history is a separate document: https://apify.com/crawleast/1688-image-search-scraper/changelog.md

# Actor input Schema

## `imageUrls` (type: `array`):

Public URLs of product photos to search with (jpg/png/webp, ~1 MB or less each). Each image yields up to maxResultsPerImage visually similar candidate listings; similarity does not confirm the same product. An image-search charge applies only when that image actually delivers at least one match. Batch multiple URLs in one run and set maxImages to the number of images (up to 20) — image mode adds the $0.01 run base fee once when at least one image delivers matches, not per image. Example: a photo of a product you saw on TikTok/Amazon/AliExpress.

## `imagesBase64` (type: `array`):

Alternative to imageUrls when you have no public URL: base64-encoded images. Each entry is either a raw base64 string or {"base64": "...", "fileName": "product.jpg"}. Mixed use with imageUrls is supported.

## `offerIds` (type: `array`):

Skip image search and attempt available product details directly for these 1688 offer IDs (the numeric ID from a detail.1688.com/offer/<ID>.html URL). Overrides image inputs. A $0.01 run base fee applies once when at least one detail is actually delivered, plus the delivered-detail fee ($0.003 each at FREE tier until 2026-11-22T02:48:53.080Z, then $0.0045); no image-search fee. No delivered details = $0.00; partial success is billed only for delivered details plus that one base fee. Capped at 400 per run; extras are dropped and never charged.

## `maxImages` (type: `integer`):

Maximum number of input images to process (default 10). Set it to the number of images you pass, up to 20, to search them all in one run. Extras beyond this limit are truncated, never searched and never charged.

## `maxResultsPerImage` (type: `integer`):

How many matching listings to return per image, ordered by visual similarity.

## `enrichDetails` (type: `boolean`):

Attempt best-effort detail enrichment for matched offers using available fields: SKUs and stock, quantity-break price ladder, English title, weight, dropship-ready score, estimated landed cost (USD) and compliance hints. Fields and English translations are not guaranteed for every match; supplier legal names remain Chinese. Defaults to false (Chinese search cards). Billed $0.003 per detail actually delivered at FREE tier until 2026-11-22T02:48:53.080Z, then $0.0045; undelivered details are not charged.

## `targetMarket` (type: `string`):

Destination market used for the estimated landed cost (duty rate) and compliance certification hints on enriched details.

## `maxTotalChargeUsd` (type: `number`):

Pay-per-event charge budget for this run. When it is reached, the run stops scheduling new work; check the dataset and SUMMARY for delivered results and billing-event records. In image mode, the $0.01 base fee applies once when at least one image actually delivers matches. In offerIds mode, it applies once when at least one detail is actually delivered, plus delivered-detail fees and no image-search fee. No successful delivery = $0.00; partial success is charged for successful deliveries even if the run ends FAILED.

## Actor input object example

```json
{
  "imageUrls": [
    "https://example.com/screenshot-of-a-product.jpg"
  ],
  "imagesBase64": [
    {
      "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "fileName": "product.jpg"
    }
  ],
  "offerIds": [
    "802207808750"
  ],
  "maxImages": 10,
  "maxResultsPerImage": 20,
  "enrichDetails": false,
  "targetMarket": "US",
  "maxTotalChargeUsd": 2
}
```

# Actor output Schema

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

One row per query image: search status and the matching 1688 listings in similarity order — factory price, MOQ, booked demand and supplier trust signals; with enrichDetails=true each delivered match carries full details (SKUs, price ladder, English title, dropship score, estimated landed cost, compliance hints). Field meanings are described in the dataset schema (Overview view).

## `runSummary` (type: `string`):

Machine-readable run report stored under the SUMMARY key: charged vs intended PPE events, charged USD, per-image search outcomes, detail delivery counters and compensation-retry diagnostics.

# 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 = {
    "imageUrls": [
        "https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg"
    ],
    "imagesBase64": [],
    "offerIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawleast/1688-image-search-scraper").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 = {
    "imageUrls": ["https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg"],
    "imagesBase64": [],
    "offerIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("crawleast/1688-image-search-scraper").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 '{
  "imageUrls": [
    "https://cbu01.alicdn.com/img/ibank/15418323391_1847764777.jpg"
  ],
  "imagesBase64": [],
  "offerIds": []
}' |
apify call crawleast/1688-image-search-scraper --silent --output-dataset

```

## MCP server setup

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

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/4nHSiNhcVlyNqPfi2/builds/kil9DofjrqZReq7sP/openapi.json