Render an image asynchronously

Enqueues the render and returns 202 immediately. Poll /render/status/{job_id} or pass webhook_url.

post/render/async

Request

  • Base URL: https://rendry.io/api/v1
  • URL: https://rendry.io/api/v1/render/async
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

Headers

X-Rendry-Accountstring

Browser/OAuth current member account selector. API keys/embed credentials are bound to their persisted account and reject another account. Omitting this header selects the browser actor personal account.

Request body

preset_idstring

Template ID from GET /presets. Either this or draft_id.

draft_idstring

Draft returned by an inline preview (POST /render/preview with canvas+layers). Renders ONCE, charged as a normal render, no template slot spent, and dynamic_data does not apply to it. Either this or preset_id, not both. Accepted by POST /render/sync only; /render/async refuses it, because a draft renders once and is not queued.

dynamic_dataobject

Variable substitutions: text variables take text, dynamic image slots take a public image URL

webhook_urlstring

Async only: POST-ed {job_id,status,result_url} on completion; the outcome of that call is reported as webhook on GET /render/status/{id}. Must be an http or https address on the public internet: an unparseable address, another scheme, an internal host name or a literal private, loopback or link-local IP is refused with 400 invalid_webhook_url before anything is queued or charged.

previewboolean

POST /render/sync only: cap the file at 640 px on the long side and charge the preview price (0.1 credit) — the same price on every channel, api key or signed-in session, because the price follows the capped file and not the transport. Rejected for pdf/html, and refused by POST /render/async, which always renders the full page at the full price.

format'png' | 'jpeg' | 'webp' | 'pdf' | 'html'

Overrides the template's canvas.output_format for this call only. pdf/html render the DOCUMENT profile.

qualityinteger

jpeg/webp only. Accepts a number sent as a string.

max_widthinteger

Downscale the finished canvas to this width, proportions kept, never upscales. Rejected for pdf/html.

rowsobject

Arrays of rows for repeat groups AND for a table bound to rows_key: {"items": [{"name":"Coffee","price":"3.50"}, ...]}. A group with repeat.source="items" clones its children once per row and values arrive as {row.key} in content and url; a table with rows_key="items" takes each row as a body row, mapped onto its columns by columns[i].key

preview_pagesinteger[]

pdf only: pages to also return as raster previews of the finished file, free of extra charge and capped like any preview. Page 1 comes back when the field is absent; at most 3 pages per reply, and a page the render does not have is refused before any charge. POST /render/sync renders ONE page, so only [1] applies there and the pictures arrive in its own page_previews; on POST /render/async and POST /render/document they arrive at GET /render/status/{id} once the job is done.

Response

Accepted

formatstring

Document output format.

job_idstring
statusstring
status_urlstring
messagestring
pages_usedstring[]

preset_id of every page queued — determinism between calls.

pagesinteger

Output page count for document quotes and submissions.

cost_creditsnumber

Displayed credits for the document. A dry run does not charge.

credits_chargednumber

What this call actually took, in credits, at the moment it was queued. Distinct from cost_credits, which a dry run reports for work that is NOT charged.

warningsstring[]

dry_run: the same warnings the finished job would carry.

text_searchableboolean

dry_run: true when every page's text comes out of the file as the words it was typed as, false when a line stays text and stops being WORDS (letter_spacing past size/20). ABSENT when the document carries no text at all, so a client promises nothing about a sheet of scans.

errorstring

On a refusal: the machine code (see Refusal); message is its sentence. On 402 it is the credit failure: see balance, required, packages_url.

balancenumber

402 only: credits the account has.

requirednumber

402 only: credits this render needs.

packages_urlstring

402 only: where to top up.

Changes

No recorded changes to this operation across all 1 revision of this API.