POST /v1/document

Image Document API

Convert images to PDF and render PDF pages as images.

Opérations clés

image_to_pdf

pdf_to_image

pdf_to_jpg

pdf_to_png

Cas d’utilisation

Photo-to-PDF exports
PDF page thumbnails
Document preview generation

For advanced PDF workflow orchestration, see PDFHQ placeholders in docs and footer links.

Cycle de vie de la tâche async

Tous les endpoints de traitement ImageHQ sont asynchrones. Après un POST réussi, vous recevez une réponse 202 Acceptedavec un job_id. Interrogez l’endpoint de statut jusqu’à ce que l’état atteigne succeeded.

Exemple de requête

import requests

url = "https://api.imagehq.io/v1/document"
payload = {
  "operation": "image_to_pdf",
  "options": {
    "merge_images": True,
    "orientation": "auto",
    "page_size": "auto"
  },
  "tool_slug": "image-to-pdf"
}
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": "image_to_pdf",
  "options": {
    "merge_images": true,
    "orientation": "auto",
    "page_size": "auto"
  },
  "tool_slug": "image-to-pdf"
}));

const response = await fetch("https://api.imagehq.io/v1/document", {
  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": "image_to_pdf",
  "options": {
    "merge_images": true,
    "orientation": "auto",
    "page_size": "auto"
  },
  "tool_slug": "image-to-pdf"
}));

const response = await fetch("https://api.imagehq.io/v1/document", {
  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/document" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@image.png" \
  -F 'request={"operation":"image_to_pdf","options":{"merge_images":true,"orientation":"auto","page_size":"auto"},"tool_slug":"image-to-pdf"}'

$client = new GuzzleHttp\Client();
$response = $client->post("https://api.imagehq.io/v1/document", [
  "multipart" => [
    ["name" => "files[]", "contents" => fopen("image.png", "r")],
    ["name" => "request", "contents" => '{"operation":"image_to_pdf","options":{"merge_images":true,"orientation":"auto","page_size":"auto"},"tool_slug":"image-to-pdf"}']
  ]
]);

require "faraday"

response = Faraday.post("https://api.imagehq.io/v1/document") do |req|
  req.headers["Idempotency-Key"] = SecureRandom.uuid
  req.body = { "files[]" => Faraday::UploadIO.new("image.png", "image/png"), "request" => '{"operation":"image_to_pdf","options":{"merge_images":true,"orientation":"auto","page_size":"auto"},"tool_slug":"image-to-pdf"}' }
end

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("request", `{"operation":"image_to_pdf","options":{"merge_images":true,"orientation":"auto","page_size":"auto"},"tool_slug":"image-to-pdf"}`)
file, _ := writer.CreateFormFile("files[]", "image.png")
_ = file
writer.Close()
http.Post("https://api.imagehq.io/v1/document", writer.FormDataContentType(), body)

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

using var form = new MultipartFormDataContent();
form.Add(new StringContent('{"operation":"image_to_pdf","options":{"merge_images":true,"orientation":"auto","page_size":"auto"},"tool_slug":"image-to-pdf"}'), "request");
form.Add(new StreamContent(File.OpenRead("image.png")), "files[]", "image.png");
await httpClient.PostAsync("https://api.imagehq.io/v1/document", form);

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

Réponse réussie

{
  "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": "document",
    "poll_url": "/v1/jobs/job_123",
    "progress": 0,
    "status": "queued",
    "tool_slug": "png-to-jpg"
  }
}

Questions fréquentes

Is /api/document replacing /api/pdf?

Yes. In this API surface, document operations are grouped under /v1/document.

Can I render selected PDF pages only?

Yes. Use options like page_range for targeted rendering.

Can document output be downloaded like other jobs?

Yes. Completed jobs expose output download URLs.

API associées

API ocr API convert API pipeline API batch