gzo.ai — シンプル画像ホスト API（5ch専用ブラウザ向け）

5ch専用ブラウザがすぐ実装できるよう最小限の仕様にしています。画像アップロードは認証不要。一方で、ユーザーアカウント機能（ログイン、プロフィール、パスワード変更等）を使う場合は、Cookieベースのセッション＋CSRFを利用します。

基本

Base URL

本番:https://gzo.ai

画像アップロード/取得は不要。アカウント機能はCookieセッションを使用。

なし

リクエスト

アップロード時はmultipart/form-data

レスポンス

APIはJSON（UTF-8）。画像取得はバイナリ。

アカウント/認証（任意機能）

ユーザーアカウントを使うクライアント向けの最小仕様です。セッションはCookie（HttpOnly, SameSite=Lax）で管理し、状態変更系はCSRFトークンを必須とします。CORSはOrigin反射で許可されます。

セッションCookie: gzo_session（HttpOnly / Path=/ / SameSite=Lax / Secure=環境依存）。ログイン成功時にSet-Cookieで付与。
CSRF: GET /api/csrf で gzo_csrf Cookieを受け取り、以後の POST で X-CSRF-Token ヘッダに同値をエコー。
資格情報送信: フロントエンドは credentials: 'include' を必ず指定。

ログイン/登録

登録（任意・メール確認あり） — POST /api/auth/register

Content-Type は JSON または form-urlencoded をサポート。成功すると仮ログイン（セッション発行）し、確認メールを送信します。

{
  "email": "[email protected]",
  "password": "<12+ chars>",
  "username": "optional_lowercase_3-20"
}

ログイン — POST /api/auth/login

成功するとセッションCookieが発行され、レスポンスはユーザー情報＋メール未確認フラグを返します。

{
  "user": {"id": "u_xxx", "email": "[email protected]", "username": null},
  "needsVerification": true
}

フロント実装例（fetch）

await fetch("https://gzo.ai/api/auth/login",{
  method:"POST",
  credentials:"include",
  headers:{"Content-Type":"application/json"},
  body:JSON.stringify({email, password})
});

curl例

curl -i -c cookies.txt -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"hunter2"}' \
  https://gzo.ai/api/auth/login

現在ユーザー — GET /api/auth/me

セッションCookie同伴で現在ログイン中のユーザーを返します。未ログインは

user: null。

curl -b cookies.txt https://gzo.ai/api/auth/me
# → {"user": {"id":"u_...","email":"...","username":null}}

ログアウト — POST/GET /api/auth/logout

CSRF必須版（POST）と簡易版（GET）の両方があります。ブラウザからは

credentials: 'include' を忘れずに。

CSRFの扱い（重要）

まず GET /api/csrf を呼び、gzo_csrf Cookieを取得。
以後、POST /api/auth/logout, POST /api/auth/me, POST /api/password/change, POST /api/password/reset/start, POST /api/password/reset/complete, POST /api/auth/verify/resend などの状態変更系に X-CSRF-Token: <gzo_csrf cookie値> を必ず付与。

JS例

// 1) CSRF発行
await fetch("https://gzo.ai/api/csrf", {credentials:"include"});
// 2) Cookie gzo_csrf を読み出して、以後のPOSTでX-CSRF-Tokenにセット
const csrf = document.cookie.split('; ').find(x=>x.startsWith('gzo_csrf='))?.split('=')[1];
await fetch("https://gzo.ai/api/password/change",{
  method:"POST",
  credentials:"include",
  headers:{"Content-Type":"application/json","X-CSRF-Token":csrf},
  body:JSON.stringify({current:"oldpass", new:"newlongpassword"})
});

メール確認/パスワード再設定

メール確認完了 — GET/POST /api/auth/verify(*/complete)?token=...

メール内リンクから遷移。成功時は

ok:true とユーザー情報を返し、そのまま自動ログイン（セッションCookie発行）。

確認メール再送 — POST /api/auth/verify/resend（CSRF必須・要ログイン）

スパム防止でIP/メール別にスロットルされます。

パスワード再設定 — POST /api/password/reset/start & /complete（CSRF必須）

/start にメールを送る → リセット用メール送付（常に 200）。
/complete に {token,newPassword} を送信 → 成功で全セッション失効。

IDとファイル

ID: base62（0-9a-zA-Z）。長さはサーバ側で決定（既定7、許容5〜16）。
対応形式: JPEG / PNG / GIF / WEBP。
既定TTL: 24時間（86,400秒）。TTL経過で自動削除。CDN/キャッシュの都合で短い遅延が発生する場合があります。

エンドポイント

POST /3/image— 画像アップロード（multipart）。
GET /i/:id— 元画像（拡張子なし）。
GET /i/:id.:ext— 拡張子を明示（jpg,png,gif,webpのいずれか）。
POST /3/image/:id/delete?token=<tok>— 削除（アップロード時に発行されたトークンが必要）。

アップロード —`POST /3/image`

フォームフィールド

image（必須）—multipart/form-dataの単一ファイル。
ttl（任意）— 秒・整数・1…86400（超過値は86400に丸め）。

成功（200）

{
  "success": true,
  "status": 200,
  "data": {
    "id": "a1B9zQ7",
    "link": "https://gzo.ai/i/a1B9zQ7",
    "extension": "jpg",
    "mime": "image/jpeg",
    "bytes": 123456,
    "claimed_content_type": "image/jpeg",
    "ttl_seconds": 86400,
    "expires_at": 1724966400,
    "delete_url": "https://gzo.ai/3/image/a1B9zQ7/delete?token=<opaque-token>",
    "thumbs": {
      "s": "https://gzo.ai/i/a1B9zQ7s",
      "b": "https://gzo.ai/i/a1B9zQ7b",
      "t": "https://gzo.ai/i/a1B9zQ7t",
      "m": "https://gzo.ai/i/a1B9zQ7m",
      "l": "https://gzo.ai/i/a1B9zQ7l",
      "h": "https://gzo.ai/i/a1B9zQ7h"
    }
  }
}

エラー

400—image欠如 / 非対応形式 / 保存失敗 / 不正な入力
403— 禁止（IPブロック）
413— ファイルサイズ上限超過
429— リクエスト過多（レート制限）

削除URL: 成功レスポンスのdelete_urlに、1回使い切りのトークン付き削除エンドポイントを返します。

注: 古いアップロードには削除トークンが無い場合があります（その場合はTTL削除のみ）。

補足: EXIFは除去され、可能な場合は自動回転されます。サムネ生成に失敗したサイズはthumbsに含まれないことがあります。

curl例

# 基本
curl -F "image=@/path/to/pic.jpg" https://gzo.ai/3/image

# TTLを10分に指定
curl -F "image=@/path/to/pic.jpg" -F "ttl=600" https://gzo.ai/3/image

取得

元画像（拡張子なし）

GET /i/:id→200 image/*または404

GET /i/a1B9zQ7  → 200 image/jpeg

拡張子を明示

GET /i/:id.:ext（:ext ∈ {jpg,png,gif,webp}）

GET /i/a1B9zQ7.jpg  → 200 image/jpeg

サムネイル

thumbsは「1文字サフィックス → URL」のマップです。

サフィックス	種別	目標サイズ（px）	動作	URL例
`s`	正方形	90 × 90	中央トリミング後に縮小	`/i/<id>s`
`b`	正方形	160 × 160	中央トリミング後に縮小	`/i/<id>b`
`t`	フィット	240 × 240	長辺基準で収める（拡大しない）	`/i/<id>t`
`m`	フィット	320 × 320	長辺基準で収める（拡大しない）	`/i/<id>m`
`l`	フィット	640 × 640	長辺基準で収める（拡大しない）	`/i/<id>l`
`h`	フィット	1024 × 1024	長辺基準で収める（拡大しない）	`/i/<id>h`

実装メモ: サムネイルも/i/で配信され、IDにサフィックス（例:<id>s）を付けたものになります。

削除 —`POST /3/image/:id/delete`

アップロード成功時に返されるdelete_url（/3/image/:id/delete?token=...）を叩くと、その画像とサムネイル、メタ情報が削除対象になります。

パラメータ

token（必須）— クエリ文字列またはフォームフィールド。
例:POST /3/image/a1B9zQ7/delete?token=AbCd...

成功（200）

{
  "success": true,
  "status": 200,
  "deleted": true,
  "id": "a1B9zQ7",
  "marked": true
}

markedは内部メタの「削除済み」フラグ更新に成功したかを示します。

エラー

400—token不足などの不正入力。
403— 無効なトークン、またはトークン未対応の古いアップロード。
404— 該当IDが存在しない。

curl例

# 返ってきた delete_url をそのまま叩く（推奨）
curl -X POST "https://gzo.ai/3/image/a1B9zQ7/delete?token=AbCdEf..."

# または token をフォームで渡す（同等）
curl -X POST -F "token=AbCdEf..." "https://gzo.ai/3/image/a1B9zQ7/delete"

注意点

削除トークンはアップロードごとに固有のランダム値です。
トークンが漏えいすると第三者が削除できるため、クライアントUIでは安易に露出しない設計を推奨します。
削除は最終的にTTLファイル・メタ・サムネイル・オリジナルを全て対象にします。

レート制限

POST /3/imageに対して、IPごとに適用。
しきい値はサーバ設定依存。以下のヘッダを読み取ってください。

X-RateLimit-Limit: <int>
X-RateLimit-Remaining: <int>
X-RateLimit-Window: <seconds>

429の場合は次も返ります:

Retry-After: <seconds>

エラー形式（JSON）

{
  "success": false,
  "status": 400,
  "error": "human-readable message",
  "...optional context...": "e.g. max_bytes, ip"
}

よくあるメッセージ（英語表記のまま）:"missing 'image' field (multipart/form-data)"、"unsupported or unrecognized image format (jpeg/png/gif/webp)"、"file too large"、"forbidden (banned IP)"、"not found"、"too many requests"。

削除関連の例:"missing token"、"invalid token"、"delete not available for this upload"。

クライアント実装指針（5chブラウザ向け）

アップロードのフィールド名はimage（1リクエスト1ファイル）。
クリップボード/ドラッグ＆ドロップも、multipartでそのままPOSTすればOK。
URLの即時表示:data.link（元画像）またはdata.thumbs[k]を使う。
スレ埋め込み: 小さめ →s/b、通常 →t/m、大きめ →l/h。
期限管理: 画像はdata.expires_at（UNIX秒）で失効。404になったら表示を抑制するなどの処理を推奨。
削除UI: 成功レスのdelete_urlを安全に保管し、ユーザが明示操作した時のみPOSTを実行。
レート制限の尊重:429とRetry-Afterをユーザに分かる形で表示・再試行制御。
禁止（403）: ユーザに「forbidden (banned IP)」等のメッセージを表示。

最小疑似コード（アップロード）

resp = POST multipart /3/image
  fields:
    image = <file bytes>
    ttl   = <任意・1..86400秒>

if resp.status in 200..299 and resp.json.success:
    id     = resp.json.data.id
    link   = resp.json.data.link        # 元画像
    thumbs = resp.json.data.thumbs      # サフィックス -> URL
    表示は link か、希望サイズの thumbs を使用
else:
    表示: resp.json.error
    status==429 かつ "Retry-After" ヘッダがあれば、待って再試行

互換性メモ

サーバ側でEXIFを除去し、可能なら自動回転します（クライアント側での回転は不要）。
元GIFはそのまま保存。サムネイルは既定でJPEG。
ネイティブアプリはCORS特別対応不要。WebViewでも画像直読みでOK。
削除はTTLで自動。公開の削除APIはありません。

テストマトリクス（curl）

# 成功
curl -s -F 'image=@/tmp/a.jpg' https://gzo.ai/3/image | jq .

# サイズ超過
curl -s -F 'image=@/tmp/big.png' https://gzo.ai/3/image | jq .

# フィールド名ミス（失敗例）
curl -s -F 'file=@/tmp/a.jpg' https://gzo.ai/3/image | jq .

# 元画像（拡張子なし）取得
curl -I https://gzo.ai/i/a1B9zQ7

# サムネイル取得
curl -I https://gzo.ai/i/a1B9zQ7m

基本

アカウント/認証（任意機能）

ログイン/登録

登録（任意・メール確認あり） — POST /api/auth/register

ログイン — POST /api/auth/login

フロント実装例（fetch）

curl例

現在ユーザー — GET /api/auth/me

ログアウト — POST/GET /api/auth/logout

CSRFの扱い（重要）

JS例

メール確認/パスワード再設定

メール確認完了 — GET/POST /api/auth/verify(*/complete)?token=...

確認メール再送 — POST /api/auth/verify/resend（CSRF必須・要ログイン）

パスワード再設定 — POST /api/password/reset/start & /complete（CSRF必須）

IDとファイル

エンドポイント

アップロード —POST /3/image

フォームフィールド

成功（200）

エラー

curl例

取得

元画像（拡張子なし）

拡張子を明示

サムネイル

削除 —POST /3/image/:id/delete

パラメータ

成功（200）

エラー

curl例

注意点

レート制限

エラー形式（JSON）

クライアント実装指針（5chブラウザ向け）

最小疑似コード（アップロード）

互換性メモ

テストマトリクス（curl）

アップロード —`POST /3/image`

削除 —`POST /3/image/:id/delete`