HCC2D API
HCC2D REST API 可让你以编程方式生成 HCC2D 和 QR 码。使用前需要 API 密钥，可在这里申请。
认证
请在 Authorization 请求头中传递密钥：
Authorization: Bearer hcc2d_<64 hex chars>
没有有效密钥的请求会收到 HTTP 401。
基础 URL
https://hcc2d.com/api/v1
端点
POST /api/v1/generate
将负载编码为 HCC2D 或 QR 符号，并返回 PNG 图像。
请求体（JSON）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
payloadBase64 | string | 是 | 以 base64 编码的负载字节 |
inputName | string | 否 | 存储在 HCC2DF 容器中的文件名。默认值为 payload.bin。structured: false 时忽略。 |
structured | boolean | 否 | 使用 HCC2DF 容器包装负载（文件名 + zlib 压缩）。默认 true。设为 false 可直接存储原始字节。URL 与 vCard 建议使用 false，以便解码器直接识别内容。 |
mode | string | 否 | 符号类型：qr、hcc2d4（4 色）、hcc2d8（8 色，默认） |
ec | string | 否 | 纠错级别：L、M、Q、H（默认 M） |
version | integer | 否 | 符号版本（1–40）。使用 0 表示自动选择。 |
scale | integer | 否 | 每个模块的像素数（1–64，默认 12） |
quietZone | integer | 否 | 静区宽度（模块数，0–64，默认 4） |
请求示例
curl -X POST https://hcc2d.com/api/v1/generate -H "Authorization: Bearer hcc2d_<your-key>" -H "Content-Type: application/json" -d '{
"payloadBase64": "SGVsbG8sIFdvcmxkIQ==",
"inputName": "payload.txt",
"structured": true,
"mode": "hcc2d8",
"ec": "M",
"version": 0,
"scale": 4,
"quietZone": 4
}' --output code.png
成功响应（200）
{
"ok": true,
"imageUrl": "/generated/<uuid>.png",
"message": "Code generated successfully — Version 1"
}
错误响应
{
"ok": false,
"error": "Human-readable message",
"code": "machine_readable_code"
}
错误代码
| HTTP | 代码 | 含义 |
|---|---|---|
| 400 | missing_payload | payloadBase64 缺失或为空 |
| 400 | invalid_base64 | payloadBase64 不是有效的 base64 |
| 400 | empty_payload | 解码后的负载为空 |
| 400 | payload_over_max | 负载超过服务器编码前检查上限 |
| 400 | too_large_settings | 负载整体可编码，但无法在当前版本、纠错和模式组合下编码 |
| 400 | too_large_absolute | 负载超过任何符号的绝对容量上限，请减小数据量 |
| 400 | encoder_failed | 编码器因容量以外的原因拒绝了输入 |
| 400 | invalid_mode / invalid_ec / invalid_version / invalid_scale / invalid_quiet_zone | 某个请求字段超出允许范围 |
| 401 | auth_required | API 密钥缺失、无效或已被撤销 |
| 413 | body_too_large | HTTP 请求体超过解析器上限 |
| 415 | unsupported_media_type | Content-Type 不是 application/json |
| 429 | rate_limited | 达到按密钥或按 IP 的速率限制 |
| 429 | too_many_jobs | 服务器达到并发编码任务上限 |
| 500 | internal_error | 意外的服务器内部错误 |
| 502 | missing_output | 编码器运行完成，但未生成输出图像 |
| 503 | encoder_unavailable | 服务器上缺少编码器二进制文件 |
| 504 | encoder_timeout | 编码器进程超时 |
速率限制
| 限制项 | 值 |
|---|---|
| 每个 API 密钥 | 30 次请求 / 分钟 |
| 每个 IP（携带密钥） | 60 次请求 / 分钟 |
| 暴力尝试锁定 | 15 分钟内 10 次认证失败会锁定该 IP 15 分钟 |
达到限制时，服务器会返回 429，并附带 Retry-After 头。
如需更高额度，请联系 info@hcc2d.com。
负载大小限制
| 层级 | 限制 | 执行方 |
|---|---|---|
| 请求体解析器 | 约 86 KB | 服务器，JSON 解析前 — 返回 body_too_large |
| 编码前检查 | 65,536 字节（64 KB） | 服务器，base64 解码后 — 返回 payload_over_max |
| 条码绝对上限 | 约 8,859 字节 | 编码器 — 返回 too_large_absolute |
| 设置相关上限 | 取决于版本和 EC | 编码器 — 返回 too_large_settings |
默认情况下，服务器会通过 HCC2DF 容器先进行 zlib 压缩再编码，因此原始输入在 64 KB 以内时通常仍有机会编码成功。传入 structured: false 可跳过容器，直接编码原始字节。
网页界面也对上传设置了 64 KB 的客户端限制，与服务器预检查保持一致。
图像获取
生成的 PNG 将通过 https://hcc2d.com<imageUrl> 提供，并保留 1 小时。请在生成后尽快下载。
获取 API 密钥
可通过官方申请表申请 API 密钥。