API ドキュメント

課金

API は成功ごとに 1 クレジット、サイトは 10 クレジットで、同じ残高を使います。API 作成時に 1 を予約し、最終失敗時に一度だけ返還します。

必要な権限を持つ Bearer キーを使用します。同一画像の再送は同じ Idempotency-Key を使い、入力を変えると HTTP 409 になります。照会は無料です。

エンドポイント

ジョブを作成

multipart/form-data で JPEG・PNG・WebP の画像一枚（最大 5 MB）と consent を送信します。成人が本人の写真を同意の上で提出する場合に限ります。URL と追加パラメータは拒否されます。新規テストごとに新しい冪等キーを作成してください。

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

結果を照会

作成時に HTTP 202 とジョブ ID を返します。10〜15 秒間隔で照会してください。queued・processing・retrying は処理中、succeeded・failed は終端状態です。HF の起動には数分かかる場合があります。期限は 20 分で、有効な実行リースにより最大四分延びる場合があります。

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

エラーと制限

応答は code/message/data 形式です。400 は入力・同意、401 はキー、403 は権限、402 は残高不足、404 は所有権・存在、409 は入力競合、413/415 は画像、429 は頻度・同時実行・予算、503 は利用不可を示します。message と Retry-After を確認し、同じ冪等キーで再試行してください。

キーの有効期限は最長一年です。予算は予約・確定分を含み、返還時に回復します。アカウントごとに毎分 60 リクエスト、同時 API ジョブは最大二つです。

写真は非公開ストレージに一時保存し、処理終了後に削除します。予備の保持期限は 24 時間です。HF が画像を処理し、推定結果は医療助言・本人確認・年齢証明には使えません。