Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-zhihuiya-patent-image-search

ecommerce.zhihuiya-patent-image-search

Verified

Perform visual similarity search for design patents using an image URL, with filtering by country, legal status, date ranges, Locarno classification, and assignee. Supports design patent types only (type D). Triggered when users mention patent image search, design patent search, search patent by image, visual patent lookup, patent similarity detection, patent image matching, or design patent infringement check. Even if the user does not explicitly mention "patent image," this skill should be triggered whenever the need involves searching for similar design patents through an image. For utility model patents, use ecommerce.Nexscope-utility-patent-image-search instead.

FileKindSize
SKILL.mdskill md9.5 KB
manifest.jsonconfig551 B
references/api.mdmarkdown10.3 KB
scripts/upload_image.pyscript9.6 KB
scripts/zhihuiya_patent_image_search.pyscript6.2 KB

references/api.md

View on GitHub
# Nexscope Patent Image Search API Reference

## Request Specification

- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/zhihuiya/patentImageSearch`
- **Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`; read api_key from `nexscope_AGENT_API_KEY` or `nexscopeAGENT_API_KEY`. If neither is configured, follow the authentication and credits guidance in SKILL.md.

## Request Parameters

POST Body (JSON):

### Required Parameters

| Parameter | Type | Required | Description |
|------|------|------|------|
| url | string | Yes | Image URL (maximum 1000 characters) |
| patentType | string | Yes | Patent type: `D` (design patent); this Skill fixes it to `D` (gateway default `D`). |
| model | integer | Yes | Image search model. Design patents: `1` (smart association, recommended), `2` (search this image); utility model patents: `3` (match shape), `4` (match shape/pattern/color, recommended) |

### Optional Parameters

| Parameter | Type | Required | Description |
|------|------|------|------|
| country | string | No | Patent office (country/organization/region codes), separated by commas, e.g., `CN,US,JP`. Omit to search all patent offices |
| loc | string | No | LOC classification (Locarno classification numbers); combine multiple numbers with AND/OR/NOT |
| legalStatus | string | No | Patent legal status, comma-separated. Values: `1` (published), `2` (substantive examination), `3` (granted), `8` (avoidance of duplicate grants), `11` (withdrawn), `12` (withdrawn - unspecified type), `17` (withdrawn - deemed withdrawn), `18` (withdrawn - voluntarily withdrawn), `13` (rejected), `14` (fully revoked), `15` (term expired), `16` (annual fee unpaid), `21` (rights restored), `22` (rights terminated), `23` (partially invalidated), `24` (application terminated), `30` (abandoned), `19` (abandoned - deemed abandoned), `20` (abandoned - voluntarily abandoned), `25` (abandoned - unspecified type), `222` (PCT not entered a designated state - within the designation period), `223` (PCT entered a designated state - within the designation period), `224` (PCT entered a designated state - designation period expired), `225` (PCT not entered a designated state - designation period expired) |
| simpleLegalStatus | string | No | Simplified patent legal status, comma-separated. Values: `0` (invalid), `1` (valid), `2` (pending), `220` (PCT designation period expired), `221` (within the PCT designation period), `999` (unconfirmed) |
| assignees | string | No | Applicant (patent holder); maximum 1000 characters |
| applyStartTime | string | No | Patent application start date; format: `yyyyMMdd` |
| applyEndTime | string | No | Patent application end date; format: `yyyyMMdd` |
| publicStartTime | string | No | Patent publication start date; format: `yyyyMMdd` |
| publicEndTime | string | No | Patent publication end date; format: `yyyyMMdd` |
| limit | integer | No | Number of patents to return, 1-100. Default: `10` |
| offset | integer | No | Offset, 0-1000. Default: `0` |
| field | string | No | Result sort field: `SCORE` (relevance), `APD` (application date), `PBD` (publication date), or `ISD` (grant date). Default: `SCORE` |
| order | string | No | Applies when field is APD/PBD/ISD: `desc` (descending) or `asc` (ascending). Default: `desc` |
| lang | string | No | Preferred title language: `original` (original patent title), `cn` (Chinese translation), or `en` (English translation). Default: `original` |
| preFilter | integer | No | Whether to enable country/LOC pre-filtering: `1` (enabled), `0` (disabled). Default: `1` |
| stemming | integer | No | Whether to enable stemming: `1` (enabled), `0` (disabled). Default: `0` |
| mainField | string | No | Main patent fields, including title, abstract, claims, specification, publication number, application number, applicants, inventors, and IPC/UPC/LOC classification numbers (maximum 1000 characters) |
| includeMachineTranslation | boolean | No | Include machine-translated data in the search |
| scoreExpansion | boolean | No | Score expansion |
| isHttps | integer | No | Image URL protocol: `1` (return https), `0` (return http). Default: `0` |
| returnImgId | boolean | No | Whether to return img_id. Default: `false` |

**Note**:
- `model` must match `patentType`: models 1-2 are for design patents (`D`); models 3-4 are for utility model patents (`U`)

## Nexscope response envelope

These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.

`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.

Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.

```json
{"code":0,"msg":null,"data":{}}
```

Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.

## Response Structure

| Field | Type | Description |
|------|------|------|
| total | integer | Number of records returned in this request |
| allRecordsCount | integer | Total matching records in the database |
| data | array | List of matching patent records |
| columns | array | Rendering column definitions |
| type | string | Rendering style |
| costToken | integer | Tokens consumed |

### Patent Record Fields (Each Record in `data`)

| Field | Type | Description |
|------|------|------|
| patentId | string | Similar patent ID |
| patentPn | string | Similar patent number |
| apno | string | Application number |
| title | string | Patent title |
| inventor | string | Inventor |
| originalAssignee | string | Original applicant |
| currentAssignee | string | Current applicant |
| authority | string | Patent office (country code) |
| url | string | URL of the similar patent drawing |
| score | number | Similarity score (higher scores mean greater similarity; applies only when field is `SCORE`) |
| loc | array | LOC classification (Locarno classification numbers) |
| locMatch | integer | Whether a high-weight LOC matches: `1` (match), `0` (no match). Applies only when model=1 and field=SCORE |
| apdt | integer | Application date (timestamp) |
| pbdt | integer | Publication date (timestamp) |
| imgId | string | Patent drawing img_id (returned only when `returnImgId` is true) |

## curl Examples

```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/zhihuiya/patentImageSearch \
  -H "Authorization: $nexscopeAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product-image.jpg",
    "patentType": "D",
    "model": 1,
    "country": "CN,US",
    "limit": 20,
    "lang": "cn"
  }'
```

### Response Example

```json
{
  "total": 20,
  "allRecordsCount": 1523,
  "data": [
    {
      "patentId": "abcdef123456",
      "patentPn": "CN305123456S",
      "apno": "CN202130123456.7",
      "title": "台灯",
      "inventor": "张三",
      "originalAssignee": "示例公司",
      "currentAssignee": "示例公司",
      "authority": "CN",
      "url": "http://images.zhihuiya.com/patent/12345.jpg",
      "score": 0.95,
      "loc": ["26-05"],
      "locMatch": 1,
      "apdt": 1640995200000,
      "pbdt": 1656633600000
    }
  ],
  "columns": [],
  "type": "patent_image",
  "costToken": 100
}
```

## Error Codes

HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.

### Recovery guidance

| Condition | Action |
|---|---|
| Authentication failed | HTTP 401 or authorized error: follow the authentication and credits guidance in SKILL.md. |
| - | HTTP 402: follow the authentication and credits guidance in SKILL.md. |

## Feedback API

> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.

- **POST** `https://skill-api.nexscope.com/api/v1/public/feedback`
- **Content-Type:** `application/json`

```json
{
  "skillName": "nexscope-xxx-xxx",
  "sentiment": "POSITIVE",
  "category": "OTHER",
  "content": "Results were accurate, user was satisfied."
}
```

**Field rules:**
- `skillName`: Use this skill's `name` from the YAML frontmatter
- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)
- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`
- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise

## API Key request rate and retries

All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.

HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall