中国色 API 文档 · Chroma Cathay

01 · 概览

当前生产 API 基础地址

请使用下方当前生产域名。每个端点都要求已批准的人工 Beta 账户及有效 API Key。

商业数据投影包含 161 条已清权颜色记录。API 不提供列出或下载颜色记录的端点。

API 仅供服务端调用；不支持浏览器 CORS。

https://api.chinesecoloratlas.com/v1

02 · 认证

Bearer API Key

在 Authorization 请求头中发送 API Key，并仅将它保存在服务端。不要将 Key 放进浏览器 JavaScript、移动应用包或公开代码仓库。

POST /v1/match 和 GET /v1/search 还必须提供 Idempotency-Key，长度为 8–128 个字母、数字、句点、下划线、冒号或连字符。相同 Key 和请求可重放原结果；同一 Key 配合不同输入会被拒绝。遇到网络超时、request_in_progress、500 或 503 时，必须用原 Key 和完全相同的请求重试；遵循 Retry-After，连续服务错误采用退避重试。

Authorization: Bearer $CATHYCOLOR_API_KEY

03 · 颜色匹配

POST /v1/match

每次请求提交 1–5 个 RGB 颜色，各通道范围为 0–255。可选字段 top 接受 1–3，用于设置每个输入返回的匹配数量。

每项结果包含输入值、最多三条匹配记录、可靠性、deltaE 和 similarity 字段。

curl --request POST \
  --url https://api.chinesecoloratlas.com/v1/match \
  --header "Authorization: Bearer $CATHYCOLOR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: match-2026-09-26-0001" \
  --data '{"colors":[{"r":0,"g":52,"b":96}],"top":1}'

04 · 颜色搜索

GET /v1/search

可搜索中文名、英文名、拼音、稳定 slug 或 HEX。查询长度为 2–64 个字符，响应最多返回 10 条记录。

curl --get \
  --url https://api.chinesecoloratlas.com/v1/search \
  --header "Authorization: Bearer $CATHYCOLOR_API_KEY" \
  --header "Idempotency-Key: search-2026-09-26-0001" \
  --data-urlencode "q=indigo" \
  --data-urlencode "limit=5"

参数	必填	含义
q	是	搜索文本，长度 2–64 个字符。
limit	否	结果上限为 1–10，默认值为 10。

05 · 数据集元信息

GET /v1/library

为已认证账户返回数据集版本和记录数等元信息。此端点不会返回颜色记录数组，也不能用于分页或导出完整数据集。

curl https://api.chinesecoloratlas.com/v1/library \
  --header "Authorization: Bearer $CATHYCOLOR_API_KEY"

06 · 用量与配额

GET /v1/usage

返回两种月度计量的已提交、预留、剩余和上限。Match 按输入颜色计量，Search 按搜索次数计量。

每个 UTC 自然月硬上限为 2,000 个 match 输入颜色和 1,000 次搜索。计数在 UTC 月首重置，与订阅的付费周期分别计算。

curl https://api.chinesecoloratlas.com/v1/usage \
  --header "Authorization: Bearer $CATHYCOLOR_API_KEY"

07 · 错误与限制

错误与重试

响应会带有 request ID。联系支持时可提供该 ID；请勿在支持消息中发送 API Key。

HTTP 状态	含义	处理方式
400 idempotency_key_required / body_required / invalid_json	Key 或 match 请求正文缺失或无效。	先修正请求再重试。
401 unauthorized	API Key 缺失或无效。	检查服务端的 Key 配置。
403 account_unavailable	账户当前不可用。	联系支持并提供 request ID。
409 idempotency_conflict	同一 Key 已用于不同输入。	保留原请求；仅新请求才使用新 Key。
409 request_in_progress	该 Key 对应的请求仍在处理中。	等待 Retry-After 后用相同 Key 重试原请求。
413 payload_too_large	match 请求正文超过服务器字节上限。	缩小请求正文。
415 content_type_required	请求 Content-Type 不受支持。	match 请求请发送 application/json。
422 invalid_match_request / invalid_batch_size / invalid_rgb / invalid_top / invalid_query	请求字段无效。	修正字段，不要原样重试。
429	触发滥用限流或达到月度额度。	遵循 Retry-After 并查看错误码。
500 internal_error	服务器内部错误。	使用相同 Key 和原请求退避重试。
503 usage_commit_failed	用量提交暂时不可用。	遵循 Retry-After，用相同 Key 重试原请求。

429 rate_limited 与 quota_exceeded 含义不同。只有 quota_exceeded 响应会带 X-Usage-* 响应头。Retry-After 是重试提示，不保证月度额度已经重置。遇到 request_in_progress、internal_error 或 usage_commit_failed 时，重试应保留原 Key 和完全相同的请求。

08 · 数据边界

受限查询，不提供全库下载

API 仅为已认证的匹配或搜索请求返回所需的有限数据；数据集端点只返回元信息。

所有端点都要求有效 API Key。
每次匹配最多提交 5 个输入颜色；搜索最多返回 10 条记录。
CathyColor 网站仍可公开浏览，已授权的 API 响应也可被复制；请求和配额上限并不保证防止抓取。
此 API 不支持浏览器 CORS，请从服务端发起请求。