服务端调用 · 现有客户

API 接入指南

现有客户可管理密钥并从服务端调用 API。新 API 销售和新账户开通暂停。

API 可以做什么

你的服务器可以提交 RGB 值匹配相近颜色、搜索色名，并查看 161 种颜色的色库和用量信息。API 不提供完整色库下载；浏览器也不能直接调用，因为不支持 CORS。

1. 下载并解压工具

需要 Node.js 20 或更高版本。以下命令使用 POSIX 兼容终端，例如 macOS 或 Linux 终端；尚未验证 Windows 原生命令。ZIP 包含客户侧辅助脚本，不含色库数据或 API 密钥，也不需要运行 npm install。

API 接入工具（ZIP）

将 ZIP 保存到“下载”目录，解压到仅自己可访问的工作目录，然后在该目录运行：

mkdir -p ~/cathycolor-api
unzip ~/Downloads/key-delivery-tools.zip -d ~/cathycolor-api
cd ~/cathycolor-api
node --version

解压后会看到 tools/api-key-delivery/。请在网站公开目录和 Git 源代码目录之外保存接入文件。

2. 生成公钥文件和私钥文件

如现有客户需要 API 支持协助处理密钥变更，公钥文件可让 CathyColor 加密 API 密钥，只有配对的私钥才能解开。仅在支持人员提出要求时提供公钥文件；私钥留在自己控制的设备上。JWK 是一种 JSON 格式的密钥文件。

在解压目录运行：

umask 077
node tools/api-key-delivery/generate-keypair.mjs \
  --public-out ./customer.public.jwk \
  --private-out ./customer.private.jwk

工具会生成 3072 位 RSA 密钥对，使用 RSA-OAEP 和 SHA-256。两个文件权限均设为 0600，并且不会覆盖已存在的文件。

确认两个文件已生成：

ls -l ./customer.public.jwk ./customer.private.jwk

3. 现有客户账户与密钥支持

目前暂停新的 API 销售和新客户账户开通。现有客户可继续使用 API 和有效密钥；续费与支持服务继续。如需现有账户协助，请使用账户邮箱联系支持团队。 support@chinesecoloratlas.com

请提供账户邮箱和相关的 X-Request-Id。仅在支持人员为现有账户密钥变更提出要求时，才提供公钥 JWK。

账户邮箱: 现有账户的邮箱
收件人: support@chinesecoloratlas.com
主题: CathyColor API 支持
可选附件: 仅在支持人员为现有账户密钥变更提出要求时附上 customer.public.jwk

不要附上 customer.private.jwk、API 密钥、完整 Authorization 请求头或银行卡资料。不要在公开问题区或聊天中粘贴任何密钥。

4. 读取加密密钥回执

如支持团队为现有账户密钥变更提供加密回执，请将文件保存为 provisioning-receipt.json，放在私有工作目录中。文件里的 API 密钥是加密数据，不是可直接阅读的明文。请勿修改回执，并妥善保管。

使用你的私钥 JWK 运行解密工具：

umask 077
node tools/api-key-delivery/decrypt-envelope.mjs \
  --envelope ./provisioning-receipt.json \
  --private-key ./customer.private.jwk \
  --key-out ./cathycolor.api-key \
  --purpose cathycolor_api_key_provisioning

工具会验证回执，并以 0600 权限将 API 密钥写入 cathycolor.api-key。它不会打印密钥，也不会覆盖已存在的输出文件。请将密钥存入密钥管理器，绝不要发给支持团队。

5. 验证密钥（运行一次）

请使用发给你账户的有效密钥。验证会调用 /v1/library（不扣额度）并发送一次 /v1/search 请求（消耗 1 次搜索额度）。重复运行会继续消耗搜索额度。

以下示例搜索 red：

node tools/api-key-delivery/verify-key.mjs \
  --key-file ./cathycolor.api-key \
  --base-url https://api.chinesecoloratlas.com \
  --query red

成功时，library.status 和 search.status 都会返回 HTTP 200。工具会丢弃响应正文，只显示状态和非敏感用量信息。如状态不同，请保留请求信息并联系支持团队，不要发送密钥。

6. API 参考

请从你的后端向生产主机发送请求。将 API 密钥保存在密钥管理器中；读取密钥时关闭 Shell 跟踪，也不要导出该变量。

读取色库和用量信息

GET /v1/library — 只返回发布信息，不消耗额度。
GET /v1/usage — 查看当前 UTC 月份两种用量，不消耗额度。
POST /v1/match — 匹配请求中的每个 RGB 颜色消耗 1 个匹配输入。colors 接受 1–5 个 RGB 值；可选参数 top 的范围是 1–3。
GET /v1/search — 每次搜索消耗 1 次搜索额度。去除首尾空格后，q 必须为 2–64 个字符；limit 最大为 10。

/v1/library 只返回版本等发布信息，不返回颜色记录。匹配和搜索只返回 161 种颜色中的有限结果；没有完整色库的下载接口。

匹配颜色与搜索色名

set +x
API_BASE_URL="https://api.chinesecoloratlas.com"
API_KEY_FILE="./cathycolor.api-key"
API_KEY="$(tr -d '\n' < "$API_KEY_FILE")"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/library"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/usage"

MATCH_IDEMPOTENCY_KEY="match-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $MATCH_IDEMPOTENCY_KEY" \
  --data '{"colors":[{"r":12,"g":34,"b":56}],"top":2}' \
  "$API_BASE_URL/v1/match"

SEARCH_IDEMPOTENCY_KEY="search-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: $SEARCH_IDEMPOTENCY_KEY" \
  "$API_BASE_URL/v1/search?q=black&limit=3"

unset API_KEY

匹配请求中的每个 RGB 颜色消耗 1 个匹配输入。colors 接受 1–5 个 RGB 值；可选参数 top 的范围是 1–3。每次搜索消耗 1 次搜索额度。去除首尾空格后，q 必须为 2–64 个字符；limit 最大为 10。

安全重试计量请求

POST /v1/match 和 GET /v1/search 必须带 Idempotency-Key（8–128 个 ASCII 英文字母、数字或 ., _, :、-）。每个新的逻辑请求生成一个键。请求超时、返回 5xx 或 request_in_progress 时，使用同一个键重试完全相同的请求；重放不会再次扣量。同一键配合不同请求数据会返回 409 idempotency_conflict。只有确实要发起新请求时才生成新键。

常见错误

401 — API 密钥缺失、无效、已撤销或过期。检查密钥文件和 Authorization 请求头；联系支持时不要附上密钥。
403 `account_unavailable` — 停止重试，向支持团队提供请求 ID 和错误详情。
409 — 解决幂等键冲突；若请求仍在处理中，使用相同的键和请求内容重试。
422 — 修正无效输入，例如超出 0–255 的 RGB 值，或长度不符合要求的搜索词。
429 `rate_limited` 表示触发滥用防护，请遵循 `Retry-After`（通常为 60 秒）。`quota_exceeded` 表示月度硬额度已用完，请遵循重试提示（通常为 86,400 秒）；这不代表额度会在那时重置。只有额度错误会附带用量响应头。不要并行重试或绕过限制。
500 或 503 — 若计量请求结果不确定，请使用相同幂等键重试完全相同的请求，并逐步延长重试间隔。

需要帮助？

联系支持时，请提供订阅邮箱、请求路径、UTC 时间、HTTP 状态码、错误码和 X-Request-Id。不要发送请求正文、RGB 值、搜索词、私钥、API 密钥或 Authorization 请求头。 support@chinesecoloratlas.com

参考资料下载

以上步骤可以直接在线完成。需要离线阅读时，请下载与当前页面语言相同的指南。其他文件分别用于以下开发任务：

离线 API 接入指南（Markdown）

可保存在本地的完整接入步骤和首次调用说明。

OpenAPI 接口定义（YAML）

供工具读取的端点、参数、响应和结构参考。

API 接入工具（ZIP）

用于生成密钥对、解密回执和验证有效密钥的脚本；不含色库数据或 API 凭证。