POST /documents waits for the finished document or answers at once. Both make the same
document at the same price; only the response changes.
This is useful for:
- Direct: scripts, agent tools and short documents, where one call should return the file.
- Background: queues, web requests that must answer fast, and batches of many documents.
How it works
In both modes the document keeps being made after the response, even if your client disconnects. Follow a
202 with
GET /documents/{id}, GET /documents/{id}/events or webhooks.
A direct 200 doesn’t mean the document worked: check status. A document that failed comes back as 200 with
status: "failed" and its error.code (see when a document fails).
standard and best often take longer than 120 s, so a direct request at those levels usually gets a 202. For a
finished document in under 120 s, use quality: "fast".In the SDKs
documents.create() always returns a finished document: when the API answers 202, the SDK follows the document’s
events until it finishes. documents.create_in_background() (Python) and documents.createInBackground() (TypeScript)
return the 202 document at once.
wait() returns once the document is ready, failed or canceled, and reconnects on its own if the connection
drops.
When to use each
Use direct when the caller can wait up to 120 s per request. Use background when it can’t, or when you start many documents at once: you can make up to 120 documents per minute per organization (see pricing).Next steps
Follow the events
Show progress while a document is being made.
Receive webhooks
Get notified when a document finishes.