中國色 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，請從伺服器端發起請求。