API quickstart
This walks through calling the API directly, without the WordPress plugin: upload an image, wait for it to finish, and read back the result.
Authentication
Every request needs your API key as a bearer token. Get one from the helloIMG dashboard.
Authorization: Bearer <your API key>
X-HIMG-Site: example.com
Every live key is issued for one website. Send the bare host of the site the
request is made for in X-HIMG-Site — the same domain you registered the
website with, or any subdomain of it (www. is ignored). Requests from a
different site are refused with 403 site_mismatch; requests without the
header with 403 site_header_required. Every himg_ key is bound this way.
Upload an image
POST /v1/optimize takes multipart/form-data: an image file field, and
an optional data field with a JSON string describing how to optimize it.
curl -X POST https://api.helloimg.io/v1/optimize \
-H "Authorization: Bearer <your API key>" \
-H "X-HIMG-Site: example.com" \
-F "[email protected]" \
-F 'data={"level":"aggressive","convert":"webp"}'
By default this call blocks until processing finishes and returns the result directly. If the exact same image and options were optimized recently, you get the cached result back immediately instead of waiting.
Or upload async and poll yourself
Add ?async=true to get a job_id right away instead of waiting:
curl -X POST "https://api.helloimg.io/v1/optimize?async=true" \
-H "Authorization: Bearer <your API key>" \
-H "X-HIMG-Site: example.com" \
-F "[email protected]" \
-F 'data={"level":"aggressive","convert":"webp"}'
{
"job_id": "job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
"status": "processing",
"poll_url": "/v1/jobs/job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
}
Then poll GET /v1/jobs/{job_id} until status is no longer "processing":
curl https://api.helloimg.io/v1/jobs/job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c \
-H "Authorization: Bearer <your API key>" \
-H "X-HIMG-Site: example.com"
{
"job_id": "job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
"status": "completed",
"result": {
"image_url": "https://cdn.helloimg.io/helloimg-optimized/opt_job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c.webp",
"original_size": 855000,
"new_size": 111000,
"percent": 87.03,
"processing_time_ms": 26
}
}