Render an image synchronously

Renders the template with dynamic_data substituted. Waits up to 25s (typical: 1-3s). Returns result_url of the finished PNG. Body flag "preview": true renders at preview price (0.1 credit) and caps the file at 640 px on the long side.

post/render/sync

Request

  • Base URL: https://rendry.io/api/v1
  • URL: https://rendry.io/api/v1/render/sync
  • 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

Rendered

mime_typestring

Effective output MIME type on success, including request overrides.

credits_chargednumber

Actual credits debited by this successful render attempt; zero when no charge was made.

job_idstring
status'success' | 'error'
result_urlstring

Path under /api/v1/files/… relative to the API origin — prefix https://rendry.io to download. Historical image results are public. New document attempt files and their page previews require the authenticated owner; a user asset (user_assets/…) is served only to its owner.

errorstring

On a refusal (status error): the machine code — see Refusal.

messagestring

On a refusal: the sentence that explains the code.

warningsstring[]

Document profile (pdf/html): which fragments were rasterized and stopped being text.

pages_usedstring[]

preset_id of every page actually rendered — the same call twice gives the same list.

expires_atstring date-time

Server-owned file deadline: authenticated live/test output expires 365 days after completion; guests expire 72 hours after batch creation.

Changes

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