# imgd.dev

> Image hosting your agent can sign up for. No email, no captcha, no dashboard.
> One API call creates an account. $1 = 1 GB of storage, one-time, stacking.

## Pricing

$1 buys 1 GB of permanent storage. Payments are one-time and stack: five $1
payments give you 5 GB. There is no subscription and no metered balance to
run down — you buy space, you keep it.

There is no free tier. Creating an account is free and instant, but it starts
with no storage and cannot upload until you buy some. An upload attempted
before payment returns 402 payment_required with a checkout URL in the body.

## Quickstart (three calls, no human required)

1. Create an account. No email, no captcha.

   curl -X POST https://imgd.dev/v1/accounts

   Returns {"api_key": "imgd_...", "activation_url": "https://checkout.stripe.com/..."}.
   Save the key: it is shown exactly once and is never recoverable.
   The account has no storage until you complete step 2.

2. Buy storage. $1.00 per GB, one-time, stacks.

   curl -X POST https://imgd.dev/v1/credit \
     -H "Authorization: Bearer $IMGD_KEY" \
     -d '{"gb": 1}'

   Returns {"checkout_url": "https://checkout.stripe.com/...", "gb": 1}.
   Works for new AND already-paid accounts — top up any time.

3. Upload.

   curl -X POST https://imgd.dev/v1/upload \
     -H "Authorization: Bearer $IMGD_KEY" \
     -F "file=@photo.jpg"

   Returns 202 {"hash","url","status":"processing"}. Moderation runs async and
   usually finishes in a few seconds. Poll GET /v1/images/:hash for the verdict
   and the generated alt_text.

## Endpoints

POST   /v1/accounts        create account, returns api key + activation url
POST   /v1/credit          buy storage; body {"gb": N}, returns a checkout url
GET    /v1/me              quota, usage, remaining bytes, strike count
POST   /v1/upload          multipart (field: file) or raw image bytes
GET    /v1/images          list your images, paginated (?limit=&cursor=)
GET    /v1/images/:hash    metadata for one image, including alt_text
DELETE /v1/images/:hash    unlink an image from your account
GET    /i/:hash            serve the image; ?w=800&fmt=webp to transform
GET    /health             liveness
GET    /openapi.json       machine-readable spec

## Things worth knowing

- Uploads are content-addressed by sha256. The same bytes always return the
  same hash and url, are never billed twice, and are never re-scanned by the
  moderation model. Retry freely; it is idempotent.
- Storage quota counts every image you keep, including one that deduplicated
  against another account's copy. Delete an image and its bytes come straight
  back. Check GET /v1/me before a large upload: storage_remaining_bytes tells
  you whether it will fit.
- Over quota returns 402 quota_exceeded with a topup_url and a suggested_gb.
  Buy the storage or delete something, then retry the same bytes.
- alt_text is generated during moderation and returned for free. Use it.
- Every 4xx body has a "fix" field in plain language saying what to do next.
  Read it before retrying.
- Nothing is publicly served until it clears moderation. A fresh upload is
  status=processing, then live | review | blocked.
- Explicit or gore uploads add an abuse strike. 3 strikes suspends the account.
- Max upload 20MB. Accepted: jpeg, png, gif, webp, avif.

## Contact

Abuse and takedowns: abuse@imgd.dev