外观专利检测 · 任务管理

外观专利检测的生命周期管理。

历史列表

GET /ip/patent/design/histories

查询参数

参数	类型	必填	说明
`page`	`integer`	✅	页码，从 1 开始
`pageSize`	`integer`	✅	每页条数

cURLPython

curl -X GET "https://api.trohub.com/v2/ip/patent/design/histories?page=1&pageSize=20" -H "Authorization: Bearer YOUR_API_KEY"

import requests

url = "https://api.trohub.com/v2/ip/patent/design/histories?page=1&pageSize=20"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.get(url, headers=headers)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "items": [
      {
        "taskID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
        "title": "2026 秋季批次 A",
        "submittedVia": "api",
        "status": "completed",
        "error": "string",
        "createdAt": "2026-10-19T12:00:00+08:00",
        "imageCount": 1,
        "riskLevel": "low",
        "riskCounts": {
          "high": 0,
          "medium": 0,
          "low": 0,
          "tro": 0,
          "expired": 0
        },
        "riskCountsUnit": "mark",
        "review": {
          "total": 1,
          "reviewed": 0,
          "decisions": "string"
        },
        "thumbs": [
          "string"
        ]
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`total`	`integer`	❌	—
`page`	`integer`	❌	—
`pageSize`	`integer`	❌	—
`totalPages`	`integer`	❌	—
`items`	`array<CheckHistoryItem>`	❌	—
`items[].taskID`	`string`	❌	—
`items[].title`	`string`	❌	—
`items[].submittedVia`	`string`	❌	`web` \| `api`
`items[].status`	`string`	❌	聚合状态：`queued` \| `processing` \| `completed` \| `failed`
`items[].error`	`string`	❌	—
`items[].createdAt`	`string`	❌	—
`items[].imageCount`	`integer`	❌	—
`items[].riskLevel`	`string`	❌	`low` \| `medium` \| `high`；未生成结论时为空串，外观专利关闭 AI 比对时为 `unscored`。
`items[].riskCounts`	`RiskCounts`	❌	各档位数量。模块未使用的档位恒为 0。
`items[].riskCounts.high`	`integer`	❌	—
`items[].riskCounts.medium`	`integer`	❌	—
`items[].riskCounts.low`	`integer`	❌	外观专利恒为 0。
`items[].riskCounts.tro`	`integer`	❌	TRO 高风险图数（`high` 的子集）。
`items[].riskCounts.expired`	`integer`	❌	已失效权利数，不计入结论。
`items[].riskCountsUnit`	`string`	❌	`image` \| `mark` \| `patent`
`items[].review`	`Review`	❌	—
`items[].review.total`	`integer`	❌	需表态条目数（按件）。
`items[].review.reviewed`	`integer`	❌	—
`items[].review.decisions`	`object`	❌	`{ 命中项ID: "flag" \| "dismiss" }`
`items[].thumbs`	`array<ImageUrl>`	❌	缩略图，临时链接，30 分钟过期。

可能的错误

HTTP	错误码	说明
401	`UNAUTHORIZED_AUTH_REQUIRED`	缺少 API Key、Key 无效或被封禁（HTTP 401），错误码 `UNAUTHORIZED_AUTH_REQUIRED`。
429	`BUSINESS_RATE_LIMIT_EXCEEDED` / `RATE_LIMITER_UNAVAILABLE`	请求频率或并发数超限（HTTP 429），错误码 `BUSINESS_RATE_LIMIT_EXCEEDED`。限流校验不可用时返回 503（`RATE_LIMITER_UNAVAILABLE`）。限流是动态的：额度由「你的 API 档位 × 接口所属的桶」决定，所以同一个接口对不同调用者可能是不同的数值，这里不给出固定数字。两处可以看到实际生效值： 1. 每次响应的 `X-RateLimit-` 响应头（当次生效的次数、窗口、命中哪一档额度）； 2. `GET /v2/quota/mine`（带 API Key，返回你每个额度的生效值）；另有 `GET /v2/quota/config`（公开）给出未分档的基线额度。计数口径：按账号计* —— 同一账号下的所有 API Key 共享同一份额度，多开一个 Key 不会获得额外配额。接口桶是分开计数的（例如「提交检测」与「轮询结果」是两个桶），所以轮询不会吃掉提交的额度。
500	`INTERNAL_ERROR_UNKNOWN`	服务器内部错误（HTTP 500），错误码 `INTERNAL_ERROR_UNKNOWN`

改名

PUT /ip/patent/design/{taskID}/name

请求参数

参数	类型	必填	说明
`taskID`	`string`	✅	检测 ID。提交时若传了 `clientRequestId`，这里也可以填该值，两者指向同一条检测。
`title`	`string`	❌	新的名称；首尾空白会被去除，空字符串不合法

请求示例

{
  "title": "2026 秋季批次 A"
}

cURLPython

curl -X PUT "https://api.trohub.com/v2/ip/patent/design/TASK_ID/name" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"title":"2026 秋季批次 A"}'

import requests

url = "https://api.trohub.com/v2/ip/patent/design/TASK_ID/name"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
  "title": "2026 秋季批次 A"
}

r = requests.put(url, headers={**headers, "Content-Type": "application/json"}, json=payload)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "title": "2026 秋季批次 A"
  }
}

响应字段

参数	类型	必填	说明
`title`	`string`	❌	—

给命中打标记

PUT /ip/patent/design/{taskID}/triage

请求参数

参数	类型	必填	说明
`taskID`	`string`	✅	检测 ID。提交时若传了 `clientRequestId`，这里也可以填该值，两者指向同一条检测。
`patentID`	`string`	❌	—
`value`	`string`	❌	`none`（清除标记）/ `flag`（需处理）/ `dismiss`（不相似）

请求示例

{
  "patentID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
  "value": "string"
}

cURLPython

curl -X PUT "https://api.trohub.com/v2/ip/patent/design/TASK_ID/triage" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"patentID":"3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6","value":"string"}'

import requests

url = "https://api.trohub.com/v2/ip/patent/design/TASK_ID/triage"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
  "patentID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
  "value": "string"
}

r = requests.put(url, headers={**headers, "Content-Type": "application/json"}, json=payload)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "triage": "string"
  }
}

响应字段

参数	类型	必填	说明
`triage`	`object`	❌	`{ 命中项ID: "flag" \| "dismiss" }`；`none` 表示清除。

删除一条

DELETE /ip/patent/design/{taskID}

查询参数

参数	类型	必填	说明
`taskID`	`string`	✅	检测 ID。提交时若传了 `clientRequestId`，这里也可以填该值，两者指向同一条检测。

cURLPython

curl -X DELETE "https://api.trohub.com/v2/ip/patent/design/TASK_ID" -H "Authorization: Bearer YOUR_API_KEY"

import requests

url = "https://api.trohub.com/v2/ip/patent/design/TASK_ID"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.delete(url, headers=headers)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "ok": true,
    "message": "string",
    "data": "string"
  }
}

响应字段

参数	类型	必填	说明
`ok`	`boolean`	❌	—
`message`	`string`	❌	固定 `"成功"`；删除类接口为 `"Deleted successfully"`。
`data`	`object`	❌	—

批量删除

POST /ip/patent/design/batch-delete

请求参数

参数	类型	必填	说明
`taskIDs`	`array<string>`	❌	待删除的检测 ID；重复项将自动去重，不存在或不属于当前账号的 ID 将被跳过

请求示例

{
  "taskIDs": [
    "string"
  ]
}

cURLPython

curl -X POST "https://api.trohub.com/v2/ip/patent/design/batch-delete" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"taskIDs":["string"]}'

import requests

url = "https://api.trohub.com/v2/ip/patent/design/batch-delete"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
  "taskIDs": [
      "string"
  ]
}

r = requests.post(url, headers={**headers, "Content-Type": "application/json"}, json=payload)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "deleted": 0,
    "notFound": [
      "string"
    ]
  }
}

响应字段

参数	类型	必填	说明
`deleted`	`integer`	❌	—
`notFound`	`array<string>`	❌	未找到或不属于本账号的 ID。