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 モジュールあたりのピクセル数（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`	デコード後のペイロードが 0 バイトです
400	`payload_over_max`	ペイロードがサーバーの事前チェック上限を超えています
400	`too_large_settings`	絶対上限には収まるものの、指定した version / EC / mode の組み合わせでは入りません
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 ボディが parser の上限を超えています
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 回認証失敗すると 15 分間 IP をロック

制限に達すると、サーバーは Retry-After ヘッダー付きで 429 を返します。

より高い上限が必要な場合は info@hcc2d.com までご連絡ください。

ペイロードサイズ制限

層	上限	適用箇所
ボディパーサ	約 86 KB	JSON 解析前のサーバー — body_too_large を返します
事前チェック	65,536 バイト（64 KB）	base64 デコード後のサーバー — payload_over_max を返します
コードの絶対上限	約 8,859 バイト	エンコーダ — too_large_absolute を返します
設定依存の上限	version と EC に依存	エンコーダ — too_large_settings を返します

既定では、サーバーは HCC2DF コンテナ経由で zlib 圧縮してからエンコードするため、生データが 64 KB あっても収まる場合があります。structured: false を指定するとコンテナを使わずに生バイトをエンコードします。

Web UI でも 64 KB のアップロード上限を設けており、サーバー側の事前チェックと揃えています。

画像の取得

生成された PNG は https://hcc2d.com<imageUrl> で提供され、1 時間保持されます。生成後は早めにダウンロードしてください。

API キーの取得

公式申請フォームから API キーを申請してください。

参考情報

HCC2DF 形式リファレンス — 構造化コンテナのバイナリレイアウトを項目ごとに説明します。

コード例 — JavaScript、Python、Java、PHP の実行可能なサンプルです。

← HCC2D Encoder に戻る