Images API

Endpoints and authentication

Use UUIDs returned by the service for projectId and id. Metadata is JSON; content is a private attachment, not a public image URL.

Upload request

curl --fail-with-body --silent --show-error \
  --request POST "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/images" \
  --header "X-API-Key: $IMAZEO_API_KEY" \
  --header "X-Upload-Length: $(wc -c < "$IMAZEO_INPUT" | tr -d '[:space:]')" \
  --form "file=@$IMAZEO_INPUT" \
  --output upload.json && \
IMAZEO_IMAGE_ID=$(node -e 'const fs=require("node:fs"); const r=JSON.parse(fs.readFileSync("upload.json","utf8")); if(!r.success || !r.data?._id) process.exit(1); process.stdout.write(r.data._id);') && export IMAZEO_IMAGE_ID

Inputs: JPEG, PNG, WebP, AVIF, GIF and a strict SVG subset. The server validates signatures and decoded content, not the filename. SVG scripts, external resources, embedded images and unsafe XML are rejected. AVIF must use AV1. APNG is rejected when all frames cannot be validated.

Upload response and metadata

HTTP 201 uses the standard envelope. The following is an illustrative response projection; the API also includes originalName, sha256, sourceType, status, createdAt and updatedAt. Image metadata includes format, mimeType, width, height, frames, pixelCount, hasAlpha and nullable orientation.

{
  "success": true,
  "data": {
    "_id": "00000000-0000-4000-8000-000000000001",
    "projectId": "00000000-0000-4000-8000-000000000002",
    "bytes": 1234,
    "metadata": {
      "format": "png",
      "width": 800,
      "height": 600
    }
  },
  "meta": {
    "requestId": "example-request-id"
  }
}

Use data._id as imageId in a transformation. API metadata does not expose EXIF/GPS/ICC payloads, but downloaded originals still contain embedded metadata from your upload.

List and retrieve

List with page (default 1, maximum 100000) and limit (default 20, maximum 100). Both are positive integers. The data array contains ready-image metadata; meta includes requestId and pagination (page, limit, total, pages). Only these pagination fields are documented for this endpoint; do not assume generic filters are supported.

curl --fail-with-body --silent --show-error \
  "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/images/$IMAZEO_IMAGE_ID/content" \
  --header "X-API-Key: $IMAZEO_API_KEY" --output original-response.bin

Content returns Content-Type, Content-Length, ETag, X-Image-Width, X-Image-Height, X-Image-Format and X-Request-ID. Cache-Control is private, no-store. SVG is an application/octet-stream attachment. Original content does not implement ranges or conditional 304 responses. Check HTTP status before using the saved body.

Delete originals

DELETE removes the original and its stored derivatives and refunds their storage. It does not refund past processing or bandwidth. A concurrent operation can return IMAGE_CONFLICT or TRANSFORM_CONFLICT; retry after it completes. This is a destructive operation: keep your own backups.

Successful deletion returns a JSON message envelope. Repeating deletion is idempotent within the authorized project; credentials and ownership still apply.

Errors and recovery

Failures use a JSON error envelope even when the successful response is binary. Check status before treating the body as an image. Request IDs are illustrative below.

{
  "success": false,
  "error": {
    "code": "TRANSFORM_INVALID",
    "message": "Transformation parameters are invalid or unsupported.",
    "details": {}
  },
  "meta": {
    "requestId": "example-request-id"
  }
}

Uploads can return IMAGE_INVALID (400), IMAGE_FORMAT_NOT_SUPPORTED (415), IMAGE_TOO_LARGE or pixel/frame-limit errors (413), PLAN_LIMIT_EXCEEDED (403), RATE_LIMIT_EXCEEDED (429) or IMAGE_BUSY (503).