POST /v1/metadata

Image Metadata API

Inspect, extract, or remove EXIF, GPS, camera, color profile, and file metadata.

Key Operations

inspect

remove

remove_exif

remove_gps

check_size

check_dimensions

Use cases

Privacy cleanup
Compliance checks
Metadata extraction in ingestion pipelines

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/metadata"
payload = {
  "operation": "inspect",
  "options": {
    "include_exif": True,
    "include_gps": True,
    "remove_exif": False
  },
  "tool_slug": "view-image-metadata"
}
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({
  "operation": "inspect",
  "options": {
    "include_exif": true,
    "include_gps": true,
    "remove_exif": false
  },
  "tool_slug": "view-image-metadata"
}));

const response = await fetch("https://api.imagehq.io/v1/metadata", {
  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({
  "operation": "inspect",
  "options": {
    "include_exif": true,
    "include_gps": true,
    "remove_exif": false
  },
  "tool_slug": "view-image-metadata"
}));

const response = await fetch("https://api.imagehq.io/v1/metadata", {
  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/metadata" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@image.png" \
  -F 'request={"operation":"inspect","options":{"include_exif":true,"include_gps":true,"remove_exif":false},"tool_slug":"view-image-metadata"}'

$client = new GuzzleHttp\Client();
$response = $client->post("https://api.imagehq.io/v1/metadata", [
  "multipart" => [
    ["name" => "files[]", "contents" => fopen("image.png", "r")],
    ["name" => "request", "contents" => '{"operation":"inspect","options":{"include_exif":true,"include_gps":true,"remove_exif":false},"tool_slug":"view-image-metadata"}']
  ]
]);

require "faraday"

response = Faraday.post("https://api.imagehq.io/v1/metadata") do |req|
  req.headers["Idempotency-Key"] = SecureRandom.uuid
  req.body = { "files[]" => Faraday::UploadIO.new("image.png", "image/png"), "request" => '{"operation":"inspect","options":{"include_exif":true,"include_gps":true,"remove_exif":false},"tool_slug":"view-image-metadata"}' }
end

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("request", `{"operation":"inspect","options":{"include_exif":true,"include_gps":true,"remove_exif":false},"tool_slug":"view-image-metadata"}`)
file, _ := writer.CreateFormFile("files[]", "image.png")
_ = file
writer.Close()
http.Post("https://api.imagehq.io/v1/metadata", writer.FormDataContentType(), body)

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

using var form = new MultipartFormDataContent();
form.Add(new StringContent('{"operation":"inspect","options":{"include_exif":true,"include_gps":true,"remove_exif":false},"tool_slug":"view-image-metadata"}'), "request");
form.Add(new StreamContent(File.OpenRead("image.png")), "files[]", "image.png");
await httpClient.PostAsync("https://api.imagehq.io/v1/metadata", form);

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

Frequently Asked Questions

Can metadata jobs return JSON?

Yes. Inspect operations can return structured metadata results.

Can I remove GPS only?

Yes. Use the remove_gps operation for targeted cleanup.

Does metadata processing alter pixels?

No pixel edits are required for inspect-only metadata operations.