POST /v1/convert

Image Convert API

Convert images between PNG, JPG, WebP, AVIF, HEIC, TIFF, SVG, PDF, and more.

Key Operations

PNG to JPG

JPG to WebP

HEIC to JPG

SVG to PNG

PDF to JPG

Use cases

Website image optimization
Archive format normalization
Document to image rendering

Async Job Lifecycle

All ImageHQ processing endpoints are asynchronous. Upon a successful POST, you receive a 202 Acceptedresponse with a job_id. Poll the status endpoint until the state reaches succeeded.

Request Example

import requests

url = "https://api.imagehq.io/v1/convert"
payload = {
  "client_reference_id": "example-123",
  "input_format": "png",
  "output": {
    "background": "#ffffff",
    "output_format": "jpg",
    "quality": 90,
    "strip_metadata": True
  },
  "output_format": "jpg",
  "tool_slug": "png-to-jpg"
}
files = [("files[]", open("image.png", "rb"))]
data = {"request": json.dumps(payload)}

response = requests.post(url, files=files, data=data)
print(response.json())

const form = new FormData();
form.append("files[]", file);
form.append("request", JSON.stringify({
  "client_reference_id": "example-123",
  "input_format": "png",
  "output": {
    "background": "#ffffff",
    "output_format": "jpg",
    "quality": 90,
    "strip_metadata": true
  },
  "output_format": "jpg",
  "tool_slug": "png-to-jpg"
}));

const response = await fetch("https://api.imagehq.io/v1/convert", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: form
});

const data = await response.json();
console.log(data);

const form = new FormData();
form.append("files[]", file);
form.append("request", JSON.stringify({
  "client_reference_id": "example-123",
  "input_format": "png",
  "output": {
    "background": "#ffffff",
    "output_format": "jpg",
    "quality": 90,
    "strip_metadata": true
  },
  "output_format": "jpg",
  "tool_slug": "png-to-jpg"
}));

const response = await fetch("https://api.imagehq.io/v1/convert", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: form
});

const data = await response.json();
console.log(data);

curl -X POST "https://api.imagehq.io/v1/convert" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@image.png" \
  -F 'request={"client_reference_id":"example-123","input_format":"png","output":{"background":"#ffffff","output_format":"jpg","quality":90,"strip_metadata":true},"output_format":"jpg","tool_slug":"png-to-jpg"}'

$client = new GuzzleHttp\Client();
$response = $client->post("https://api.imagehq.io/v1/convert", [
  "multipart" => [
    ["name" => "files[]", "contents" => fopen("image.png", "r")],
    ["name" => "request", "contents" => '{"client_reference_id":"example-123","input_format":"png","output":{"background":"#ffffff","output_format":"jpg","quality":90,"strip_metadata":true},"output_format":"jpg","tool_slug":"png-to-jpg"}']
  ]
]);

require "faraday"

response = Faraday.post("https://api.imagehq.io/v1/convert") do |req|
  req.headers["Idempotency-Key"] = SecureRandom.uuid
  req.body = { "files[]" => Faraday::UploadIO.new("image.png", "image/png"), "request" => '{"client_reference_id":"example-123","input_format":"png","output":{"background":"#ffffff","output_format":"jpg","quality":90,"strip_metadata":true},"output_format":"jpg","tool_slug":"png-to-jpg"}' }
end

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("request", `{"client_reference_id":"example-123","input_format":"png","output":{"background":"#ffffff","output_format":"jpg","quality":90,"strip_metadata":true},"output_format":"jpg","tool_slug":"png-to-jpg"}`)
file, _ := writer.CreateFormFile("files[]", "image.png")
_ = file
writer.Close()
http.Post("https://api.imagehq.io/v1/convert", writer.FormDataContentType(), body)

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.imagehq.io/v1/convert"))
  .header("Idempotency-Key", UUID.randomUUID().toString())
  .POST(HttpRequest.BodyPublishers.ofString("multipart form data"))
  .build();

using var form = new MultipartFormDataContent();
form.Add(new StringContent('{"client_reference_id":"example-123","input_format":"png","output":{"background":"#ffffff","output_format":"jpg","quality":90,"strip_metadata":true},"output_format":"jpg","tool_slug":"png-to-jpg"}'), "request");
form.Add(new StreamContent(File.OpenRead("image.png")), "files[]", "image.png");
await httpClient.PostAsync("https://api.imagehq.io/v1/convert", form);

var request = URLRequest(url: URL(string: "https://api.imagehq.io/v1/convert")!)
request.httpMethod = "POST"
request.setValue(UUID().uuidString, forHTTPHeaderField: "Idempotency-Key")
// Attach multipart files[] and request fields before sending.

Successful Response

{
  "completed": {
    "download_url": "/v1/jobs/job_123/download",
    "expires_at": "2026-05-03T00:00:00Z",
    "id": "job_123",
    "inputs": [
      {
        "filename": "input.png",
        "format": "png",
        "mime_type": "image/png",
        "size_bytes": 420122
      }
    ],
    "outputs": [
      {
        "filename": "output.jpg",
        "format": "jpg",
        "id": "0",
        "mime_type": "image/jpeg",
        "size_bytes": 161002
      }
    ],
    "progress": 100,
    "retention_policy": {
      "clamp": true,
      "ttl_hours": 24
    },
    "stages": [
      {
        "name": "queued",
        "progress": 100,
        "status": "succeeded"
      },
      {
        "name": "processing",
        "progress": 100,
        "status": "succeeded"
      }
    ],
    "status": "succeeded",
    "warnings": []
  },
  "queued": {
    "client_reference_id": "example-123",
    "created_at": "2026-05-02T00:00:00Z",
    "current_stage": "queued",
    "expires_at": "2026-05-03T00:00:00Z",
    "id": "job_123",
    "operation": "convert",
    "poll_url": "/v1/jobs/job_123",
    "progress": 0,
    "status": "queued",
    "tool_slug": "png-to-jpg"
  }
}

Frequently Asked Questions

What image formats can I convert?

You can convert between common raster formats and selected document/image bridge formats like PDF where supported.

Does the API run asynchronously?

Yes. Jobs are queued and processed asynchronously with polling and downloadable outputs.

Can I send S3 keys instead of uploads?

Yes. Requests can include S3 input references where configured.

How do I download converted files?

Poll the job status endpoint and call the returned download URL after success.