Getting Started
API quickstart
Optimize an image end to end with curl — upload, then poll until it's done.
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.
Terminal
Authorization: Bearer <your API key>
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.
Terminal
curl -X POST https://api.helloimg.io/v1/optimize \
-H "Authorization: Bearer <your API key>" \
-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:
Terminal
curl -X POST "https://api.helloimg.io/v1/optimize?async=true" \
-H "Authorization: Bearer <your API key>" \
-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":
Terminal
curl https://api.helloimg.io/v1/jobs/job_5f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c \
-H "Authorization: Bearer <your API key>"
{
"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
}
}
A sensible poll interval is a few hundred milliseconds to start, backing off
as the job runs longer — most images finish in well under a second, but
give it more room for large uploads.