One1One1 开放平台 · /v1 API
把 One1 的商标检索与风险初筛能力接入你的系统。所有接口走 HTTPS，返回 JSON，UTF-8 编码。
快速开始
- 登录后进入 开发者控制台，点「新建 Key」创建你的 API Key（明文只显示一次，请立即保存）。
- 带上 Key 发起第一次调用：
curl -H "Authorization: Bearer one1_live_你的Key" \
"https://trademark.radarsea.com/v1/text-search?q=ANKER&limit=10"
鉴权
所有 /v1 接口通过请求头鉴权：
Authorization: Bearer one1_live_xxxxxxxx
缺少或无效的 Key 返回 401 invalid_key；当前套餐无权使用某能力时返回 403 forbidden_entitlement。
套餐、配额与计量
| 能力 | Free（自助） | Pro / Enterprise | 计量权重 |
|---|---|---|---|
| /v1/text-search | ✓ | ✓ | 1 / 次 |
| /v1/graphic | — 需升级 | ✓ | 2 / 次 |
| /v1/advice | — 需升级 | ✓ | 3 / 次 |
| /v1/image-search | — 需升级 | ✓ | 5 / 次 |
| /v1/batch-screen | — 需升级 | ✓ | 1 / 条（items 条数） |
| 项 | 说明 |
|---|---|
| 免费额度 | 自助创建的 Key 为 Free 档：1000 计量单位 / 月（仅 text-search）。升级 Pro / Enterprise 请联系客服。 |
| 无权能力 | Free Key 调用需升级的能力返回 403 forbidden_entitlement。 |
| 响应头 | X-Quota-Remaining：本月剩余计量单位；X-Data-As-Of：数据批次日期（未配置批次时可能为空）。 |
| 超额 | 返回 429 quota_exceeded，下月自动恢复。 |
统一错误体与错误码
{ "error": { "code": "quota_exceeded", "message": "本月配额已用尽，请升级或下月再试" } }
| HTTP | code | 含义 |
|---|---|---|
| 400 | bad_request | 参数缺失或非法（如 image-search 未提供图片） |
| 401 | invalid_key | 缺少或无效的 API Key |
| 403 | forbidden_entitlement | 当前套餐无权使用该能力 |
| 404 | not_found | 未知 /v1 接口路径 |
| 429 | quota_exceeded | 本月配额已用尽 |
| 500 | server_error | 服务内部错误 |
接口
GET/v1/text-search — 文本商标检索
| 参数 | 位置 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| q | query | 是 | — | 检索词（品牌名 / 商标文字） |
| mode | query | 否 | smart | smart 智能（音形近似召回）/ exact 精确 / prefix 前缀 |
| live | query | 否 | 0 | 传 1 只返回 Live（有效）商标 |
| limit | query | 否 | 50 | 返回条数上限，最大 200 |
curl -H "Authorization: Bearer one1_live_xxx" \
"https://trademark.radarsea.com/v1/text-search?q=ANKER&mode=smart&live=1&limit=10"
响应（字段固定，示例值）
{
"results": [
{ "serial": "86123456", "mark": "ANKER", "nice": "009",
"status": "REGISTERED", "is_live": 1, "score": 1.0, "tro_hit": false }
],
"count": 1,
"data_as_of": "2026-06-30"
}
| 字段 | 说明 |
|---|---|
| serial | USPTO 序列号（申请号，非注册号） |
| mark | 商标文字 |
| nice | 尼斯分类号 |
| status | USPTO 状态码原文 |
| is_live | 1 = Live 有效 / 0 = 已失效 |
| score | 匹配相似度分（0–1，精确命中为 1.0；exact/prefix 模式下可能为 null） |
| tro_hit | 是否命中 TRO 维权高危库（仅布尔，不含权利人名录） |
GET/v1/graphic — 图形商标检索
| 参数 | 位置 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| design | query | 否* | — | USPTO 设计要素编码，6 位数字（如 241715） |
| nice | query | 否* | — | 尼斯分类号过滤 |
| mark | query | 否* | — | 商标文字过滤（图形商标中的文字部分） |
| live | query | 否 | 0 | 传 1 只返回 Live 商标 |
| limit | query | 否 | 100 | 上限 300 |
* design / nice / mark 至少提供一个作为检索条件。
curl -H "Authorization: Bearer one1_live_xxx" \
"https://trademark.radarsea.com/v1/graphic?design=241715&nice=9&live=1"
{
"results": [
{ "serial": "86123456", "mark": "FOX LOGO", "design": "241715",
"nice": "009", "is_live": 1 }
],
"count": 1,
"data_as_of": "2026-06-30"
}
POST/v1/image-search — 以图搜图
| 参数 | 位置 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| image_b64 | body | 二选一 | — | 图片 Base64（可含 dataURL 前缀） |
| url | body | 二选一 | — | 图片 URL（服务端抓取） |
| nice | body | 否 | — | 尼斯分类号过滤 |
| live | body | 否 | 0 | 传 "1" 只返回 Live 商标 |
| limit | body | 否 | 30 | 上限 100 |
curl -X POST -H "Authorization: Bearer one1_live_xxx" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/logo.png","nice":"9","limit":20}' \
"https://trademark.radarsea.com/v1/image-search"
{
"results": [
{ "serial": "86123456", "mark": "FOX LOGO", "score": 0.87,
"nice": "009", "is_live": 1 }
],
"count": 1,
"data_as_of": "2026-06-30",
"degraded": false
}
score 为图像特征相似度（0–1，部分召回通道可能为 null）；degraded 为 true 表示当次检索走了降级通道（结果可能不完整）。未提供 image_b64 / url 返回 400。
POST/v1/batch-screen — 批量核名初筛
按 items 条数计扣配额（50 条 = 50 次）。单次最多 2000 条，超出部分截断。
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
| items | body | 是 | 对象数组。每条：title（或 name）商品标题/名称，可选 nice 类目号、brand 指定品牌词（提供则跳过自动抽取） |
curl -X POST -H "Authorization: Bearer one1_live_xxx" \
-H "Content-Type: application/json" \
-d '{"items":[{"title":"ANKER Wireless Earbuds","nice":"9"},{"title":"Generic USB Cable"}]}' \
"https://trademark.radarsea.com/v1/batch-screen"
{
"results": [
{ "name": "ANKER Wireless Earbuds", "risk": "高", "tro_hit": false, "top_conflict": "ANKER" },
{ "name": "Generic USB Cable", "risk": "低", "tro_hit": false, "top_conflict": null }
],
"count": 2,
"data_as_of": "2026-06-30"
}
name 回显该条标题（截 80 字）；risk 为 高 / 中 / 低 三档；top_conflict 为撞到的在先注册商标文字（无命中为 null）；tro_hit 表示该冲突商标是否在 TRO 维权高危库中。
POST/v1/advice — 风险建议
| 参数 | 位置 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| q | body | 是 | — | 品牌 / 商标词 |
| nice | body | 否 | — | 你的商品类目（尼斯号），提供后同类目冲突权重更准 |
| live | body | 否 | 0 | 传 "1" 只按 Live 商标评估 |
curl -X POST -H "Authorization: Bearer one1_live_xxx" \
-H "Content-Type: application/json" \
-d '{"q":"ANKER","nice":"9"}' \
"https://trademark.radarsea.com/v1/advice"
{
"advice": {
"tier": "规避",
"reason": "同类目存在有效在先商标……",
"actions": ["更换品牌词", "咨询专业代理"],
"disclaimer": "结果仅供参考，不构成法律意见",
"signals": {
"tro_hit": false,
"conflict_count": 12,
"class_specified": true,
"query_class": "9",
"top_conflict": { "mark": "ANKER", "serial": "86123456", "sim": 1.0,
"is_live": 1, "same_class": true, "nice": "009" }
}
},
"data_as_of": "2026-06-30"
}
tier 取值：规避 / 谨慎 / 可上 三档；signals 给出结论可追溯的信号（冲突数、是否同类、TRO、决定性冲突标）。对非品牌词（纯描述词）或无有效输入返回 "advice": null。
数据边界与免责
· 数据源为 美国 USPTO 商标库，批次日期见响应头 X-Data-As-Of 与响应体 data_as_of；其余市场（EUIPO / UKIPO / CNIPA）规划中。
· TRO 维权命中仅返回 tro_hit 布尔，不输出维权方名录。
· 所有结果为算法初筛，仅供参考，不构成法律意见；重要决策请咨询专业商标代理 / 律师。
· TRO 维权命中仅返回 tro_hit 布尔，不输出维权方名录。
· 所有结果为算法初筛，仅供参考，不构成法律意见；重要决策请咨询专业商标代理 / 律师。