renderly-ai for Python

Official client for the Renderly API: one key and one credit wallet (1 credit = $0.01) for image, video, audio, 3D and language models. Standard library only; Python 3.8+. Keep your API key on a server.

pip install renderly-ai
export RENDERLY_API_KEY="rly_…"   # Settings → API access

from renderly_ai import Renderly

renderly = Renderly()  # reads RENDERLY_API_KEY (and RENDERLY_BASE_URL if set)

result = renderly.run(
    model_id="model-…",            # from renderly.search_models("…")
    operation="text-to-image",
    input={"prompt": "A glass fox in morning light"},
    max_credits=50,                # refuse anything pricier, before any charge
)

for artifact in result["job"]["artifacts"]:
    data = renderly.download_artifact(artifact["id"])

run() quotes, checks max_credits, creates the job with a server-side wait of up to 60 seconds and then long-polls until the job is completed or refunded.

Step by step

models = renderly.search_models("portrait", kind="image", available=True)["models"]
model = renderly.model(models[0]["id"])            # creation fields + inputSchema
quote = renderly.quote(model_id=model["id"], operation=model["operation"], sku=model["sku"], input=input)  # free
job = renderly.create_job(quote_id=quote["quoteId"], input=input, webhook_url="https://example.com/hooks/renderly", wait=30)["job"]
done = renderly.wait_for_job(job["id"], on_update=lambda j: print(j["status"]))
link = renderly.artifact(done["artifacts"][0]["id"])  # {"url", "expiresIn"}: 15 minutes

• Inputs: file = renderly.upload(data, kind="image") or renderly.upload_from_url("https://…/photo.png", kind="image"), then pass {"inputAssetId": file["id"]} in the model's input field.
• Retries: GETs and job creation retry network errors, 5xx and 429 (honouring Retry-After up to 60 s); job creation reuses one request ID, so a retry never starts a second job. Quotes retry at most once; uploads and cancellation retry only after 429.
• Rate limits: renderly.last_rate_limit holds limit, remaining, reset and retry_after; renderly.last_request_id the latest X-Request-Id.
• Errors: failures raise RenderlyError with code, status, request_id and, for 429, retry_after.

Webhooks

from renderly_ai import verify_webhook

# Use the raw request body exactly as received.
event = verify_webhook(raw_body, headers["Renderly-Signature"], os.environ["RENDERLY_WEBHOOK_SECRET"])
if event["type"] == "job.completed":
    artifacts = event["data"]["job"]["artifacts"]
elif event["type"] == "balance.low":
    balance = event["data"]["balance"]

Full guide: https://renderly-web-production.up.railway.app/docs.html · OpenAPI: https://renderly-web-production.up.railway.app/openapi.json