ImageGrid.dev

Hosted image-processing API

Sign in Create account

Documentation

Getting Started

Activate an account, create a key, and send the first upload/job request.

Read this page as markdown OpenAPI JSON Open docs search

Last updated: July 17, 2026

ImageGrid is a hosted image-processing API for upload, asynchronous processing, derivative generation, and large-image tiling. This guide takes you from account creation to the first successful artifact.

Product shape

  • People sign in under /app/* to manage API keys, usage, billing, and settings.
  • Applications authenticate with API keys against /v1/* on the API host.
  • Jobs are asynchronous: upload a source image, submit a job, then poll for its artifacts.
  • The public reference set lives in API Reference, Operations, and Errors.

Quickstart checklist

  1. Create an account at /app/signup.
  2. Verify the email address.
  3. Activate Starter or Growth from the account overview.
  4. Open API Keys and create an api_runtime key.
  5. Upload an image.
  6. Submit a resize, optimize, tile, grid render, or tile patch job.
  7. Poll the job until its artifacts are ready.
  8. Read artifact metadata and use the signed download URL.

Keep API keys in server-side secrets. When rotating one, create the replacement first, move traffic to it, then revoke the old key from API Keys.

Hostnames and surfaces

Surface Purpose
imagegrid.dev Public site, docs, and customer UI
api.imagegrid.dev JSON API and artifact metadata/download URLs

Remote /v1/* requests are intentionally blocked on the public apex. Use the API host for integration traffic.

First upload

BASH
curl -X POST \
  -H "Authorization: Bearer igk_..." \
  -F "file=@/path/to/image.png" \
  https://api.imagegrid.dev/v1/assets

The response includes the asset ID needed for job creation.

First resize job

BASH
curl -X POST \
  -H "Authorization: Bearer igk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "<asset-id>",
    "operation": "resize",
    "options": {
      "width": 320,
      "fit": "inside",
      "format": "webp"
    }
  }' \
  https://api.imagegrid.dev/v1/jobs

Complete copy-paste quickstart

Set a runtime key and a local image path, then run this script. It uploads the source, starts a resize job, polls with bounded backoff, and prints the completed job with its artifact metadata.

BASH
export IMAGEGRID_API_KEY='igk_...'
export IMAGEGRID_SOURCE='/path/to/image.png'

api='https://api.imagegrid.dev'
asset_id="$({
  curl -fsS -X POST \
    -H "Authorization: Bearer $IMAGEGRID_API_KEY" \
    -F "file=@$IMAGEGRID_SOURCE" \
    "$api/v1/assets"
} | jq -er '.id')"

job_id="$({
  jq -n --arg asset_id "$asset_id" '{
    asset_id: $asset_id,
    operation: "resize",
    options: {width: 320, fit: "inside", format: "webp"}
  }' | curl -fsS -X POST \
    -H "Authorization: Bearer $IMAGEGRID_API_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- \
    "$api/v1/jobs"
} | jq -er '.id')"

for delay in 1 2 3 5 8 13 21; do
  result="$(curl -fsS \
    -H "Authorization: Bearer $IMAGEGRID_API_KEY" \
    "$api/v1/jobs/$job_id")"
  status="$(jq -r '.status' <<<"$result")"
  if [ "$status" = succeeded ]; then
    jq . <<<"$result"
    exit 0
  fi
  if [ "$status" = failed ]; then
    jq . <<<"$result" >&2
    exit 1
  fi
  sleep "$delay"
done

echo "Job $job_id is still processing; poll it again shortly." >&2
exit 2

The example requires curl and jq. Keep the key in a secret manager or protected environment variable; do not commit it to a repository.

Processing model

  1. Upload source image
  2. Create async job
  3. Poll job status
  4. Read artifact metadata
  5. Use signed download URL

Local development

Use the repository's existing Docker stack:

BASH
docker compose up -d --build

Then open:

  • http://localhost:18082/
  • http://localhost:18082/app/signup
  • http://localhost:18082/app/login

The stack keeps PostgreSQL and application data in its existing Compose volumes unless you explicitly reset them.

Where to go next