{ "openapi": "3.1.0", "info": { "title": "RenderHour API", "version": "1.0.0", "description": "Image, video and audio generation paid from a dollar balance. A job is charged only when it succeeds; a failed job costs nothing." }, "servers": [ { "url": "https://renderhour.com/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key: \"Authorization: Bearer rh_…\"" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Models": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "unit": { "type": "string", "enum": [ "image", "second", "run", "1k_chars", "audio_second" ] }, "description": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "string", "enum": [ "prompt", "text", "references", "startFrame", "endFrame", "audio" ] } }, "max_references": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "durations_s": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "aspect_ratios": { "type": "array", "items": { "type": "string" } }, "configs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "object", "properties": { "resolution": { "type": "string" }, "audio": { "type": "boolean" }, "quality": { "type": "string" }, "mode": { "type": "string" }, "duration_s": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "price_usd": { "type": "number", "exclusiveMinimum": 0 }, "list_price_usd": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] } }, "required": [ "config", "price_usd", "list_price_usd" ], "additionalProperties": false } } }, "required": [ "id", "title", "kind", "unit", "description", "inputs", "max_references", "durations_s", "aspect_ratios", "configs" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "GenerationRequest": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 64 }, "config": { "default": {}, "type": "object", "properties": { "resolution": { "type": "string" }, "audio": { "type": "boolean" }, "quality": { "type": "string" }, "mode": { "type": "string" }, "duration_s": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "count": { "default": 1, "type": "integer", "minimum": 1, "maximum": 4 }, "duration_s": { "type": "integer", "minimum": 1, "maximum": 30 }, "prompt": { "default": "", "type": "string", "maxLength": 4000 }, "text": { "type": "string", "maxLength": 10000 }, "aspect_ratio": { "type": "string", "maxLength": 8 }, "inputs": { "default": { "references": [] }, "type": "object", "properties": { "references": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "start_frame": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "end_frame": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "audio": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "webhook_url": { "type": "string", "maxLength": 2048 } }, "required": [ "model" ] }, "CostPreview": { "type": "object", "properties": { "model": { "type": "string" }, "unit": { "type": "string", "enum": [ "image", "second", "run", "1k_chars", "audio_second" ] }, "price_usd": { "type": "number", "exclusiveMinimum": 0 }, "list_price_usd": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] } }, "required": [ "model", "unit", "price_usd", "list_price_usd" ], "additionalProperties": false }, "Generation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "model": { "type": "string" }, "price_usd": { "type": "number", "minimum": 0 }, "failure_reason": { "anyOf": [ { "type": "string", "enum": [ "provider_error", "moderation", "timeout", "expired", "invalid_input", "internal" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "asset_id", "content_type", "url" ], "additionalProperties": false } } }, "required": [ "id", "status", "kind", "model", "price_usd", "failure_reason", "created_at", "finished_at", "outputs" ], "additionalProperties": false }, "GenerationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "model": { "type": "string" }, "price_usd": { "type": "number", "minimum": 0 }, "failure_reason": { "anyOf": [ { "type": "string", "enum": [ "provider_error", "moderation", "timeout", "expired", "invalid_input", "internal" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "asset_id", "content_type", "url" ], "additionalProperties": false } } }, "required": [ "id", "status", "kind", "model", "price_usd", "failure_reason", "created_at", "finished_at", "outputs" ], "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Upload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "kind", "content_type", "url" ], "additionalProperties": false }, "Balance": { "type": "object", "properties": { "balance_usd": { "type": "number", "minimum": 0 }, "concurrency": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "balance_usd", "concurrency" ], "additionalProperties": false }, "GenerationFinished": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "model": { "type": "string" }, "price_usd": { "type": "number", "minimum": 0 }, "failure_reason": { "anyOf": [ { "type": "string", "enum": [ "provider_error", "moderation", "timeout", "expired", "invalid_input", "internal" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "asset_id", "content_type", "url" ], "additionalProperties": false } }, "event": { "type": "string", "const": "generation.finished" } }, "required": [ "id", "status", "kind", "model", "price_usd", "failure_reason", "created_at", "finished_at", "outputs", "event" ], "additionalProperties": false } } }, "paths": { "/models": { "get": { "operationId": "listModels", "summary": "Catalog with rates", "responses": { "200": { "description": "The models on sale and their prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Models" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cost-preview": { "post": { "operationId": "previewCost", "summary": "Price of a request without running it", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" } } } }, "responses": { "200": { "description": "The price the same request would be charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostPreview" } } } }, "400": { "description": "The request is not valid or the model is not sold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads": { "post": { "operationId": "uploadFile", "summary": "Upload an input file", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "The stored file; pass its id in `inputs`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "No file, or an audio file that cannot be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The file is larger than 4 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The file type is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generations": { "post": { "operationId": "createGeneration", "summary": "Start a generation", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 200 }, "description": "Repeating a request with the same key returns the same job and never charges twice." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" } } } }, "responses": { "200": { "description": "The job this key already created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "201": { "description": "The job was taken and its price reserved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "400": { "description": "The request is not valid or the model is not sold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the price; nothing was started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The account already runs as many jobs as it may", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listGenerations", "summary": "List generations, newest first", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`next_cursor` of the previous page" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "A page of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationList" } } } }, "400": { "description": "The cursor is not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generations/{id}": { "get": { "operationId": "getGeneration", "summary": "Status and result of a generation", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such job on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balance": { "get": { "operationId": "getBalance", "summary": "Dollar balance and the limit on parallel jobs", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "description": "The API key is missing, unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Generation is not switched on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "generation.finished": { "post": { "operationId": "onGenerationFinished", "summary": "Sent to `webhook_url` when a job succeeds or fails", "description": "Signed in the RenderHour-Signature header as `t=,v1=` with the webhook secret of the API key. Retried after 30 s, 2 min, 10 min, 30 min and 2 h until it is answered with a 2xx status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationFinished" } } } }, "responses": { "200": { "description": "Received" } } } } } }