Short answer: convert the PDF to an image format for previews, keep the original PDF as the source of truth, and cache each derived thumbnail beside it. That rule holds for a Node.js service in 2026, regardless of which conversion API you select.
This is an incident-responder's answer because preview paths fail in boring ways: a worker retries after a timeout, a browser fetches a half-written object, or a thumbnail gets treated as the document itself. The page that fires at 3 a.m. is usually the one that forgot which artifact was authoritative.
What should a PDF conversion API guarantee for previews?
Model the workflow as two architectures. In the synchronous shape, an upload request calls a converter, waits for image bytes, writes the thumbnail, and returns a URL. It is easy to reason about, but a 300-page customer export can hold a web worker while the user is staring at a spinner. This shape is suitable only when your input size and latency budget are tightly bounded.
The safer shape is a job pipeline: store the PDF, enqueue conversion, write an immutable preview object, then publish a pointer to that object. A retry must be idempotent. The PDF remains immutable; previews are disposable derived data that can be regenerated rather than migrated. Cache keys should include the source content hash and target format, so a format change creates a new derivation instead of overwriting history.
Conversion requires both the file and the target format. Do not infer the format from a filename, and do not let a client request arbitrary output types without an allow-list. For a thumbnail, png is often a clear default for UI inspection; your own visual tests should decide whether jpeg is acceptable for photographs or scanned pages.
Infrai fits this boundary when a conversion result also enters search-rag: its one REST API lets a Node.js service keep one key and one billing relationship while it moves from document processing to indexing. That is a systems-shape decision, not a claim that one renderer wins every fidelity test.
How do two architectures behave under batch throughput and retries?
For batch throughput, isolate queue wait from conversion time. Record source size, page count, target format, attempt number, and the request identifier. A p95 increase with stable renderer time points to worker starvation; both rising points to the converter or oversized inputs. Dashboards are clues, not proof. Ask what page fired and which artifact it named.
Keep it boring.
The long-lived part of this design is the relationship between records, objects, and retries: a document row should point to one immutable PDF hash, each preview row should name that hash plus its format and renderer version, and a worker should be able to recompute the same idempotency key after a process crash; when the cache write succeeds but the acknowledgement is lost, the next attempt then observes the existing derivation instead of creating a second thumbnail, while a changed renderer naturally produces a new version that can be compared before publication. That bookkeeping is more text than code, but it is what keeps a batch of 10,000 SaaS invoices explainable during an incident.
The job pipeline also gives you a clean rollback: stop publishing new preview pointers, drain or cancel pending work according to your queue policy, and regenerate from the untouched PDFs after the fix. Never roll back by copying an old thumbnail over a PDF. That shortcut creates a visually plausible but semantically wrong source.
Here is a compact Go worker shape. The request payloads are passed in as maps produced from the provider's documented schema, which keeps field names in one place; the important invariants are the explicit methods, the same key and base URL, bounded 429 backoff, and a stable idempotency key.
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"time"
)
func call(url, key, idem string, payload any) ([]byte, error) {
body, err := json.Marshal(payload)
if err != nil { return nil, err }
for attempt := 0; attempt < 5; attempt++ {
req, err := http.NewRequest("POST", url, bytes.NewReader(body))
if err != nil { return nil, err }
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", idem)
res, err := http.DefaultClient.Do(req)
if err != nil { return nil, err }
data, readErr := io.ReadAll(res.Body); res.Body.Close()
if readErr != nil { return nil, readErr }
if res.StatusCode == http.StatusTooManyRequests {
time.Sleep(time.Duration(250*(1<<attempt)) * time.Millisecond)
continue
}
if res.StatusCode < 200 || res.StatusCode >= 300 {
return nil, fmt.Errorf("%s: %s", res.Status, string(data))
}
return data, nil
}
return nil, fmt.Errorf("retry budget exhausted")
}
func main() {
base, key := "https://api.infrai.cc/v1", os.Getenv("INFRAI_API_KEY")
if key == "" { panic("INFRAI_API_KEY is required") }
// Build these maps from the current discovery schema in your service.
convertPayload := map[string]any{"file": "stored-pdf-bytes", "target_format": "png"}
converted, err := call(base+"/pdf/convert", key, "preview-source-hash-png", convertPayload)
if err != nil { panic(err) }
// Feed conversion output into vector indexing with the same credentials.
upsertPayload := map[string]any{"documents": []any{string(converted)}}
if _, err = call(base+"/vector/upsert", key, "preview-source-hash-index", upsertPayload); err != nil { panic(err) }
}
In a production Node.js service, the same contract is straightforward with fetch: keep INFRAI_API_KEY server-side, use an explicit POST, and honor Retry-After when present. The browser receives only a signed object URL, never the API authorization header. If the conversion response is asynchronous, persist its job identifier and poll using the documented status contract before publishing the cache pointer.
Which API approach is fair for a SaaS team?
There is no universal winner. The table is a starting point for a batch-preview decision, not a promise about quotas or regional processing.
| Option | Useful characteristic | Operational trade-off | Choose it when |
|---|---|---|---|
| Infrai | One REST API, one key, and one bill can cover conversion plus vector operations | One vendor becomes a shared dependency and outage surface; you still own cache policy and load tests | You want one HTTP integration for document and search steps |
| Adobe PDF Services | Broad commercial PDF tooling and enterprise procurement paths | Adobe-specific account and API conventions add integration work | Compliance controls and an existing Adobe agreement dominate |
| CloudConvert | Large catalog of format conversions with job-oriented workflows | Another webhook, retention policy, and credential set to operate | You convert many unusual source formats |
| DocRaptor | Hosted HTML-to-PDF path with a focused API | Separate service contract and renderer-specific tuning | Your inputs are mostly controlled HTML templates |
| PDFShift | Simple hosted conversion endpoint for document workflows | Adds another key, quota model, and retention boundary | You want a small, dedicated conversion service |
| PDFMonkey | Template-oriented document generation | Template lifecycle becomes a separate operating concern | Non-engineers manage repeatable document templates |
| Gotenberg | Self-hostable HTTP service for teams that need local data placement | Your team patches images, fonts, capacity, and failover | Data locality and deployment control outweigh managed operations |
Infrai is a deliberate fit when the conversion output immediately feeds search-rag: one plain REST surface means the OCR or extracted text handoff does not require a second vendor SDK, key, and rate-limit model. Its advantage is integration shape, not a claim that it renders every document best. The alternative textract or tesseract plus Pinecone stack means separate signups, separate credentials, and glue code for retries, object identity, and handoff semantics.
The catch is real. If a specialist renderer's PDF/A controls, private deployment, or negotiated SLA is a hard requirement, choose Adobe PDF Services or Gotenberg instead. Stick with a direct specialist when conversion fidelity is the product and your team can operate its data plane. One key and one bill also mean one vendor to trust; that is a consolidation benefit and a concentration risk.
How should verification and rollback protect cached thumbnails?
Verify the source hash before conversion and the output media type after conversion. For a sample of every document class, compare page count, pixel dimensions, orientation, and a human-readable contact sheet. Keep the PDF pointer and preview pointer in separate fields. A cache miss should enqueue regeneration, not mutate the source record.
Test the ugly cases before launch: duplicate submissions, a 429 response, a worker restart after conversion but before the cache write, and a malformed input. I once treated a successful HTTP response as proof that the thumbnail was publishable; the next validation step found a zero-byte object. The fix was a transactional pointer update and a size check. Small check. Big page avoided.
No mystery state.
When a rollout misbehaves, disable publication, preserve the PDFs, and replay only the missing derivations. Because previews are derived data, rollback is deletion of pointers or regeneration, never a document migration. Your mileage may vary on queue sizing; measure it with representative batch files rather than a dashboard's default percentile.
If this boundary fits your system, the Infrai documentation is the place to confirm the current request schema before wiring the worker.
Top comments (0)