版权检测 · 详情 | TROHUB API 文档

查一次版权检测的整体状态与结论，以及每张图各自的命中。

查询检测详情

GET /ip/copyright/{taskID}

查询参数

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

cURLPython

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

import requests

url = "https://api.trohub.com/v2/ip/copyright/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": [],
          "searchCounts": null,
          "matches": null,
          "sourceClues": [],
          "knownIpMatch": null,
          "troCases": [],
          "aiAnalysis": null,
          "searchSummary": "string"
        }
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`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`	`CopyrightCheck`	❌	版权检测的结果（每张图片对应一项）
`images[].result.riskLevel`	`string`	❌	该图片的风险等级：`low` / `medium` / `high`；结果尚未生成时为空字符串
`images[].result.riskDrivers`	`array<string>`	❌	该风险等级的成因：`tro` / `knownIp` / `matches` / `score`
`images[].result.searchCounts`	`CopyrightSearchCounts`	❌	检索、核对、一致、改造版本四个层级的计数
`images[].result.matches`	`MatchItemPage`	❌	版权命中清单的一页（元素为 `MatchItem`）
`images[].result.sourceClues`	`array<SourceClue>`	❌	从一致作品中整理出的来源线索；线索指向命中的来源，不表示权利归属
`images[].result.knownIpMatch`	`KnownIpMatch`	❌	对提交图片本身进行的知名品牌 / IP 识别
`images[].result.troCases`	`array<TroCase>`	❌	TRO 案件命中列表；无命中时为空数组
`images[].result.aiAnalysis`	`AiAnalysis`	❌	—
`images[].result.searchSummary`	`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/copyright/{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/copyright/TASK_ID/matches?imageId=3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6&offset=0&limit=0" -H "Authorization: Bearer YOUR_API_KEY"

import requests

url = "https://api.trohub.com/v2/ip/copyright/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",
        "title": "2026 秋季批次 A",
        "matchType": "identical",
        "sharedTraits": [
          "string"
        ],
        "confidence": "string",
        "reason": "string",
        "sourceUrl": "https://example.com/item/123",
        "sourceHost": "https://example.com/item/123",
        "image": "https://example.com/images/logo.png"
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`total`	`integer`	❌	—
`hasNextPage`	`boolean`	❌	—
`items`	`array<MatchItem>`	❌	—
`items[].id`	`string`	❌	—
`items[].title`	`string`	❌	—
`items[].matchType`	`string`	❌	该命中与提交图片的关系：`identical`（同一张图）/ `verified`（同一件作品）/ `derivative`（疑似改造版本）/ `similar`（仅相似）
`items[].sharedTraits`	`array<string>`	❌	仅 `derivative` 时返回：两图共有的具体特征（如「标语文字一致」）
`items[].confidence`	`string`	❌	置信度：`high` / `medium` / `low`
`items[].reason`	`string`	❌	一致性核对的结论；`matchType` 为 `identical` 时是与原图为同一张
`items[].sourceUrl`	`string`	❌	—
`items[].sourceHost`	`string`	❌	—
`items[].image`	`ImageUrl`	❌	图片地址。带签名的临时链接，有效期 30 分钟，可直接用于 `<img src>`。过期后重新调用本接口获取。