POST /v1/filter

Image Filter API

Apply classic filters, color adjustments, and social-media-inspired looks with one filter pipeline.

Key Operations

grayscale

sepia

blur

sharpen

brightness

contrast

saturation

pixelate

cinematic

viral_glow

warm_film

vhs_glitch

golden_hour

Use cases

Preset-based media styling
Brand-aligned visual edits
Bulk post-processing

Inspired by common social-media aesthetics, not exact copies of proprietary platform filters.

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/filter"
payload = {
  "filters": [
    {
      "intensity": 75,
      "type": "viral_glow"
    }
  ],
  "options": {
    "quality": 92,
    "strip_metadata": True
  },
  "output_format": "jpg",
  "tool_slug": "viral-glow-filter"
}
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({
  "filters": [
    {
      "intensity": 75,
      "type": "viral_glow"
    }
  ],
  "options": {
    "quality": 92,
    "strip_metadata": true
  },
  "output_format": "jpg",
  "tool_slug": "viral-glow-filter"
}));

const response = await fetch("https://api.imagehq.io/v1/filter", {
  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({
  "filters": [
    {
      "intensity": 75,
      "type": "viral_glow"
    }
  ],
  "options": {
    "quality": 92,
    "strip_metadata": true
  },
  "output_format": "jpg",
  "tool_slug": "viral-glow-filter"
}));

const response = await fetch("https://api.imagehq.io/v1/filter", {
  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/filter" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@image.png" \
  -F 'request={"filters":[{"intensity":75,"type":"viral_glow"}],"options":{"quality":92,"strip_metadata":true},"output_format":"jpg","tool_slug":"viral-glow-filter"}'

$client = new GuzzleHttp\Client();
$response = $client->post("https://api.imagehq.io/v1/filter", [
  "multipart" => [
    ["name" => "files[]", "contents" => fopen("image.png", "r")],
    ["name" => "request", "contents" => '{"filters":[{"intensity":75,"type":"viral_glow"}],"options":{"quality":92,"strip_metadata":true},"output_format":"jpg","tool_slug":"viral-glow-filter"}']
  ]
]);

require "faraday"

response = Faraday.post("https://api.imagehq.io/v1/filter") do |req|
  req.headers["Idempotency-Key"] = SecureRandom.uuid
  req.body = { "files[]" => Faraday::UploadIO.new("image.png", "image/png"), "request" => '{"filters":[{"intensity":75,"type":"viral_glow"}],"options":{"quality":92,"strip_metadata":true},"output_format":"jpg","tool_slug":"viral-glow-filter"}' }
end

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("request", `{"filters":[{"intensity":75,"type":"viral_glow"}],"options":{"quality":92,"strip_metadata":true},"output_format":"jpg","tool_slug":"viral-glow-filter"}`)
file, _ := writer.CreateFormFile("files[]", "image.png")
_ = file
writer.Close()
http.Post("https://api.imagehq.io/v1/filter", writer.FormDataContentType(), body)

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

using var form = new MultipartFormDataContent();
form.Add(new StringContent('{"filters":[{"intensity":75,"type":"viral_glow"}],"options":{"quality":92,"strip_metadata":true},"output_format":"jpg","tool_slug":"viral-glow-filter"}'), "request");
form.Add(new StreamContent(File.OpenRead("image.png")), "files[]", "image.png");
await httpClient.PostAsync("https://api.imagehq.io/v1/filter", form);

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

Frequently Asked Questions

Can I apply multiple filters in one request?

Yes. Filters are applied sequentially in the order you provide.

Do preset filters use AI models?

No. The current filter system is non-AI and built from deterministic image operations.

Are the social presets exact copies?

No. They are inspired by common aesthetics and intentionally generic.