From API key
to first result.

Sign in, open API access, and create a key with Read & create permissions. Copy the key when it appears and store it on your server.

$env:RENDERLY_API_KEY = "YOUR_API_KEY"
$env:RENDERLY_BASE_URL = "https://woovhhwoevjoipwltiwy.supabase.co/functions/v1/core-api"

Install the official SDK for your language. Both are MIT-licensed and have no dependencies; they add safe retries, long polling, rate-limit details and webhook verification.

The JavaScript package renderly-ai runs on Node.js 18+, Deno, Bun and edge runtimes and includes the renderly command line. The Python package renderly-ai needs Python 3.8+ and is imported as renderly_ai. The SDKs are optional: every step below also shows plain HTTPS code under “Without the SDK”. RENDERLY_BASE_URL is optional for the SDKs.

Select a model to see its exact request body and supported inputs. You can use the same key for multiple models.

Send your model and inputs to POST /quotes. The response contains quoteId, credits, maxCredits and expiresAt. This step does not charge your account.

Choose a model above to replace the placeholders with its actual contract.

Review the maximum credits before continuing. Settings and uploaded file IDs must match the quote exactly. 1 credit = $0.01.

After approving the quote, send it to POST /jobs with the same input and a unique requestId. This reserves credits and starts the job.

Read GET /jobs/{id}?wait=60 until the status is completed or refunded. With wait, the API answers as soon as the job is final or after up to 60 seconds; repeat the call while the job is still running. Other states, including reconciling, still need a later check. Without wait, poll every 3 seconds.

A completed job includes artifacts. Request a download URL with GET /artifacts/{id}. Links expire after 15 minutes (expiresIn: 900); request a new one when needed. Fetch the link without your API key. A refunded job has its reserved credits returned.

Prefer not to poll? Let the API wait for you (next section) or receive a signed webhook when the job finishes.

Wait for the result in one request

Add ?wait=N (0–60 seconds) or the header Prefer: wait=N to POST /jobs. The API holds the response until the job is completed or refunded, or until the wait ends, and returns the job in whatever state it reached. Fast models often finish inside one request; keep long polling GET /jobs/{id}?wait=60 for the rest. The SDKs’ run() combines quote, budget check, creation and waiting.

Set your HTTP client timeout above the wait (for example 75 seconds for wait=60). A timed-out request is safe to retry with the same request ID.

Input schema

Inputs vary by model. For dynamic models, pass the IDs below inside input.parameters. For fixed models, use the field names shown directly inside input. Every model also publishes its input as JSON Schema 2020-12 in GET /models/{id} → model.inputSchema; validate against it before quoting, or run renderly model <id>.

Upload reference files

Send raw file bytes to POST /uploads?kind=image, video or audio with Content-Type: application/octet-stream, or send JSON {"url": "https://…"} to import a public HTTPS file. The response contains the upload id.

Replace YOUR_UPLOADED_ASSET_ID in a model example with the returned ID. Array inputs expect a list of IDs. Files are limited to 24 MiB and validated as in the workspace; other limits depend on the model. URL imports refuse private, local and redirect-to-private addresses with invalid_upload_url, and answer 502 upload_fetch_failed when the file cannot be downloaded. Model inputs take upload IDs, never URLs. Uploaded inputs are kept for 24 hours.

Webhooks

Instead of polling, Renderly can call your server. There are two ways to receive the same signed events:

{"id":"evt_5120","type":"job.completed","createdAt":"2026-10-26T09:00:15Z","attempt":1,
 "data":{"job":{"id":"…","modelId":"…","status":"completed","artifacts":[{"id":"…","kind":"image","mimeType":"image/png"}]}}}

Each delivery is a POST with the headers Renderly-Event, Renderly-Event-Id and Renderly-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with the signing secret. Verify it against the raw body before parsing, reject timestamps older than five minutes, and use id to ignore duplicates: a delivery can repeat if your server answers slowly.

Answer with any 2xx within 8 seconds. Other answers, timeouts and redirects (never followed) are retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours; eight failed attempts end that delivery, and twenty consecutive failures turn an account endpoint off. Only public HTTPS hostnames are accepted.

Account, limits and headers

GET /account returns your account’s tier and per-minute limits, and describes the calling key: name, prefix, scopes, expiry, monthlySpendLimit and monthSpent. GET /wallet returns your balance, the credits reserved by unfinished jobs (already deducted from the balance) and your lowBalanceCredits alert.

Each API key allows 600 protected requests per minute. Account limits grow with lifetime purchased credits:

A key with a monthly spend limit refuses new jobs with 409 key_spend_limit_reached when this calendar month’s spend (UTC) plus the new reservation would exceed it.

Usage and ledger

GET /usage totals jobs and credits (charged, refunded and still reserved) for a window of up to 366 days (default: the last 30), grouped by day, model or key. Jobs created in the browser appear under the key workspace. GET /ledger pages through every credit movement (limit up to 200, before, kind, from, to); continue with nextBefore. GET /jobs filters by status (including active), modelId, from, to and keyId.

Cancel a job

POST /jobs/{id}/cancel with {} cancels a job that has not been sent for generation yet and returns its full reservation: the response is {job, balance, cancelled: true} and the job carries cancelled: true. Once generation has started, the API answers 409 job_not_cancellable and the job finishes normally (or is refunded if it fails).