图形商标检测 · 详情 | TROHUB API 文档

查一次检测的整体状态与结论，以及每张图各自的命中商标。结果是一棵树：一次检测 → 每张图 → 每张图的命中，不靠下标和另一份数组对齐。

提交后建议每 2–3 秒轮询一次，status 变为 completed / failed 即可停止。

查询检测详情

GET /ip/trademark/design/{taskID}

查询参数

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

cURLPython

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

import requests

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

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

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "taskID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
    "title": "2026 秋季批次 A",
    "submittedVia": "api",
    "status": "completed",
    "error": "string",
    "warnings": [
      "string"
    ],
    "createdAt": "2026-10-19T12:00:00+08:00",
    "updatedAt": "2026-10-19T12:00:00+08:00",
    "riskSummary": {
      "riskLevel": "low",
      "riskDrivers": [
        "string"
      ],
      "aiReranked": false,
      "riskCounts": {
        "high": 0,
        "medium": 0,
        "low": 0,
        "tro": 0,
        "expired": 0
      },
      "riskCountsUnit": "mark",
      "review": {
        "total": 1,
        "reviewed": 0,
        "decisions": "string"
      }
    },
    "images": [
      {
        "id": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
        "status": "completed",
        "error": "string",
        "warnings": [
          "string"
        ],
        "isStale": false,
        "updatedAt": "2026-10-19T12:00:00+08:00",
        "image": "https://example.com/images/logo.png",
        "result": {
          "riskLevel": "low",
          "riskDrivers": [],
          "matches": null,
          "aiAnalysis": null,
          "countries": []
        }
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`taskID`	`string`	❌	—
`title`	`string`	❌	—
`submittedVia`	`string`	❌	`web` \| `api`
`status`	`string`	❌	聚合状态：`queued` \| `processing` \| `completed` \| `failed`
`error`	`string`	❌	无失败时不出现。
`warnings`	`array<string>`	❌	无告警时不出现。
`createdAt`	`string`	❌	—
`updatedAt`	`string`	❌	—
`riskSummary`	`RiskSummary`	❌	—
`riskSummary.riskLevel`	`string`	❌	`low` \| `medium` \| `high`；`unscored` = 未定档（仅外观专利关闭 AI 比对时出现）。
`riskSummary.riskDrivers`	`array<string>`	❌	定档依据：`tro` \| `knownIp` \| `matches` \| `score`
`riskSummary.aiReranked`	`boolean`	❌	图形商标、版权恒 `true`；外观专利关闭 AI 比对时为 `false`。
`riskSummary.riskCounts`	`RiskCounts`	❌	各档位数量。模块未使用的档位恒为 0。
`riskSummary.riskCounts.high`	`integer`	❌	—
`riskSummary.riskCounts.medium`	`integer`	❌	—
`riskSummary.riskCounts.low`	`integer`	❌	外观专利恒为 0。
`riskSummary.riskCounts.tro`	`integer`	❌	TRO 高风险图数（`high` 的子集）。
`riskSummary.riskCounts.expired`	`integer`	❌	已失效权利数，不计入结论。
`riskSummary.riskCountsUnit`	`string`	❌	`image` \| `mark` \| `patent`
`riskSummary.review`	`Review`	❌	—
`riskSummary.review.total`	`integer`	❌	需表态条目数（按件）。
`riskSummary.review.reviewed`	`integer`	❌	—
`riskSummary.review.decisions`	`object`	❌	`{ 命中项ID: "flag" \| "dismiss" }`
`images`	`array<object>`	❌	本次检测提交的图片列表；每张图的状态与结果都在自己这一项里
`images[].id`	`string`	❌	—
`images[].status`	`string`	❌	`pending` \| `queued` \| `observing` \| `thinking` \| `recalling` \| `discerning` \| `recording` \| `completed` \| `failed`。终态为 `completed` / `failed`。
`images[].error`	`string`	❌	致命失败原因；无失败时不出现。
`images[].warnings`	`array<string>`	❌	非致命告警；无告警时不出现。
`images[].isStale`	`boolean`	❌	超时未更新，按 `failed` 处理。
`images[].updatedAt`	`string`	❌	—
`images[].image`	`ImageUrl`	❌	图片地址。带签名的临时链接，有效期 30 分钟，可直接用于 `<img src>`。过期后重新调用本接口获取。
`images[].result`	`TrademarkCheck`	❌	图形商标检测的结果（每张图片对应一项）
`images[].result.riskLevel`	`string`	❌	该图片的风险等级：`low` / `medium` / `high`；结果尚未生成时为空字符串
`images[].result.riskDrivers`	`array<string>`	❌	该风险等级的成因：`matches` / `score`
`images[].result.matches`	`TrademarkMatchPage`	❌	—
`images[].result.aiAnalysis`	`AiAnalysis`	❌	—
`images[].result.countries`	`array<string>`	❌	—

可能的错误

HTTP	错误码	说明
400	`VALIDATION_*`（见 message）	请求数据无效（HTTP 400）
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`

翻页取某张图的命中

GET /ip/trademark/design/{taskID}/matches

请求参数

参数	类型	必填	说明
`taskID`	`string`	✅	检测 ID。提交时若传了 `clientRequestId`，这里也可以填该值，两者指向同一条检测。
`imageId`	`string`	✅	取哪张图的命中清单。取值为详情响应中的 `images[].id`（即提交时的 `imageID`）。
`offset`	`integer`	✅	起始位置，从 0 开始；续取时传已获取的条数（已取 100 条则传 `offset=100`）。
`limit`	`integer`	✅	本页最多返回条数，默认 100；为 0 或负数时不截断（响应体较大）。

cURLPython

curl -X GET "https://api.trohub.com/v2/ip/trademark/design/TASK_ID/matches?imageId=3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6&offset=0&limit=0" -H "Authorization: Bearer YOUR_API_KEY"

import requests

url = "https://api.trohub.com/v2/ip/trademark/design/TASK_ID/matches?imageId=3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6&offset=0&limit=0"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

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

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "total": 1,
    "hasNextPage": false,
    "items": [
      {
        "id": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
        "markText": "string",
        "image": "https://example.com/images/logo.png",
        "score": 0,
        "reason": "string",
        "status": "completed",
        "legalStatus": "string",
        "serialNumber": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
        "regNumber": "string",
        "filingDate": "2026-10-19T12:00:00+08:00",
        "regDate": "2026-10-19T12:00:00+08:00",
        "owners": [
          {
            "name": "string",
            "country": "string"
          }
        ],
        "classes": [
          {
            "code": "string",
            "description": "string"
          }
        ],
        "attorney": "string",
        "drawingCode": "string"
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`total`	`integer`	❌	—
`hasNextPage`	`boolean`	❌	—
`items`	`array<TrademarkHit>`	❌	—
`items[].id`	`string`	❌	—
`items[].markText`	`string`	❌	商标文字（图形商标可能为空）
`items[].image`	`ImageUrl`	❌	图片地址。带签名的临时链接，有效期 30 分钟，可直接用于 `<img src>`。过期后重新调用本接口获取。
`items[].score`	`number`	❌	—
`items[].reason`	`string`	❌	—
`items[].status`	`string`	❌	商标法律状态，与 `legalStatus` 口径不同，两者均原样返回、不做合并。
`items[].legalStatus`	`string`	❌	商标法律状态，与 `status` 口径不同，两者均原样返回、不做合并。
`items[].serialNumber`	`string`	❌	—
`items[].regNumber`	`string`	❌	—
`items[].filingDate`	`string`	❌	—
`items[].regDate`	`string`	❌	—
`items[].owners`	`array<TrademarkOwner>`	❌	—
`items[].owners[].name`	`string`	❌	—
`items[].owners[].country`	`string`	❌	—
`items[].classes`	`array<TrademarkClass>`	❌	—
`items[].classes[].code`	`string`	❌	—
`items[].classes[].description`	`string`	❌	—
`items[].attorney`	`string`	❌	—
`items[].drawingCode`	`string`	❌	—