This skill performs visual product searches on the 1688 platform using an image URL, helping cross-border sellers find visually similar supplier products for sourcing.
Core Concepts
1688 Image Search uses visual recognition to find products with similar appearance on the 1688 wholesale marketplace. It returns supplier product data including title, price, minimum order quantity, monthly sales, repurchase rate, trade score, and seller identity badges.
Data Fields
| Field | Description |
|---|---|
| offerId | Product ID on 1688 |
| title | Product title |
| imageUrl | Product main image |
| price | Wholesale price (CNY) |
| consignPrice | Dropship price (CNY) |
| salesQuantity | Monthly sales volume |
| estimatedSalesAmount | Estimated monthly revenue |
| quantityBegin | Minimum order quantity |
| repurchaseRate | Repurchase rate |
| tradeScore | Product trade score |
| compositeServiceScore | Composite service experience score |
| sellerIdentities | Seller identity (Super Factory/Strength Merchant/TrustPass member) |
| offerIdentities | Product badge (Strictly Selected) |
| sendGoodsAddressText | Shipping origin |
| deliveryTime | Delivery time (24/48 hours) |
| isOnePsale | Supports dropshipping (Yes/No) |
| isJxhy | Premium sourcing (Yes/No) |
| hasPromotion | Has promotion (Yes/No) |
| isPatentProduct | Patent product (Yes/No) |
Parameter Guide
Image Rules:
- Only png, jpg, jpeg formats are supported. webp, gif, and other formats are NOT supported.
- Base64 string must be pure encoded content WITHOUT the
data:image/jpeg;base64,prefix. - Image source — one of imageUrl, imageBase64, or imageId must be provided (at least one required).
| Parameter | Required | Default | Description |
|---|---|---|---|
| imageUrl | Conditional | - | Public image URL (max 1000 chars). Only png/jpg/jpeg formats supported |
| imageBase64 | Conditional | - | Pure Base64 encoded image string, without data:image/...;base64, prefix. Only png/jpg/jpeg supported |
| imageId | Conditional | - | 1688 image ID from previous search result (speeds up pagination) |
| page | No | 1 | Page number, starting from 1 |
| pageSize | No | 20 | Results per page (1-50) |
| priceStart | No | - | Min price filter (CNY) |
| priceEnd | No | - | Max price filter (CNY) |
| filter | No | - | Filter conditions, comma-separated (see supported filters below) |
| sort | No | {"monthSold":"desc"} | Sort as JSON: {field: direction} (see supported sort fields below) |
| keyword | No | - | Keyword to further filter results |
| productCollectionId | No | - | Product collection ID (see supported IDs below) |
Supported Filters
Multiple filters can be combined with commas (e.g. 1688Selection,totalEpScoreLv1,qrr0).
| Filter Value | Description |
|---|---|
| 1688Selection | 1688 Strictly Selected |
| certifiedFactory | Certified Factory |
| totalEpScoreLv1 | Overall experience score 5 stars |
| totalEpScoreLv2 | Overall experience score 4 stars |
| totalEpScoreLv3 | Overall experience score 3 stars |
| totalEpScoreLv4 | Overall experience score 2 stars |
| qrr0 | No quality refunds |
| qrr1 | Quality refund rate <1% |
| qrr5 | Quality refund rate <5% |
| qrr10 | Quality refund rate <10% |
| shipInToday | Same-day shipping |
| shipIn24Hours | 24-hour shipping |
| shipIn48Hours | 48-hour shipping |
| noReason7DReturn | 7-day no-reason returns |
| isOnePsale | Dropshipping |
| isOnePsaleFreePost | Dropshipping with free shipping |
| new7 | New product within 7 days |
| new30 | New product within 30 days |
| isQqyx | Global Strictly Selected |
| JPFL | Japan dedicated line |
| USFL | US dedicated line |
| KRFL | South Korea dedicated line |
| VNFL | Vietnam dedicated line |
| SAFL | Saudi Arabia dedicated line |
| RUFL | Russia dedicated line |
| KZFL | Kazakhstan dedicated line |
| HKFL | Hong Kong dedicated line |
| MOFL | Macau dedicated line |
| TWFL | Taiwan dedicated line |
Supported Sort Fields
| Field | Direction | Description |
|---|---|---|
| price | asc/desc | Price ascending/descending |
| monthSold | asc/desc | Monthly sales ascending/descending |
| rePurchaseRate | asc/desc | Repurchase rate ascending/descending |
Sort format example: {"price":"asc"} for price low to high.
Supported Product Collection IDs
| ID | Usage |
|---|---|
| 262105288 | Cross-border supply pool |
| 262105286 | Cross-border supply pool |
| 262105253 | Cross-border supply pool |
| 262105281 | Cross-border supply pool |
| 262105280 | Cross-border supply pool |
| 262105277 | Cross-border supply pool |
| 262105276 | Cross-border supply pool |
| 262105274 | Cross-border supply pool |
| 262105269 | Cross-border supply pool |
| 262185282 | Cross-border supply pool |
How to call
- API endpoint：
POST /alibaba1688/imageSearch(for full parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/alibaba1688_image_search.py '<JSON 参数>' [--inline] - Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure or empty results, do not automatically try different keywords, page through, or change the postal code to probe continuously; if further retrieval is needed, first explain to the user that additional consumption will be incurred.
Output strategy (default script behavior)：
- Alwayswrite the full response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-search-by-image-<timestamp>.json（<cwd>is the working directory when the script runs, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error) - Response body ≤ 8 KB: after writing to disk, print the full JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, length of the largest list field + first 3 samples) - Add
--inlineto force full printing to stdout (also written to disk)
Data reading suggestions: First check the summary to determine whether it is sufficient; when specific fields are needed, prioritize using jqorConvertFrom-Json to extract from the saved json file on demand, avoiding bringing the entire JSON into context.
Resolve authentication and computing power issues
When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:
Abnormal situations
- API Key not configured: The environment variable
LINKFOX_AGENT_API_KEYis not configured, andLINKFOXAGENT_API_KEY。 - Response 401 or 402 status code
- Response indicates insufficient computing power or balance: The message contains "算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值", or content with a similar meaning.
Local Image Upload
This tool requires a publicly accessible image URL. If the user provides a local image file path, you must upload it first to obtain a public URL.
Run the upload script:
python scripts/upload_image.py /path/to/local/image.png
The script will return a public URL (valid for 24 hours) that can be used as the imageUrl parameter.
Usage Examples
1. Basic image search
在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg
2. Search with filters
在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg，查询第1页，筛选1688严选，并按价格从高到低排序
3. Search with sorting
在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，按价格从高到低排序
4. Paginated search
在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，查询第2页，每页50条
5. Price range filter
在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，价格区间10-100元
Display Rules
- Present data clearly: Show results in a structured table with key columns: product image, title, price, dropship price, monthly sales, minimum order quantity, repurchase rate, and seller identity
- Image display: When the response includes imageUrl for products, display them inline for visual comparison
- Price display: Always show price in CNY (¥) format
- Seller badges: Display seller identity badges (超级工厂/实力商家/诚信通会员) and product badges (严选) prominently
- Result count: Always inform the user of total results and current page/total pages
- Pagination hint: When more pages are available, suggest the user can request the next page
- Filter/sort limitation: If the user requests a sort or filter not in the supported list, do NOT attempt any workaround. Inform the user of the supported options
- No secondary processing: Results are real-time and not stored in a database, so secondary SQL/data processing is not available
Important Limitations
- Data real-time nature: Results are live searches, not stored in any database. Cannot use
_dataQuery_executeDynamicQueryfor secondary processing. - Logic constraint: If the user requests sort or filter conditions not in the preset supported list, do NOT call any other tool or logic to compensate.
- Image input: One of imageUrl, imageBase64, or imageId is required. For page > 1, prefer passing imageId from the first page result to speed up queries.
- Image format: Only png, jpg, jpeg are supported. webp, gif, and other formats will be rejected.
- Base64 format: The imageBase64 value must be the raw Base64 string only — do NOT include the
data:image/jpeg;base64,prefix. - Page size: Maximum 50 results per page.
User Expression & Scenario Quick Reference
Applicable -- Visual product sourcing scenarios on 1688:
| User Says | Scenario |
|---|---|
| "1688 image search" / "use an image to find 1688 supply sources" | Basic image search |
| "Help me find the same item as this image on 1688" | Find same-style products |
| "Cross-border factory sourcing, the image is..." | Cross-border supplier sourcing |
| "Does this Amazon product have supply sources on 1688" | Reverse sourcing from Amazon image |
| "Filter similar products from 1688 严选" | Filtered image search |
| "Sort by monthly sales to find similar supply sources" | Sorted image search |
| "View the results on page 2" | Pagination |
Not applicable -- Needs beyond 1688 image search:
- Text/keyword-based 1688 search (use 店雷达-1688选品库)
- 1688 product rankings/trending (use 店雷达-1688商品榜单)
- Amazon image search (use 亚马逊前端-以图搜图)
- Image generation or editing
- Product review analysis
- Price history or trend analysis
Boundary judgment: When users say "找货源" or "找同款", if they provide an image URL and the intent is to find visually similar products on 1688, this skill applies. If they want keyword-based search or ranking data on 1688, use the 店雷达 tools instead.
Computing power consumption rules
Consumes 5 computing power.
Users pay fees due to computing power consumption. Please fully evaluate: when this skill needs to be called frequently, or when the user's expectation of computing power consumption is insufficient, be sure to remind the user, and let the user decide whether to continue.
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
- The functionality or purpose described in this skill does not match actual behavior
- The skill's results do not match the user's intent
- The user expresses dissatisfaction or praise about this skill
- Anything you believe could be improved
Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.