Request Mode Guide

ComPDF API offers three request modes for different business scenarios: synchronous, asynchronous, and pre-signed URL. This page compares them side by side and provides the full calling flow for each one to help you choose the best integration approach.

Overview of the Three Modes

Dimension	Synchronous (Sync)	Asynchronous (Async)	Pre-signed URL (Pre-signed)
Upload method	Direct upload: send the file to ComPDF in one multipart/form-data request	Direct upload: send the file to ComPDF in one multipart/form-data request	The client uploads directly to object storage through a pre-signed URL, and the file does not pass through the business API
File count	Single file (except merge endpoints)	Single / multiple files	Single / multiple files
Blocking	Yes. The server returns only after processing finishes	No. Returns taskId immediately	No. Returns taskId and the upload address immediately
How to get results	The sync response returns downloadUrl directly	Poll task status / receive Webhook notifications	Poll task status / receive Webhook notifications
Recommended file size	Small files up to 10 MB	10 MB ~ 50 MB	Large files / batch jobs / browser uploads
Server bandwidth usage	High (both directions go through the business gateway)	High (upload still goes through the business gateway)	Low (upload goes through object storage CDN)
Implementation complexity	★ Easiest	★★ Moderate	★★★ Slightly more complex (one extra signature step)
Typical scenarios	Demos, small tools, instant-feedback pages	Background batch jobs, async pipelines	Browser/mobile uploads, very large files, cross-region uploads

Selection advice

• If you are unsure, start with synchronous, then upgrade to asynchronous / pre-signed as needed.
• If the business side should not block and files are relatively large, prefer asynchronous.
• If files come from browsers or end users, are often larger than 50 MB, or you want to reduce your own server bandwidth pressure, use pre-signed URL.

Pros and Cons

Synchronous (Sync)

Pros

• One request gets the result, so the logic is the simplest.
• Easy to debug; good for examples and tutorials.

Cons

• Processing time equals HTTP wait time, so it is prone to gateway / network timeouts.
• Larger files are less stable; batch processing is not supported.
• Client threads stay occupied, which limits throughput.

Asynchronous (Async)

Pros

• Returns taskId immediately, so the caller is non-blocking.
• Supports batch processing and can work with Webhook callbacks for higher throughput.
• Good for backend pipelines and scheduled jobs.

Cons

• Uploads still go through the business gateway, so single-request body limits still apply.
• Requires an extra "check status / handle callback" step.

Pre-signed URL (Pre-signed)

Pros

• Files are uploaded directly to object storage, bypassing the business gateway, so very large files are supported.
• Greatly reduces inbound bandwidth / forwarding pressure on your own server.
• Ideal for direct uploads from browsers, mini programs, or mobile apps.

Cons

• The call chain is longest (get signature → upload → trigger task → query result).
• The client must handle PUT / POST upload protocols.

Call Flow

1. Synchronous Request Flow

Key points

• One request completes the full "upload + process + return" flow, so the chain is shortest.
• Because HTTP long connections are affected by gateway timeouts, we recommend tasks with a single file of 10 MB or less and an expected processing time under 60 seconds.
• The sync API supports only one file (except merge endpoints).
• See Complete Example for a full runnable sample.

2. Asynchronous Request Flow

Key points

• You get taskId immediately after upload, so the caller is not blocked.
• Query the status through Get Task List / Get Asset Details; we recommend a polling interval of at least 3 seconds.
• Pair it with Webhook Events to receive task-completion notifications and avoid useless polling.
• It is well suited for backend batch jobs, overnight jobs, and products where users return later to check the result.

3. Pre-signed URL Request Flow

Key points

• The biggest difference from the async flow is steps 1 and 2: you first get a pre-signed URL, and the client uploads directly to object storage.
• The upload step does not pass through the ComPDF business gateway, so it is not limited by the single-request body size, which makes it ideal for large files / browser uploads.
• After you get the pre-signed URL, complete the upload within its validity period (usually 15 to 30 minutes).
• The later steps—"execute → query / callback → download"—are the same as the async mode.

General Notes

• File download links returned by the API are usually deleted at 24:00 the next day; please download them in time.
• When calling the API, pay attention to the parameter style (query / form / json) and whether the auth header x-api-key is required.
• HTTP status 200 means your HTTP request succeeded, not that file processing succeeded; use the code field in the response body as the business result.
• For mainland China access, replace https://api-server.compdf.com/ with https://api-server.compdf.cn/ in all request URLs.
• If you want automatic notification when a task finishes, use Webhook Events to avoid high-frequency polling.