Nexscope logo
Start free

1688 Search By Image API

REST API and MCP service documentation generated from server-side API definitions. Responses shown here are the direct payload returned by each API execution.

API selector
1688 Sourcing

API overview

Perform image-based product search on the 1688 platform. Use an image URL to find visually similar supplier products, returning title, price, minimum order quantity, monthly sales, repurchase rate, trade score, and seller identity.

Try this API
Endpoint
https://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run
MCP method
nexscope_1688_search_by_image

Authentication

All run endpoints require a user API key. Send it as a bearer token in the Authorization header.

Authorization: Bearer nk_xxxxxxxxxxxxxxxxx
Missing or invalid API keys return an authentication error. Manage keys from .
POSThttps://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run

Run an API

Request parameters documented by ecommerce.1688-search-by-image.

Slug1688-search-by-image
HeadersAuthorization: Bearer nk_...
Content-Type: application/json
Request bodyAPI-specific JSON object.
Response bodyDirect API response payload. No data/result wrapper is added.

Status codes

CodeDescription
200API executed successfully. Body is the direct response payload.
400Request JSON or required API parameters are invalid.
401API key is missing, invalid, or cannot be matched to a user.
5xxAPI execution or upstream service failed.

Example request

curl -X POST https://api.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run \
  -H "Authorization: Bearer nk_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{   "pageSize": 10,   "imageUrl": "https://m.media-amazon.com/images/I/61v6nYvQ7+L._AC_SL1500_.jpg",   "page": 1 }'
All categories/ 1688 Sourcing
POSThttps://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run

Run this API

Send a JSON request to execute this API and receive the direct response payload.

Open tester

Endpoint

MethodPOST
Pathhttps://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run
AuthBearer API key
Content-Typeapplication/json

Request body

NameTypeRequiredDescription
imageUrlstringoptional
图片URL地址，请确保图片URL有效且可公开访问。最大长度：1000。仅支持 png/jpg/jpeg 格式，不支持 webp/gif 等。imageUrl/imageBase64/imageId 三选一必填
Example: https://m.media-amazon.com/images/I/61v6nYvQ7+L._AC_SL1500_.jpg
imageBase64stringoptional
图片 Base64 编码字符串，为纯编码内容，不包含 data:image/jpeg;base64, 前缀。仅支持 png/jpg/jpeg 格式（imageUrl为空时使用）
imageIdstringoptional
图片ID（1688图片ID），以图搜图查询结果中也会返回，建议当分页 page>1 查询时带 imageId，加快响应速度
pageintegeroptional
页码，从1开始
Example: 1
pageSizeintegeroptional
每页返回的商品数量，最大不超过50
Example: 10
priceStartstringoptional
价格筛选起始值（人民币），如 10
priceEndstringoptional
价格筛选结束值（人民币），如 100
filterstringoptional
过滤条件，多个条件用逗号分隔。有效值见下方「支持的过滤条件」
sortstringoptional
排序条件，JSON格式 {排序字段: 排序方式}。有效字段：price、rePurchaseRate、monthSold；方式：asc/desc
keywordstringoptional
关键词，在结果中搜索
Example: phone case
productCollectionIdstringoptional
货盘ID，单选。有效值见下方「支持的货盘ID」
Example: example-id

Request example

{
  "pageSize": 10,
  "imageUrl": "https://m.media-amazon.com/images/I/61v6nYvQ7+L._AC_SL1500_.jpg",
  "page": 1
}

Response body

Returns the documented upstream API response directly without an additional wrapper.

NameTypeRequiredDescription
imageIdstringoptional
上传后的图片ID（分页查询时回传可加速）
Example: example-id
totalintegeroptional
本页商品数量
Example: 1
totalPageintegeroptional
总页数
Example: 1
sourceTypestringoptional
来源类型（固定值 "1688"）
typestringoptional
渲染样式（固定值 "productWorkbenches"）
columnsarrayoptional
渲染列定义
Example: []
costTokenintegeroptional
消耗 token
Example: 1
productsarrayoptional
商品列表（详见下方商品字段）
Example: []
offerIdstringoptional
商品ID
Example: example-id
asinstringoptional
商品编号（同 offerId）
Example: B072MQ5BRX
imageUrlstringoptional
商品图片
Example: https://example.com/image.jpg
titlestringoptional
商品标题
pricenumberoptional
批发价（元）
Example: 1
consignPricenumberoptional
一件代发价（元）
Example: 1
salesQuantityintegeroptional
月销售件数
Example: 1
estimatedSalesAmountnumberoptional
预估销售额
Example: 1
asinUrlstringoptional
商品链接
Example: B072MQ5BRX
products[].isOnePsalestringoptional
是否一件代发（是/否）
products[].isJxhystringoptional
是否精选货源（是/否）
products[].sellerIdentitiesstringoptional
商家身份（超级工厂/实力商家/诚信通会员）
products[].offerIdentitiesstringoptional
商品标（严选）
products[].repurchaseRatestringoptional
复购率
products[].tradeScorestringoptional
商品交易评分
products[].compositeServiceScorestringoptional
综合服务体验分
products[].sendGoodsAddressTextstringoptional
发货地
products[].deliveryTimestringoptional
发货时间（24/48小时）
quantityBeginintegeroptional
起批量
Example: 1
products[].hasPromotionstringoptional
是否有营销活动（是/否）
products[].promotionTypestringoptional
营销类型
products[].isPatentProductstringoptional
是否专利商品（是/否）
products[].isSelectstringoptional
跨境select货盘标识
products[].currencystringoptional
币种（固定值 "¥"）
sourceToolstringoptional
来源工具（固定值 "1688以图搜图"）
products[].dataTypestringoptional
数据类型（固定值 "monthlyData"）
errcodeintegeroptional
Upstream status code returned by the provider.
errmsgstringoptional
Upstream status message returned by the provider.
codestringoptional
Provider-specific status code.
msgstringoptional
Provider-specific status message.
messagestringoptional
Provider-specific message.
costTimeintegeroptional
Execution time reported by the upstream provider.
pageintegeroptional
Current page returned by the upstream provider.
pageSizeintegeroptional
Page size returned by the upstream provider.
pageItemCountintegeroptional
Item count on the current page returned by the upstream provider.
dataSnapshotMonthstringoptional
Data snapshot month returned by the upstream provider.

Response example

Direct response payload. No extra wrapper is added.

{
  "imageId": "example-id",
  "total": 1,
  "totalPage": 1,
  "columns": [],
  "costToken": 1,
  "products": [],
  "offerId": "example-id",
  "asin": "B072MQ5BRX",
  "imageUrl": "https://example.com/image.jpg",
  "price": 1,
  "consignPrice": 1,
  "salesQuantity": 1,
  "estimatedSalesAmount": 1,
  "asinUrl": "B072MQ5BRX",
  "quantityBegin": 1
}

Responses

CodeDescription
200API executed successfully. Body is the direct response payload.
400Request JSON or required API parameters are invalid.
401API key is missing, invalid, or cannot be matched to a user.
5xxAPI execution or upstream service failed.

Data source, freshness, and limitations

Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.

Related APIs

1688 Product Billboard

Query 1688 product bestseller billboard data for sourcing discovery and wholesale product research.

1688 Product Search

Search and analyze products on the Chinese 1688 wholesale platform (Alibaba domestic B2B market) for sourcing, supplier discovery, and product selection.

MCP

Use the MCP endpoint when an agent needs to discover and call API tools with JSON-RPC.

GET /api/skill-api/v1/mcp
POST /api/skill-api/v1/mcp
Authorization: Bearer nk_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Call a tool

{
  "jsonrpc": "2.0",
  "id": "tool-call-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_1688_search_by_image",
    "arguments": {
      "pageSize": 10,
      "imageUrl": "https://m.media-amazon.com/images/I/61v6nYvQ7+L._AC_SL1500_.jpg",
      "page": 1
    }
  }
}

Online test

Execute the current API with your API key and JSON payload.

Try it

Send a real request with the same contract shown in the reference.

Endpoint
https://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run
MCP method
nexscope_1688_search_by_image
cURL
curl -X POST \
  https://claw-callback.nexscope.ai/api/skill-api/v1/skills/1688-search-by-image/run \
  -H "Authorization: Bearer nk-..." \
  -H "Content-Type: application/json" \
  -d '{ "pageSize": 10, "imageUrl": "https://m.media-amazon.com/images/I/61v6nYvQ7+L._AC_SL1500_.jpg", "page": 1 }'
Response
No response yet. Run the request to see the response here.