{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Renderly API", "version": "2026-10-26", "summary": "One key and one credit wallet for image, video, audio, 3D and language models.", "description": "Flow: find a model (GET /models, GET /models/{id} for its inputSchema) → POST /quotes (free) → review maxCredits → POST /jobs with a requestId → GET /jobs/{id}?wait=60 until completed or refunded → GET /artifacts/{id} for a 15-minute download link. 1 credit = US$0.01.\n\nAuthentication: `Authorization: Bearer ` on every non-public route. Keys are created in Settings → API access (Read only or Read & create; 30, 90, 365 days or no expiry; optional monthly spend limit). Session-only routes (API key management, webhook endpoint management, callback secret, alerts, account export and deletion) are not callable with API keys and are not part of this document.\n\nLimits: 600 requests per minute per key. Account limits per minute by tier (lifetime purchased credits): standard (<10,000) 120 quotes, 60 jobs, 300 downloads; growth (≥10,000) 240 / 120 / 600; scale (≥100,000) 600 / 300 / 1,200. Rate-limited responses carry X-RateLimit-* headers; 429 adds Retry-After.\n\nRetention: results 7 days by default (1 hour – 30 days selectable), uploaded inputs 24 hours, download links 15 minutes.\n\nErrors: `{\"error\": {\"code\", \"message\"}}`. Codes: invalid_request, invalid_input, settings_not_quoted, invalid_upload_url (400); authentication_required (401); api_scope_forbidden, verified_account_required, account_temporarily_restricted, payment_account_review_required, origin_not_allowed (403); not_found, quote_not_found (404); insufficient_balance, quote_expired, quote_price_changed, quote_already_used, quote_input_mismatch, request_id_conflict, job_not_cancellable, key_spend_limit_reached (409); artifact_expired (410); rate_limited (429); upload_fetch_failed (502); model_unavailable, input_media_not_available, service_unavailable (503).\n\nModel lifecycle: models with API usage get at least 14 days notice before removal (marked deprecated in the catalogue), except supplier-forced or safety removals.", "termsOfService": "https://renderly-web-production.up.railway.app/terms.html", "contact": { "name": "Renderly support", "url": "https://renderly-web-production.up.railway.app/contact.html" } }, "externalDocs": { "description": "API guide", "url": "https://renderly-web-production.up.railway.app/docs.html" }, "servers": [ { "url": "https://woovhhwoevjoipwltiwy.supabase.co/functions/v1/core-api", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Models", "description": "Public catalogue and search. No key needed." }, { "name": "Account", "description": "Wallet, ledger, usage and limits." }, { "name": "Jobs", "description": "Quotes, job creation, status and cancellation." }, { "name": "Files", "description": "Input uploads and result downloads." }, { "name": "Service", "description": "Public status." } ], "paths": { "/catalog": { "get": { "operationId": "getCatalog", "tags": [ "Models" ], "summary": "Full public catalogue", "description": "Every public model with settings, availability and price information. Prefer GET /models for search and paging.", "security": [], "x-renderly-scope": "public", "responses": { "200": { "description": "The catalogue.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/catalog/details": { "get": { "operationId": "getCatalogDetails", "tags": [ "Models" ], "summary": "Creation settings for up to 100 models", "security": [], "x-renderly-scope": "public", "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated model IDs (1–100).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model details.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogDetails" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/catalog/prices": { "get": { "operationId": "getCatalogPrices", "tags": [ "Models" ], "summary": "Display prices for up to 12 models", "security": [], "x-renderly-scope": "public", "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated model IDs (1–12).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Prices.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogPrices" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "Search models", "security": [], "x-renderly-scope": "public", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free text: name, maker or task.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Output kind: image, video, audio, language, 3d or tool.", "schema": { "type": "string" } }, { "name": "operation", "in": "query", "required": false, "description": "Task, e.g. text-to-image.", "schema": { "type": "string" } }, { "name": "maker", "in": "query", "required": false, "description": "Model maker.", "schema": { "type": "string" } }, { "name": "available", "in": "query", "required": false, "description": "Only models that can be quoted now.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of compact model entries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPage" }, "example": { "models": [ { "id": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "name": "Example Image Model", "maker": "Example Labs", "kind": "image", "operation": "text-to-image", "capabilities": [ "text-to-image" ], "available": true, "sku": "selected-settings-v1", "pricingMode": "selected_input", "billingUnit": "image", "price": { "credits": "8", "usd": "0.08", "billingUnit": "image" } } ], "nextCursor": "eyJvIjo1MH0", "total": 1240 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/models/{id}": { "get": { "operationId": "getModel", "tags": [ "Models" ], "summary": "One model with its input schema", "security": [], "x-renderly-scope": "public", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Model ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The model.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelResponse" }, "example": { "model": { "id": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "name": "Example Image Model", "maker": "Example Labs", "kind": "image", "operation": "text-to-image", "capabilities": [ "text-to-image" ], "available": true, "sku": "selected-settings-v1", "pricingMode": "selected_input", "billingUnit": "image", "price": { "credits": "8", "usd": "0.08", "billingUnit": "image" }, "creation": { "dynamic": true, "promptField": "p0", "fields": [ { "id": "p0", "type": "string", "label": "Prompt", "required": true, "maxLength": 4000 }, { "id": "p1", "role": "image", "type": "string", "label": "image", "required": false } ] }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "parameters" ], "properties": { "parameters": { "type": "object", "required": [ "p0" ], "properties": { "p0": { "type": "string", "maxLength": 4000 }, "p1": { "type": "string", "format": "uuid", "description": "image: an inputAssetId returned by POST /uploads?kind=image" } } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "Service" ], "summary": "Service status", "description": "Live component checks, 90 daily generation-outcome rows and published incidents.", "security": [], "x-renderly-scope": "public", "responses": { "200": { "description": "Status.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" }, "example": { "generatedAt": "2026-10-26T09:00:00Z", "components": [ { "id": "api", "name": "API", "state": "operational", "checkedAt": "2026-10-26T08:59:30Z" } ], "daily": [ { "date": "2026-10-25", "jobs": 18234, "completed": 18120, "refunded": 114, "deliveryFailures": 3, "completionRate": "99.4" } ], "incidents": [] } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Account, tier, limits and calling key", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "responses": { "200": { "description": "The account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "account": { "id": "b5c1…", "email": "dev@example.com", "tier": "standard", "limits": { "requestsPerMinute": 600, "quotesPerMinute": 120, "jobsPerMinute": 60, "downloadsPerMinute": 300 } }, "key": { "id": "e2a9…", "name": "Production", "prefix": "rly_live_a1b2c3d4e5", "scopes": [ "read", "generate" ], "expiresAt": "2027-10-26T00:00:00Z", "monthlySpendLimit": 50000, "monthSpent": 1234 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet": { "get": { "operationId": "getWallet", "tags": [ "Account" ], "summary": "Balance and reserved credits", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "responses": { "200": { "description": "The wallet.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" }, "example": { "balance": 1250, "reserved": 16, "lowBalanceCredits": 200, "ledger": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/ledger": { "get": { "operationId": "listLedger", "tags": [ "Account" ], "summary": "Ledger entries", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Entry ID: return older entries (nextBefore).", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Only this entry kind.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "ISO 8601 start.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "ISO 8601 end.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of entries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerPage" }, "example": { "entries": [ { "id": "9811", "jobId": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "kind": "charge", "amount": -8, "balanceAfter": 1250, "createdAt": "2026-10-26T09:00:00Z" } ], "nextBefore": "9811" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/usage": { "get": { "operationId": "getUsage", "tags": [ "Account" ], "summary": "Usage by day, model or key", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "ISO 8601 start; default 30 days ago. Window at most 366 days.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "ISO 8601 end; default now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "groupBy", "in": "query", "required": false, "description": "Grouping.", "schema": { "type": "string", "enum": [ "day", "model", "key" ], "default": "day" } } ], "responses": { "200": { "description": "Usage.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "from": "2026-09-26T00:00:00Z", "to": "2026-10-26T00:00:00Z", "groupBy": "model", "totals": { "jobs": 42, "completed": 40, "refunded": 2, "inProgress": 0, "chargedCredits": 336, "refundedCredits": 16, "reservedCredits": 0 }, "rows": [ { "key": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "jobs": 42, "completed": 40, "refunded": 2, "inProgress": 0, "chargedCredits": 336, "refundedCredits": 16, "reservedCredits": 0 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/quotes": { "post": { "operationId": "createQuote", "tags": [ "Jobs" ], "summary": "Price a request (free)", "description": "Validates the input and returns a binding price. Quoting never charges credits. Retry at most once on an uncertain response; request a new quote instead.", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "The quote.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "example": { "quoteId": "0b6f2d1e-9c8a-4b7d-a6e5-f4d3c2b1a098", "credits": 8, "maxCredits": 8, "expiresAt": "2026-10-26T09:10:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/jobs": { "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "summary": "Job history", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "ISO timestamp (nextBefore) for the next page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated: active, queued, processing, completed, refunded.", "schema": { "type": "string" } }, { "name": "modelId", "in": "query", "required": false, "description": "Only this model.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "ISO 8601 start.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "ISO 8601 end.", "schema": { "type": "string", "format": "date-time" } }, { "name": "keyId", "in": "query", "required": false, "description": "Only jobs created through this API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of jobs, newest first.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPage" }, "example": { "jobs": [ { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "modelName": "Example Image Model", "kind": "image", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": "2026-10-26T09:00:14.000Z", "refundedAt": null, "status": "completed", "credits": 8, "chargedCredits": 8, "refundCredits": null, "errorMessage": null, "artifacts": [ { "id": "c1b2a3d4-e5f6-4789-8abc-def012345678", "kind": "image", "mimeType": "image/png", "bytes": 1843200, "expiresAt": "2026-11-02T09:00:14.000Z", "createdAt": "2026-10-26T09:00:14.000Z", "available": true } ] } ], "nextBefore": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createJob", "tags": [ "Jobs" ], "summary": "Accept a quote and start the job", "description": "Reserves the quoted credits and starts generation. The same requestId and body always return the original job (reused: true), so retrying an uncertain response is safe. With ?wait=N or Prefer: wait=N the response is held up to N seconds until the job is final.", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "create", "parameters": [ { "name": "wait", "in": "query", "required": false, "description": "Hold the response up to N seconds for a final state.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } }, { "name": "Prefer", "in": "header", "required": false, "description": "Alternative to ?wait: \"wait=N\".", "schema": { "type": "string", "examples": [ "wait=30" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "200": { "description": "The job.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" }, "example": { "job": { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "modelName": "Example Image Model", "kind": "image", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": null, "refundedAt": null, "status": "queued", "credits": 8, "chargedCredits": null, "refundCredits": null, "errorMessage": null, "artifacts": [] }, "balance": 1242, "reused": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "One job", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "Long poll: answer as soon as the job is final, at most N seconds.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } } ], "responses": { "200": { "description": "The job.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" } }, "required": [ "job" ] }, "example": { "job": { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "modelName": "Example Image Model", "kind": "image", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": "2026-10-26T09:00:14.000Z", "refundedAt": null, "status": "completed", "credits": 8, "chargedCredits": 8, "refundCredits": null, "errorMessage": null, "artifacts": [ { "id": "c1b2a3d4-e5f6-4789-8abc-def012345678", "kind": "image", "mimeType": "image/png", "bytes": 1843200, "expiresAt": "2026-11-02T09:00:14.000Z", "createdAt": "2026-10-26T09:00:14.000Z", "available": true } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/jobs/{id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Jobs" ], "summary": "Cancel a job not yet sent for generation", "description": "Returns the full reservation. 409 job_not_cancellable once submission started.", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "create", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "example": {} } } } }, "responses": { "200": { "description": "Cancelled.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/artifacts/{id}": { "get": { "operationId": "getArtifact", "tags": [ "Files" ], "summary": "Signed download URL", "description": "The URL is valid for 15 minutes; request a new one when it expires. Results are stored 7 days by default (1 hour to 30 days selectable).", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artifact ID from job.artifacts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The link.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactLink" }, "example": { "url": "https://storage.example/renderly/result.png?token=…", "expiresIn": 900 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/uploads": { "post": { "operationId": "createUpload", "tags": [ "Files" ], "summary": "Upload an input file (bytes or public URL)", "description": "Send raw bytes as application/octet-stream, or JSON {\"url\": \"https://…\"} to import a public HTTPS file. Max 24 MiB; validation matches the workspace. Uploaded inputs are kept 24 hours.", "security": [ { "bearerAuth": [] } ], "x-renderly-scope": "create", "parameters": [ { "name": "kind", "in": "query", "required": true, "description": "Input kind.", "schema": { "type": "string", "enum": [ "image", "video", "audio" ] } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" } } } }, "responses": { "200": { "description": "The stored input.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" }, "example": { "id": "5f0e…", "kind": "image", "mimeType": "image/png", "bytes": 482113, "width": 1024, "height": 1024, "durationSeconds": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "webhooks": { "jobCompleted": { "post": { "operationId": "webhook_job_completed", "summary": "A job finished and its artifacts are ready", "description": "POST to your HTTPS endpoint. Answer 2xx within 8 seconds; other answers, timeouts and redirects are retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h.", "parameters": [ { "name": "Renderly-Event", "in": "header", "required": true, "description": "Event type.", "schema": { "type": "string" } }, { "name": "Renderly-Event-Id", "in": "header", "required": true, "description": "Event ID; ignore duplicates.", "schema": { "type": "string" } }, { "name": "Renderly-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. Account endpoints sign with the endpoint secret (whsec_…); per-request webhookUrl callbacks with the account callback secret. Reject timestamps older than 5 minutes.", "schema": { "type": "string", "examples": [ "t=1793001614,v1=5f2b…" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_5120", "type": "job.completed", "createdAt": "2026-10-26T09:00:15Z", "attempt": 1, "data": { "job": { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": "2026-10-26T09:00:14.000Z", "refundedAt": null, "status": "completed", "credits": 8, "chargedCredits": 8, "refundCredits": null, "errorMessage": null, "artifacts": [ { "id": "c1b2a3d4-e5f6-4789-8abc-def012345678", "kind": "image", "mimeType": "image/png", "bytes": 1843200, "expiresAt": "2026-11-02T09:00:14.000Z", "createdAt": "2026-10-26T09:00:14.000Z", "available": true } ] } } } } } }, "responses": { "2XX": { "description": "Received." } } } }, "jobRefunded": { "post": { "operationId": "webhook_job_refunded", "summary": "A job failed and its credits were returned", "description": "POST to your HTTPS endpoint. Answer 2xx within 8 seconds; other answers, timeouts and redirects are retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h.", "parameters": [ { "name": "Renderly-Event", "in": "header", "required": true, "description": "Event type.", "schema": { "type": "string" } }, { "name": "Renderly-Event-Id", "in": "header", "required": true, "description": "Event ID; ignore duplicates.", "schema": { "type": "string" } }, { "name": "Renderly-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. Account endpoints sign with the endpoint secret (whsec_…); per-request webhookUrl callbacks with the account callback secret. Reject timestamps older than 5 minutes.", "schema": { "type": "string", "examples": [ "t=1793001614,v1=5f2b…" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_5120", "type": "job.refunded", "createdAt": "2026-10-26T09:00:15Z", "attempt": 1, "data": { "job": { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": null, "refundedAt": "2026-10-26T09:01:00.000Z", "status": "refunded", "credits": 8, "chargedCredits": 0, "refundCredits": 8, "errorMessage": "The result could not be delivered. Your credits were returned.", "artifacts": [] } } } } } }, "responses": { "2XX": { "description": "Received." } } } }, "balanceLow": { "post": { "operationId": "webhook_balance_low", "summary": "The balance crossed below the account low-balance threshold", "description": "POST to your HTTPS endpoint. Answer 2xx within 8 seconds; other answers, timeouts and redirects are retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h.", "parameters": [ { "name": "Renderly-Event", "in": "header", "required": true, "description": "Event type.", "schema": { "type": "string" } }, { "name": "Renderly-Event-Id", "in": "header", "required": true, "description": "Event ID; ignore duplicates.", "schema": { "type": "string" } }, { "name": "Renderly-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. Account endpoints sign with the endpoint secret (whsec_…); per-request webhookUrl callbacks with the account callback secret. Reject timestamps older than 5 minutes.", "schema": { "type": "string", "examples": [ "t=1793001614,v1=5f2b…" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_5120", "type": "balance.low", "createdAt": "2026-10-26T09:00:15Z", "attempt": 1, "data": { "balance": 180, "lowBalanceCredits": 200 } } } } }, "responses": { "2XX": { "description": "Received." } } } }, "webhookTest": { "post": { "operationId": "webhook_webhook_test", "summary": "Sent by \"Send test\" in Settings", "description": "POST to your HTTPS endpoint. Answer 2xx within 8 seconds; other answers, timeouts and redirects are retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h.", "parameters": [ { "name": "Renderly-Event", "in": "header", "required": true, "description": "Event type.", "schema": { "type": "string" } }, { "name": "Renderly-Event-Id", "in": "header", "required": true, "description": "Event ID; ignore duplicates.", "schema": { "type": "string" } }, { "name": "Renderly-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. Account endpoints sign with the endpoint secret (whsec_…); per-request webhookUrl callbacks with the account callback secret. Reject timestamps older than 5 minutes.", "schema": { "type": "string", "examples": [ "t=1793001614,v1=5f2b…" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_5120", "type": "webhook.test", "createdAt": "2026-10-26T09:00:15Z", "attempt": 1, "data": { "test": true } } } } }, "responses": { "2XX": { "description": "Received." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rly_…", "description": "API key from Settings → API access. Read-only keys can call read routes; Read & create keys can also quote, create, cancel and upload." } }, "headers": { "X-Request-Id": { "description": "Unique request ID (req_<32 hex>). Quote it in support requests.", "schema": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" } }, "X-RateLimit-Limit": { "description": "Requests allowed in the current minute by the tightest limiter that applied.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the current minute window ends.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (429).", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid request or input: invalid_request, invalid_input, settings_not_quoted, invalid_upload_url.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Please check your request." } } } } }, "Unauthorized": { "description": "Missing, invalid, expired or revoked key: authentication_required.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "authentication_required", "message": "Please sign in to continue." } } } } }, "Forbidden": { "description": "api_scope_forbidden, verified_account_required, account_temporarily_restricted, payment_account_review_required, origin_not_allowed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "api_scope_forbidden", "message": "This API key does not allow this action." } } } } }, "NotFound": { "description": "not_found or quote_not_found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "This resource is unavailable." } } } } }, "Conflict": { "description": "insufficient_balance, quote_expired, quote_price_changed, quote_already_used, quote_input_mismatch, request_id_conflict, job_not_cancellable, key_spend_limit_reached.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "Your credit balance is too low for this creation." } } } } }, "Gone": { "description": "artifact_expired: the stored result has been deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "artifact_expired", "message": "This file has expired and is no longer available." } } } } }, "RateLimited": { "description": "rate_limited: wait Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Please wait a moment before trying again." } } } } }, "BadGateway": { "description": "upload_fetch_failed: the URL could not be fetched.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upload_fetch_failed", "message": "The file could not be downloaded from that address." } } } } }, "ServiceUnavailable": { "description": "model_unavailable, input_media_not_available or service_unavailable. Retry later; an uncertain job submission must keep its requestId.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "model_unavailable", "message": "This model is not available for generation yet." } } } } } }, "schemas": { "Money": { "type": "object", "properties": { "currency": { "const": "USD" }, "usdPerCredit": { "type": "number", "description": "0.01." }, "totalUsd": { "type": "string", "description": "Quote total in USD (quotes only)." }, "maximumUsd": { "type": "string", "description": "Quote maximum in USD (quotes only)." } }, "required": [ "currency", "usdPerCredit" ], "description": "Added to quote, job and model list responses." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code. See the error code list in the API description.", "examples": [ "insufficient_balance" ] }, "message": { "type": "string", "description": "Human-readable explanation, safe to show to end users." } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "quote_price_changed", "message": "The live price has increased. Review the new price before creating. You have not been charged." } } }, "Artifact": { "type": "object", "properties": { "id": { "type": "string", "description": "Artifact ID for GET /artifacts/{id}.", "format": "uuid" }, "kind": { "type": "string", "description": "image, video, audio, text or 3d." }, "mimeType": { "type": "string", "description": "MIME type." }, "bytes": { "type": "integer", "description": "Size in bytes." }, "expiresAt": { "type": "string", "description": "When the stored result is deleted (default 7 days; 1 hour to 30 days selectable in the workspace).", "format": "date-time" }, "createdAt": { "type": "string", "description": "Creation time.", "format": "date-time" }, "available": { "type": "boolean", "description": "False once expired or deleted." } }, "required": [ "id", "kind", "mimeType", "bytes" ] }, "JobStatus": { "type": "string", "enum": [ "queued", "processing", "reconciling", "completed", "refunded" ], "description": "completed and refunded are final. reconciling still needs a later check." }, "Job": { "type": "object", "properties": { "id": { "type": "string", "description": "Job ID.", "format": "uuid" }, "modelId": { "type": "string", "description": "Opaque catalog model ID." }, "modelName": { "type": "string", "description": "Display name." }, "kind": { "type": "string", "description": "Output kind." }, "operation": { "type": [ "string", "null" ], "description": "Task, e.g. text-to-image." }, "requestId": { "type": "string", "description": "The idempotency key it was created with." }, "createdAt": { "type": "string", "description": "Accepted at.", "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "description": "Last change.", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "description": "Completed at.", "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "description": "Refunded at.", "format": "date-time" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "credits": { "type": [ "number", "string" ], "description": "Credits reserved when the job was accepted. Credits (1 credit = US$0.01); may be a decimal string." }, "chargedCredits": { "type": [ "number", "string", "null" ], "description": "Credits finally charged. Credits (1 credit = US$0.01); may be a decimal string." }, "refundCredits": { "type": [ "number", "string", "null" ], "description": "Credits returned. Credits (1 credit = US$0.01); may be a decimal string." }, "errorMessage": { "type": [ "string", "null" ], "description": "Customer-safe reason for a refund." }, "cancelled": { "type": "boolean", "description": "Present and true when the customer cancelled the job." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } } }, "required": [ "id", "modelId", "status", "credits", "createdAt", "artifacts" ], "example": { "id": "7d0c5b2e-4a1f-4c3b-9e8d-2f6a1b0c9d8e", "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "modelName": "Example Image Model", "kind": "image", "operation": "text-to-image", "requestId": "my-app-order-1042", "createdAt": "2026-10-26T09:00:00.000Z", "updatedAt": "2026-10-26T09:00:14.000Z", "completedAt": "2026-10-26T09:00:14.000Z", "refundedAt": null, "status": "completed", "credits": 8, "chargedCredits": 8, "refundCredits": null, "errorMessage": null, "artifacts": [ { "id": "c1b2a3d4-e5f6-4789-8abc-def012345678", "kind": "image", "mimeType": "image/png", "bytes": 1843200, "expiresAt": "2026-11-02T09:00:14.000Z", "createdAt": "2026-10-26T09:00:14.000Z", "available": true } ] } }, "QuoteRequest": { "type": "object", "properties": { "modelId": { "type": "string", "description": "Opaque model ID from /models or /catalog." }, "operation": { "type": "string", "description": "The model operation, e.g. text-to-image." }, "sku": { "type": "string", "description": "Model SKU; selected-input models use selected-settings-v1.", "default": "selected-settings-v1" }, "input": { "type": "object", "description": "The complete model input. Its JSON Schema is GET /models/{id} inputSchema. Dynamic models take {\"parameters\": {\"p0\": …}}; fixed models take their prompt field and fixed settings. File inputs take {\"inputAssetId\": \"…\"} from POST /uploads.", "additionalProperties": true } }, "required": [ "modelId", "operation", "input" ], "example": { "modelId": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "operation": "text-to-image", "sku": "selected-settings-v1", "input": { "parameters": { "p0": "A glass fox in morning light" } } } }, "Quote": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "Quote ID for POST /jobs.", "format": "uuid" }, "credits": { "type": [ "number", "string" ], "description": "Expected credits. Credits (1 credit = US$0.01); may be a decimal string." }, "maxCredits": { "type": [ "number", "string" ], "description": "The most this request can reserve. Review it before creating a job. Credits (1 credit = US$0.01); may be a decimal string." }, "expiresAt": { "type": "string", "description": "Accept before this time.", "format": "date-time" }, "maximumReserve": { "type": "boolean", "description": "True for metered models: maxCredits is reserved and the unused part is refunded." }, "money": { "$ref": "#/components/schemas/Money" } }, "required": [ "quoteId", "credits", "expiresAt" ], "additionalProperties": true, "example": { "quoteId": "0b6f2d1e-9c8a-4b7d-a6e5-f4d3c2b1a098", "credits": 8, "maxCredits": 8, "expiresAt": "2026-10-26T09:10:00.000Z" } }, "CreateJobRequest": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "From POST /quotes.", "format": "uuid" }, "requestId": { "type": "string", "description": "Your idempotency key. Reuse it with the same body when retrying an uncertain response; the original job is returned.", "pattern": "^[A-Za-z0-9_-]{8,100}$" }, "input": { "type": "object", "description": "Exactly the input that was quoted.", "additionalProperties": true }, "webhookUrl": { "type": "string", "description": "Optional public HTTPS URL notified (signed) when this job completes or is refunded.", "format": "uri" } }, "required": [ "quoteId", "requestId", "input" ], "example": { "quoteId": "0b6f2d1e-9c8a-4b7d-a6e5-f4d3c2b1a098", "requestId": "my-app-order-1042", "input": { "parameters": { "p0": "A glass fox in morning light" } }, "webhookUrl": "https://example.com/hooks/renderly" } }, "CreateJobResponse": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "balance": { "type": [ "number", "string" ], "description": "Balance after the reservation. Credits (1 credit = US$0.01); may be a decimal string." }, "reused": { "type": "boolean", "description": "True when this requestId was already accepted and the original job is returned." }, "money": { "$ref": "#/components/schemas/Money" } }, "required": [ "job", "balance", "reused" ] }, "CancelJobResponse": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "balance": { "type": [ "number", "string" ], "description": "Balance after the refund. Credits (1 credit = US$0.01); may be a decimal string." }, "cancelled": { "const": true } }, "required": [ "job", "balance", "cancelled" ] }, "JobPage": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "nextBefore": { "type": [ "string", "null" ], "description": "Pass as before for the next page; null on the last page.", "format": "date-time" } }, "required": [ "jobs", "nextBefore" ] }, "ArtifactLink": { "type": "object", "properties": { "url": { "type": "string", "description": "Signed download URL. Do not send your API key to it.", "format": "uri" }, "expiresIn": { "type": "integer", "description": "Seconds until the URL expires (900)." } }, "required": [ "url", "expiresIn" ], "example": { "url": "https://storage.example/renderly/result.png?token=…", "expiresIn": 900 } }, "Upload": { "type": "object", "properties": { "id": { "type": "string", "description": "Use as {\"inputAssetId\": id} in the model input.", "format": "uuid" }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "mimeType": { "type": "string", "description": "Detected MIME type." }, "bytes": { "type": "integer", "description": "Size." }, "width": { "type": [ "integer", "null" ], "description": "Pixels." }, "height": { "type": [ "integer", "null" ], "description": "Pixels." }, "durationSeconds": { "type": [ "number", "null" ], "description": "Media duration." } }, "required": [ "id", "kind", "mimeType", "bytes" ] }, "UploadUrlRequest": { "type": "object", "properties": { "url": { "type": "string", "description": "Public HTTPS address of the file (max 24 MiB). Private, local and redirect-to-private addresses are refused.", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false, "example": { "url": "https://example.com/reference.png" } }, "LedgerEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Entry ID." }, "jobId": { "type": [ "string", "null" ], "description": "Related job." }, "kind": { "type": "string", "description": "Entry kind, e.g. purchase, charge, refund, adjustment." }, "amount": { "type": [ "number", "string" ], "description": "Signed credit change. Credits (1 credit = US$0.01); may be a decimal string." }, "balanceAfter": { "type": [ "number", "string" ], "description": "Balance after this entry. Credits (1 credit = US$0.01); may be a decimal string." }, "createdAt": { "type": "string", "description": "When.", "format": "date-time" } }, "required": [ "id", "jobId", "kind", "amount", "balanceAfter", "createdAt" ] }, "LedgerPage": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "nextBefore": { "type": [ "string", "null" ], "description": "Pass as before for the next page." } }, "required": [ "entries", "nextBefore" ] }, "Wallet": { "type": "object", "properties": { "balance": { "type": [ "number", "string" ], "description": "Spendable credits. Reservations of unfinished jobs are already deducted. Credits (1 credit = US$0.01); may be a decimal string." }, "reserved": { "type": [ "number", "string" ], "description": "Credits held by unfinished jobs. Credits (1 credit = US$0.01); may be a decimal string." }, "lowBalanceCredits": { "type": [ "number", "string", "null" ], "description": "Low-balance alert threshold, if set. Credits (1 credit = US$0.01); may be a decimal string." }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" }, "description": "Recent entries, kept for compatibility. Use GET /ledger to page." } }, "required": [ "balance" ], "additionalProperties": true, "example": { "balance": 1250, "reserved": 16, "lowBalanceCredits": 200, "ledger": [] } }, "Limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer", "description": "Per API key." }, "quotesPerMinute": { "type": "integer", "description": "Per account." }, "jobsPerMinute": { "type": "integer", "description": "Per account." }, "downloadsPerMinute": { "type": "integer", "description": "Per account." } }, "required": [ "requestsPerMinute", "quotesPerMinute", "jobsPerMinute", "downloadsPerMinute" ] }, "Account": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account ID." }, "email": { "type": "string", "description": "Verified email." }, "tier": { "type": "string", "enum": [ "standard", "growth", "scale" ] }, "limits": { "$ref": "#/components/schemas/Limits" } }, "required": [ "id", "email", "tier", "limits" ] }, "key": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Key ID." }, "name": { "type": "string", "description": "Key name." }, "prefix": { "type": "string", "description": "Masked prefix." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "generate" ] } }, "expiresAt": { "type": [ "string", "null" ], "description": "Expiry; null for no expiry.", "format": "date-time" }, "monthlySpendLimit": { "type": [ "number", "string", "null" ], "description": "Credits per calendar month (UTC), if set. Credits (1 credit = US$0.01); may be a decimal string." }, "monthSpent": { "type": [ "number", "string" ], "description": "Credits spent this month through this key. Credits (1 credit = US$0.01); may be a decimal string." } }, "required": [ "id", "name", "prefix", "scopes", "expiresAt", "monthlySpendLimit", "monthSpent" ] }, { "type": "null" } ], "description": "The calling API key, or null for a browser session." } }, "required": [ "account", "key" ], "example": { "account": { "id": "b5c1…", "email": "dev@example.com", "tier": "standard", "limits": { "requestsPerMinute": 600, "quotesPerMinute": 120, "jobsPerMinute": 60, "downloadsPerMinute": 300 } }, "key": { "id": "e2a9…", "name": "Production", "prefix": "rly_live_a1b2c3d4e5", "scopes": [ "read", "generate" ], "expiresAt": "2027-10-26T00:00:00Z", "monthlySpendLimit": 50000, "monthSpent": 1234 } } }, "UsageCounts": { "type": "object", "properties": { "jobs": { "type": "integer", "description": "Jobs created." }, "completed": { "type": "integer", "description": "Completed." }, "refunded": { "type": "integer", "description": "Refunded." }, "inProgress": { "type": "integer", "description": "Not final yet." }, "chargedCredits": { "type": [ "number", "string" ], "description": "Charged. Credits (1 credit = US$0.01); may be a decimal string." }, "refundedCredits": { "type": [ "number", "string" ], "description": "Refunded. Credits (1 credit = US$0.01); may be a decimal string." }, "reservedCredits": { "type": [ "number", "string" ], "description": "Still reserved. Credits (1 credit = US$0.01); may be a decimal string." } }, "required": [ "jobs", "completed", "refunded", "inProgress", "chargedCredits", "refundedCredits", "reservedCredits" ] }, "UsageRow": { "allOf": [ { "type": "object", "properties": { "key": { "type": "string", "description": "The group: a date (YYYY-MM-DD), a model ID or an API key ID (\"workspace\" for browser-created jobs)." } }, "required": [ "key" ] }, { "$ref": "#/components/schemas/UsageCounts" } ] }, "Usage": { "type": "object", "properties": { "from": { "type": "string", "description": "Window start.", "format": "date-time" }, "to": { "type": "string", "description": "Window end.", "format": "date-time" }, "groupBy": { "type": "string", "enum": [ "day", "model", "key" ] }, "totals": { "$ref": "#/components/schemas/UsageCounts" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } } }, "required": [ "from", "to", "groupBy", "totals", "rows" ] }, "Price": { "type": "object", "properties": { "credits": { "type": "string", "description": "Starting price in credits, as a decimal string." }, "usd": { "type": "string", "description": "The same in US dollars, as a decimal string." }, "billingUnit": { "type": "string", "description": "What one price unit buys: request, image, second, …" } }, "required": [ "credits", "usd", "billingUnit" ] }, "ModelSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque model ID." }, "name": { "type": "string", "description": "Display name." }, "maker": { "type": "string", "description": "Model maker." }, "kind": { "type": "string", "description": "image, video, audio, language, 3d or tool." }, "operation": { "type": [ "string", "null" ], "description": "Task, e.g. text-to-image." }, "capabilities": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean", "description": "Ready to quote now." }, "sku": { "type": [ "string", "null" ], "description": "SKU for POST /quotes." }, "pricingMode": { "type": [ "string", "null" ], "description": "How the price is computed." }, "billingUnit": { "type": [ "string", "null" ], "description": "Price unit." }, "price": { "oneOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "deprecated": { "type": "boolean", "description": "Present and true while a model is scheduled for removal (at least 14 days notice when it has API usage)." } }, "required": [ "id", "name", "kind", "available" ], "example": { "id": "model-3f1c2a9d8e7b6a5c4d3e2f1a0b9c8d7e", "name": "Example Image Model", "maker": "Example Labs", "kind": "image", "operation": "text-to-image", "capabilities": [ "text-to-image" ], "available": true, "sku": "selected-settings-v1", "pricingMode": "selected_input", "billingUnit": "image", "price": { "credits": "8", "usd": "0.08", "billingUnit": "image" } } }, "ModelPage": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page." }, "total": { "type": "integer", "description": "Matches across all pages." } }, "required": [ "models", "nextCursor", "total" ] }, "ModelField": { "type": "object", "properties": { "id": { "type": "string", "description": "Field ID, e.g. p0, used as the key in input.parameters." }, "label": { "type": "string", "description": "Human label." }, "type": { "type": "string", "description": "string, number, integer, boolean, array or object." }, "required": { "type": "boolean" }, "role": { "type": "string", "enum": [ "image", "video", "audio" ], "description": "Set for file inputs: pass upload IDs ({\"inputAssetId\": …})." }, "choices": { "type": "array", "items": {} }, "default": {}, "minimum": { "type": "number", "description": "Lower bound." }, "maximum": { "type": "number", "description": "Upper bound." }, "maxLength": { "type": "integer", "description": "Maximum string length." }, "minItems": { "type": "integer", "description": "Minimum array length." }, "maxItems": { "type": "integer", "description": "Maximum array length." }, "conditional": { "type": "boolean", "description": "Depends on other settings." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ModelField" } }, "item": { "$ref": "#/components/schemas/ModelField" } }, "required": [ "id", "type" ], "example": { "id": "p0", "role": "image", "type": "string", "label": "image", "required": true } }, "Creation": { "type": "object", "properties": { "dynamic": { "type": "boolean", "description": "True: send input.parameters keyed by field ID. False: send promptField plus fixedInput." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ModelField" } }, "promptField": { "type": "string", "description": "Prompt field name or ID." }, "fixedInput": { "type": "object", "additionalProperties": true, "description": "Settings to send unchanged." }, "maxPromptLength": { "type": "integer", "description": "Maximum prompt characters." } }, "required": [], "additionalProperties": true }, "ModelDetail": { "allOf": [ { "$ref": "#/components/schemas/ModelSummary" }, { "type": "object", "properties": { "creation": { "oneOf": [ { "$ref": "#/components/schemas/Creation" }, { "type": "null" } ] }, "inputSchema": { "type": "object", "description": "JSON Schema 2020-12 of the input object for POST /quotes and POST /jobs.", "additionalProperties": true } }, "required": [] } ] }, "ModelResponse": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelDetail" } }, "required": [ "model" ] }, "Catalog": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Full public catalogue entries: id, name, maker, kind, operation, sku, available, creation, options and price information." }, "updatedAt": { "type": "string", "description": "Generated at.", "format": "date-time" }, "pricingStatus": { "type": "string", "description": "ready or awaiting_provider_configuration." } }, "required": [ "models" ], "additionalProperties": true }, "CatalogDetails": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelDetail" } } }, "required": [ "models" ], "additionalProperties": true }, "CatalogPrices": { "type": "object", "properties": { "prices": { "type": "array", "items": { "type": "object", "properties": { "modelId": { "type": "string", "description": "Model ID." }, "operation": { "type": "string", "description": "Operation." }, "sku": { "type": "string", "description": "SKU." }, "credits": { "type": [ "number", "string" ], "description": "Display price in credits. Credits (1 credit = US$0.01); may be a decimal string." }, "billingUnit": { "type": "string", "description": "Unit." }, "observedAt": { "type": "string", "description": "Observed.", "format": "date-time" }, "validUntil": { "type": "string", "description": "Valid until.", "format": "date-time" } }, "required": [ "modelId", "credits" ], "additionalProperties": true } } }, "required": [ "prices" ] }, "ComponentState": { "type": "string", "enum": [ "operational", "degraded", "outage", "unknown" ] }, "Status": { "type": "object", "properties": { "generatedAt": { "type": "string", "description": "Generated at.", "format": "date-time" }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Component ID." }, "name": { "type": "string", "description": "Name." }, "state": { "$ref": "#/components/schemas/ComponentState" }, "checkedAt": { "type": [ "string", "null" ], "description": "Last check.", "format": "date-time" } }, "required": [ "id", "name", "state", "checkedAt" ] } }, "daily": { "type": "array", "description": "Up to 90 days, oldest first.", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD.", "format": "date" }, "jobs": { "type": "integer", "description": "Jobs." }, "completed": { "type": "integer", "description": "Completed." }, "refunded": { "type": "integer", "description": "Refunded." }, "deliveryFailures": { "type": "integer", "description": "Webhook delivery failures." }, "completionRate": { "type": [ "string", "null" ], "description": "Completed share, e.g. \"99.4\", or null with no jobs." } }, "required": [ "date", "jobs", "completed", "refunded", "deliveryFailures", "completionRate" ] } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Incident ID." }, "title": { "type": "string", "description": "Title." }, "state": { "type": "string", "description": "investigating, identified, monitoring or resolved." }, "impact": { "type": "string", "description": "none, minor, major or critical." }, "startedAt": { "type": "string", "description": "Start.", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "description": "End.", "format": "date-time" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "When.", "format": "date-time" }, "state": { "type": "string", "description": "State." }, "message": { "type": "string", "description": "Update text." } }, "required": [ "at", "state", "message" ] } } }, "required": [ "id", "title", "state", "impact", "startedAt", "resolvedAt", "updates" ] } } }, "required": [ "generatedAt", "components", "daily", "incidents" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID (evt_…). Use it to ignore duplicates." }, "type": { "type": "string", "enum": [ "job.completed", "job.refunded", "balance.low", "webhook.test" ] }, "createdAt": { "type": "string", "description": "Event time.", "format": "date-time" }, "attempt": { "type": "integer", "description": "Delivery attempt, from 1." }, "data": { "type": "object", "description": "job events: {job}; balance.low: {balance, lowBalanceCredits}; webhook.test: {test: true}.", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "balance": { "type": [ "number", "string" ], "description": "Balance at the crossing. Credits (1 credit = US$0.01); may be a decimal string." }, "lowBalanceCredits": { "type": [ "number", "string" ], "description": "The threshold crossed. Credits (1 credit = US$0.01); may be a decimal string." }, "test": { "const": true } } } }, "required": [ "id", "type", "createdAt", "attempt", "data" ] } } } }