API 参考

SOURCE 提供 REST API 用于 CLI/插件/AI 访问色彩数据。

基础信息

• Base URL: https://source.ink/api/v1
• 认证方式: Bearer Token (API Key)
• 响应格式: JSON

认证

所有 API 请求都需要在 Header 中携带 API Key：

Authorization: Bearer sk_xxx_your_api_key

获取 API Key

1. 登录 SOURCE 网站
2. 进入「设置」页面
3. 在「API 密钥」区域创建新密钥

端点

GET /api/v1/tools

获取工具注册表（公开，无需认证）。

curl https://source.ink/api/v1/tools

GET /api/v1/colors

获取颜色列表。

curl -H "Authorization: Bearer sk_xxx" \
  "https://source.ink/api/v1/colors?limit=10"

查询参数：

• limit: 返回数量（默认 20，最大 100）
• cursor: 分页游标
• status: 筛选状态
• search: 搜索关键词

GET /api/v1/colors/:colorId

获取单个颜色详情。

curl -H "Authorization: Bearer sk_xxx" \
  "https://source.ink/api/v1/colors/CN-Song-04"

分析 API

POST /api/analyze

完整分析 SourcePack，生成报告（包含风险识别、纸张推荐）。

curl -X POST -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d @project.sourcepack.json \
  "https://source.ink/api/analyze"

请求体：SourcePack JSON（见下方格式）

响应：

{
  "success": true,
  "data": {
    "id": "report-id",
    "summary": { ... },
    "risks": [ ... ],
    "recommendations": [ ... ],
    "expiresAt": "2026-02-08T00:00:00.000Z"
  }
}

POST /api/analyze/parse

快速解析 SourcePack，仅返回颜色映射结果（不生成报告）。

curl -X POST -H "Content-Type: application/json" \
  -d @project.sourcepack.json \
  "https://source.ink/api/analyze/parse"

GET /api/analyze/:reportId

获取分析报告详情。

curl -H "Authorization: Bearer sk_xxx" \
  "https://source.ink/api/analyze/cmk4xxx"

插件 API

POST /api/plugin/verify

验证插件授权状态。

curl -X POST -H "Authorization: Bearer sk_plugin_xxx" \
  "https://source.ink/api/plugin/verify"

响应：

{
  "ok": true,
  "data": {
    "valid": true,
    "tier": "PLUGIN_PAID",
    "scopes": ["read:color", "search:color"],
    "rateLimit": { "remaining": 59, "reset": 1704700000 }
  }
}

GET /api/plugin/colors

获取插件可用的颜色数据。

curl -H "Authorization: Bearer sk_plugin_xxx" \
  "https://source.ink/api/plugin/colors?q=烟雨"

SourcePack 格式

SourcePack 是工程色彩包的标准 JSON 格式：

{
  "version": "1.0",
  "docInfo": {
    "name": "品牌画册",
    "source": "Adobe InDesign",
    "pageCount": 12
  },
  "printIntent": {
    "printType": "offset",
    "quantity": 3000,
    "specialProcesses": ["varnish"]
  },
  "colors": [
    {
      "colorId": "CN-Song-04",
      "name": "烟雨青",
      "lab": { "L": 65.2, "a": -12.3, "b": -8.5 },
      "usage": ["fill", "background"],
      "riskTags": ["large_area"],
      "coveragePercent": 30
    }
  ]
}

响应格式

成功响应

{
  "ok": true,
  "data": { ... },
  "citations": [
    { "type": "color", "id": "CN-Song-04", "label": "烟雨青" },
    { "type": "batch", "id": "BATCH-2026-001" }
  ]
}

错误响应

{
  "ok": false,
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "颜色不存在: CN-XXX-99"
  }
}

错误码

速率限制

默认限制：

• 每分钟: 60 次请求
• 每天: 10,000 次请求

超出限制时返回 429 Too Many Requests，响应头包含：

• X-RateLimit-Limit: 限制次数
• X-RateLimit-Remaining: 剩余次数
• X-RateLimit-Reset: 重置时间戳

权限范围 (Scopes)