开放平台 · API
通过简单的 REST API,把 One1 的商标情报能力直接嵌入你的系统:文本核名、图形/图像检索、Listing 批量筛查、结构化风险结论、海关查扣风险、平台政策查询、EPO 专利检索,以及合规检测(专利/版权/政策/安全词)。
- Base URL:
https://one1.cn/v1 - 鉴权:请求头带 API Key(
X-API-Key或Authorization: Bearer),见鉴权 - 返回:干净的 JSON;所有
/v1响应顶层带request_id与timestamp,数据端点带coverage覆盖口径,成功响应带配额响应头(X-Quota-Remaining/X-Charged) - 计量:按调用扣「API 点」,各端点点价见配额与计费
- 档位:所有 API 套餐(含免费版)都能调用全部自有接口,套餐之间只差月度点数、每账户限速与 Key 数;第三方数据源接口(合规检测系列、伙伴国辖区 DE/IT/ES/TR/BX、Listing 改写)需付费 API 套餐
- 在线试用:开发者控制台创建 Key + 沙盒调试
三步上手
- 登录后在开发者控制台创建 API Key(明文只显示一次,请妥善保存)
- 请求头带上
Authorization: Bearer one1_live_… - 读取 JSON 响应与
X-Quota-Remaining头
端点一览
| 方法 | 端点 | 说明 | 消耗(API 点) | 可用档位 |
|---|---|---|---|---|
| GET | /v1/text-search | 按名称检索商标注册库 | 20 | 全部(含免费版);伙伴国辖区(DE/IT/ES/TR/BX)需付费 API 套餐 |
| GET | /v1/graphic | 按 USPTO 图形代码检索 | 30 | 全部(含免费版) |
| POST | /v1/image-search | 按 Logo 检索 US/CN 图形商标 | 30 | 全部(含免费版) |
| POST | /v1/batch-screen | 批量筛查 Listing 撞标 | 20 / 条 | 全部(含免费版) |
| POST | /v1/advice | 结构化风险结论(规避/谨慎/可上) | 20 | 全部(含免费版) |
| GET | /v1/customs/risk | 海关备案查扣风险(品牌 + 目的国) | 2 | 全部(含免费版) |
| GET | /v1/policy/query | Amazon / TikTok Shop 平台政策查询 | 3 | 全部(含免费版) |
| GET | /v1/epo-search | 欧洲专利文献检索(Beta) | 2 | 全部(含免费版) |
| GET | /v1/account/credits | 查询账户余额 | 免费 | 全部 |
| POST | /v1/listing/fix | Listing 合规改写(第三方大模型) | 5 | 需付费 API 套餐 |
| — | 合规检测系列 | 专利/版权/政策/安全词 | 5–75(按端点) | 需付费 API 套餐(政策特征管理免费) |
第三方数据源接口需付费套餐
合规检测系列、伙伴国辖区(DE/IT/ES/TR/BX)的文本检索、Listing 改写调用第三方数据源 / 大模型,有真实外部成本:免费版调用返回 403 paid_plan_required(未扣点);付费套餐调用只从套餐月度点扣除,免费额度与赠送点不可用。详见配额与计费。
诚实边界
文本检索默认美国 USPTO(覆盖最完整),country 可选 30+ 国/地区(伙伴国 DE/IT/ES/TR/BX 需付费 API 套餐);图形代码检索基于 USPTO;图像检索覆盖 US 与 CN(增量 Beta);数据端点响应带 coverage(scope / warning / clearance_ok)标明该辖区库的覆盖口径,各辖区数据截止日可用免费的 GET https://one1.cn/api/coverage?country=XX 随时查询;响应体不含数据新鲜度字段。本 API 返回的是注册库事实与基于规则的风险视图,不构成法律意见。
请求追踪
- 每个响应都带响应头
X-Request-Id;所有/v1JSON 响应(含 4xx / 5xx 错误)顶层的request_id与之同值。调用方可在请求头自带X-Request-Id(仅字母、数字、_、-,最长 64 字符),服务端原样回显,便于与你自己的日志对齐。 - 顶层
timestamp是服务端响应时间(UTC,ISO 8601 带Z,如2026-10-10T07:20:01Z),不代表数据新鲜度。 - 合规检测系列另带
partner_request_id(第三方数据源侧的请求 ID;命中服务端缓存时为null并带cached: true)。 - 排查问题时请提供响应头
X-Request-Id或 body 的request_id(同值);合规检测系列请一并提供partner_request_id。
幂等与超时
- 检索 / 检测类端点同入参同结果(数据批次更新前)。合规检测系列的检测类端点对同一入参有 30 分钟服务端缓存,命中时直接返回缓存结果并标
cached: true,计费不因缓存而变化;政策特征管理的save/delete是写操作,不在此列。 - 建议客户端读超时:文本核名与风险结论 10 秒;图形 / 图像检索与批量筛查 30 秒;合规检测系列与 Listing 改写 120 秒。超时后先按
request_id排查,不要对扣费端点盲目重试。 - 限流(
429)与服务暂不可用(503)带Retry-After响应头,错误体带error.retryable,见错误处理。
2026-10 响应格式调整
本次为加法 + 一处删除,不改任何既有字段名、分页参数与 score / risk / tier 表达:
- 新增:所有
/v1JSON 响应顶层request_id与timestamp;错误体error.retryable;429/503的Retry-After响应头;/v1/batch-screen、/v1/advice、/v1/graphic、/v1/image-search顶层coverage;伙伴国 text-search 顶层source/verdict_semantics/score_kind;合规检测系列partner_request_id、cached与X-Charged/X-Quota-Remaining响应头;/v1/account/credits的X-Quota-Remaining响应头。 - 删除:响应体顶层与
coverage内的data_as_of、/v1/epo-search的index_built_at、响应头X-Data-As-Of已停发;各辖区数据截止日以免费的GET https://one1.cn/api/coverage?country=XX为准。 - 修正:伙伴国 text-search 结果项
is_live由布尔归一为0/1(与本地结果和本文档一致);合规检测系列 body 的request_id改为与响应头X-Request-Id同值。