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

查一次文字商标检测的状态与结论，status 变为 completed / failed 即可停止轮询。

查询检测详情

GET /ip/trademark/text/{taskID}

查询参数

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

cURLPython

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

import requests

url = "https://api.trohub.com/v2/ip/trademark/text/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",
    "status": "completed",
    "words": [
      {
        "term": "string",
        "genericity": {
          "kind": "string",
          "kindLabel": "string",
          "score": 0,
          "scores": "string",
          "wellKnown": false,
          "at": "2026-10-19T12:00:00+08:00",
          "cached": false
        },
        "marks": [
          {
            "id": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
            "attorney": "string",
            "tmClass": [],
            "drawingCode": "string",
            "filingDate": "2026-10-19T12:00:00+08:00",
            "markText": "string",
            "owners": [],
            "regDate": "2026-10-19T12:00:00+08:00",
            "regNumber": "string",
            "serialNumber": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
            "status": "completed",
            "legalStatus": "string",
            "similarity": "string",
            "score": 0,
            "reason": "string",
            "imageUrl": [
              "https://example.com/images/logo.png"
            ],
            "imageID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
            "bucket": "string",
            "level": "string",
            "relation": "string",
            "where": []
          }
        ],
        "level": "string",
        "tro": {
          "ownerCases": 0,
          "markCases": 0,
          "latestCaseNumber": "string",
          "cases": []
        }
      }
    ],
    "imageCount": 1,
    "imageOCR": [
      {
        "imageID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
        "width": 0,
        "height": 0,
        "lines": [
          {
            "text": "string",
            "box": [],
            "score": 0
          }
        ],
        "error": "string"
      }
    ],
    "warnings": [
      "string"
    ],
    "failReason": "string",
    "counts": {
      "high": 0,
      "mid": 0,
      "low": 0
    },
    "pendingCount": 1,
    "createdAt": "2026-10-19T12:00:00+08:00",
    "updatedAt": "2026-10-19T12:00:00+08:00",
    "input": {
      "productTitle": "Wireless Earbuds Pro - 无线蓝牙耳机",
      "shortDesc": "string",
      "desc": "string",
      "classCodes": [
        "string"
      ],
      "images": [
        {
          "imageID": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6",
          "url": "https://example.com/item/123"
        }
      ]
    }
  }
}

响应字段

参数	类型	必填	说明
`taskID`	`string`	❌	本次检测的记录 ID，与提交时返回的值相同
`title`	`string`	❌	本次检测的名称（历史列表与详情共用；为空表示尚未命名）
`status`	`string`	❌	`queued` / `processing` / `completed` / `failed`
`words`	`array<TextCheckWord>`	❌	按词聚合的命中结果（`completed` 后才有）
`words[].term`	`string`	❌	—
`words[].genericity`	`WordGenericityDTO`	❌	—
`words[].genericity.kind`	`string`	❌	`generic`（通用词）/ `ambiguous`（存疑词）/ `nonbrand`（非通用词）/ `brand`（品牌词）
`words[].genericity.kindLabel`	`string`	❌	词性的中文名称：通用词 / 存疑词 / 非通用词 / 品牌词
`words[].genericity.score`	`number`	❌	常用度得分（0~1）
`words[].genericity.scores`	`object`	❌	各维度得分：`common`（常用）/ `brand`（品牌）/ `wellknown`（知名）/ `coined`（生造）
`words[].genericity.wellKnown`	`boolean`	❌	品牌得分与知名得分均较高时为 `true`
`words[].genericity.at`	`string`	❌	判定时间（RFC 3339）；沿用已有判定结果时为该结果首次判定的时间
`words[].genericity.cached`	`boolean`	❌	`true` 表示本次沿用已有判定结果，`false` 表示本次实时判定
`words[].marks`	`array<TextCheckMark>`	❌	该词命中的商标记录（含命中位置），按风险等级排序（高风险在前）
`words[].marks[].id`	`string`	❌	—
`words[].marks[].attorney`	`string`	❌	—
`words[].marks[].tmClass`	`array<object>`	❌	尼斯分类，每项键值对：分类号 `code`/`class`/`classCode`，说明 `description`/`desc`/`goods`/`goodsAndServices`。
`words[].marks[].drawingCode`	`string`	❌	—
`words[].marks[].filingDate`	`string`	❌	—
`words[].marks[].markText`	`string`	❌	商标文字（图形商标可能为空）
`words[].marks[].owners`	`array<object>`	❌	权利人，每项键值对：名称 `name`/`ownerName`/`applicant`/`holder`，国家 `country`/`countryCode`。
`words[].marks[].regDate`	`string`	❌	注册日（`YYYYMMDD`）
`words[].marks[].regNumber`	`string`	❌	—
`words[].marks[].serialNumber`	`string`	❌	—
`words[].marks[].status`	`string`	❌	商标法律状态。与 `legalStatus` 口径不同，两个字段均独立返回，不做合并。
`words[].marks[].legalStatus`	`string`	❌	商标法律状态。与 `status` 口径不同，两个字段均独立返回，不做合并。
`words[].marks[].similarity`	`string`	❌	格式化后的相似度百分比（如 `"83.00%"`）
`words[].marks[].score`	`number`	❌	视觉相似度得分（0~1）
`words[].marks[].reason`	`string`	❌	—
`words[].marks[].imageUrl`	`string`	❌	—
`words[].marks[].imageID`	`string`	❌	图片命中（`bucket=image`）时，该词来自哪张图片
`words[].marks[].bucket`	`string`	❌	命中的文本位置：`title` / `shortDesc` / `desc` / `image`
`words[].marks[].level`	`string`	❌	风险等级：`high` / `mid` / `low`
`words[].marks[].relation`	`string`	❌	该记录所属类目与卖家所选类目的关系： `same` / `adjacent` / `unrelated` / `unscoped`
`words[].marks[].where`	`array<string>`	❌	该词出现的位置：标题 / 五点第N条 / 描述 / 图 N 上的文字
`words[].level`	`string`	❌	该词的风险等级，取该词命中记录中的最高一档（`high` / `mid` / `low`）
`words[].tro`	`TextCheckTro`	❌	该词的 TRO 信号。`ownerCases` 与 `markCases` 口径不同，不可合并为同一个数值。
`words[].tro.ownerCases`	`integer`	❌	—
`words[].tro.markCases`	`integer`	❌	—
`words[].tro.latestCaseNumber`	`string`	❌	最近一起案件的案号（按案件日期取最新的那一起）；没有案件时为空
`words[].tro.cases`	`array<TextCheckTroCase>`	❌	相关案件明细：先列该商标被主张的案件，再列该权利人发起的案件（已按案件去重）；没有案件时为空数组。
`imageCount`	`integer`	❌	本次检测提交的图片张数（`0` = 纯文字检测）
`imageOCR`	`array<ImageOCR>`	❌	每张图片的 OCR 结果（含文本框坐标，可用于在图片上标注命中的词）
`imageOCR[].imageID`	`string`	❌	对应请求中的 `images[].imageID`，用于将文字对应到相应图片
`imageOCR[].width`	`integer`	❌	OCR 处理的图片宽度（像素）；`lines[].box` 坐标基于该尺寸
`imageOCR[].height`	`integer`	❌	OCR 处理的图片高度（像素）；`lines[].box` 坐标基于该尺寸
`imageOCR[].lines`	`array<ImageOCRLine>`	❌	识别出的文字行（自上而下）
`imageOCR[].lines[].text`	`string`	❌	—
`imageOCR[].lines[].box`	`array<array>`	❌	文本框四个顶点坐标（原图像素坐标，顺序为：左上 / 右上 / 右下 / 左下）
`imageOCR[].lines[].score`	`number`	❌	—
`imageOCR[].error`	`string`	❌	该图片处理失败的原因；不影响其他图片
`warnings`	`array<string>`	❌	对局部失败的说明（如某张图片 OCR 失败、图片文字检索失败）
`failReason`	`string`	❌	—
`counts`	`TextCheckCounts`	❌	各风险档的词数（按词统计，不按商标记录）
`counts.high`	`integer`	❌	高风险档的词数；同一个词命中多条记录时按一个词计
`counts.mid`	`integer`	❌	中风险档的词数；同一个词命中多条记录时按一个词计
`counts.low`	`integer`	❌	低风险档的词数；同一个词命中多条记录时按一个词计
`pendingCount`	`integer`	❌	表示本次提交是否已成功送达：正常为 0；仅当该记录仍处于 `queued` 状态，且本次提交未送达时为 1。不表示状态是否仍为 `queued`。
`createdAt`	`string`	❌	创建时间（RFC 3339）
`updatedAt`	`string`	❌	更新时间（RFC 3339）
`input`	`TextCheckInput`	❌	本次检测提交的输入（正文、类目与图片地址）
`input.productTitle`	`string`	❌	本次检测提交的商品标题（原文）
`input.shortDesc`	`string`	❌	本次检测提交的五点描述（整段文本，不按行拆）
`input.desc`	`string`	❌	本次检测提交的商品描述（原文）
`input.classCodes`	`array<string>`	❌	本次检测提交的尼斯类目；为空表示不限类别（覆盖全部 45 个类）
`input.images`	`array<object>`	❌	本次检测提交的图片（`imageID` 与 `imageOCR[].imageID` 一一对应）
`input.images[].imageID`	`string`	❌	图片 ID
`input.images[].url`	`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`