POST /v1/compose

Image Compose API

Add text, watermarks, borders, annotations, redactions, meme text, and overlays.

Key Operations

text_overlay

watermark

redact

annotate

border

round_corners

meme_text

Use cases

Automatic watermarking
Sensitive area redaction
Batch annotation workflows

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/compose"
payload = {
  "operations": [
    {
      "color": "#ffffff",
      "font_size": 48,
      "text": "Hello",
      "type": "text_overlay",
      "x": 100,
      "y": 80
    }
  ],
  "output_format": "same_as_input",
  "tool_slug": "add-text-to-image"
}
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({
  "operations": [
    {
      "color": "#ffffff",
      "font_size": 48,
      "text": "Hello",
      "type": "text_overlay",
      "x": 100,
      "y": 80
    }
  ],
  "output_format": "same_as_input",
  "tool_slug": "add-text-to-image"
}));

const response = await fetch("https://api.imagehq.io/v1/compose", {
  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({
  "operations": [
    {
      "color": "#ffffff",
      "font_size": 48,
      "text": "Hello",
      "type": "text_overlay",
      "x": 100,
      "y": 80
    }
  ],
  "output_format": "same_as_input",
  "tool_slug": "add-text-to-image"
}));

const response = await fetch("https://api.imagehq.io/v1/compose", {
  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/compose" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@image.png" \
  -F 'request={"operations":[{"color":"#ffffff","font_size":48,"text":"Hello","type":"text_overlay","x":100,"y":80}],"output_format":"same_as_input","tool_slug":"add-text-to-image"}'

$client = new GuzzleHttp\Client();
$response = $client->post("https://api.imagehq.io/v1/compose", [
  "multipart" => [
    ["name" => "files[]", "contents" => fopen("image.png", "r")],
    ["name" => "request", "contents" => '{"operations":[{"color":"#ffffff","font_size":48,"text":"Hello","type":"text_overlay","x":100,"y":80}],"output_format":"same_as_input","tool_slug":"add-text-to-image"}']
  ]
]);

require "faraday"

response = Faraday.post("https://api.imagehq.io/v1/compose") do |req|
  req.headers["Idempotency-Key"] = SecureRandom.uuid
  req.body = { "files[]" => Faraday::UploadIO.new("image.png", "image/png"), "request" => '{"operations":[{"color":"#ffffff","font_size":48,"text":"Hello","type":"text_overlay","x":100,"y":80}],"output_format":"same_as_input","tool_slug":"add-text-to-image"}' }
end

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("request", `{"operations":[{"color":"#ffffff","font_size":48,"text":"Hello","type":"text_overlay","x":100,"y":80}],"output_format":"same_as_input","tool_slug":"add-text-to-image"}`)
file, _ := writer.CreateFormFile("files[]", "image.png")
_ = file
writer.Close()
http.Post("https://api.imagehq.io/v1/compose", writer.FormDataContentType(), body)

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

using var form = new MultipartFormDataContent();
form.Add(new StringContent('{"operations":[{"color":"#ffffff","font_size":48,"text":"Hello","type":"text_overlay","x":100,"y":80}],"output_format":"same_as_input","tool_slug":"add-text-to-image"}'), "request");
form.Add(new StreamContent(File.OpenRead("image.png")), "files[]", "image.png");
await httpClient.PostAsync("https://api.imagehq.io/v1/compose", form);

var request = URLRequest(url: URL(string: "https://api.imagehq.io/v1/compose")!)
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": "compose",
    "poll_url": "/v1/jobs/job_123",
    "progress": 0,
    "status": "queued",
    "tool_slug": "png-to-jpg"
  }
}

Frequently Asked Questions

Does compose support redaction boxes?

Yes. You can apply redact operations with explicit coordinates and modes.

Can I add branding overlays?

Yes. Text and watermark operations are supported in compose pipelines.

Can compose be chained with filter?

Yes. Use the pipeline API for multi-endpoint workflows.