{"openapi":"3.0.3","info":{"title":"Renderful API","version":"1.1.0","description":"Renderful API for image, video, audio, 3D, and text (LLM) generation. Supports bearer API keys and x402 payments.","contact":{"name":"Renderful Support","url":"https://renderful.ai","email":"support@renderful.ai"}},"servers":[{"url":"https://api.renderful.ai/api/v1","description":"Production"}],"tags":[{"name":"Models"},{"name":"Generations"},{"name":"Agents"}],"paths":{"/models":{"get":{"tags":["Models"],"operationId":"listModels","summary":"List available models","description":"Returns model catalog. Supports filtering by type and provider.","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["image-to-image"]},"description":"Filter models by generation type"},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["OpenAI"]},"description":"Filter models by provider name"}],"responses":{"200":{"description":"Model list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}}}}},"/agents/register":{"post":{"tags":["Agents"],"operationId":"registerAgent","summary":"Register an AI agent","description":"Create a new agent API key. Optionally includes trial balance with anti-abuse guardrails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegisterRequest"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegisterResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Registration capped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/deposit":{"post":{"tags":["Agents"],"operationId":"submitAgentDeposit","summary":"Submit a USDC transaction hash for balance credit","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepositRequest"}}}},"responses":{"200":{"description":"Deposit credited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepositResponse"}}}},"400":{"description":"Invalid deposit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/balance":{"get":{"tags":["Agents"],"operationId":"getAgentBalance","summary":"Get current balance and usage","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Balance and usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBalanceResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/quote":{"post":{"tags":["Agents"],"operationId":"getAgentQuote","summary":"Get a generation cost estimate","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentQuoteRequest"}}}},"responses":{"200":{"description":"Cost estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentQuoteResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/webhook":{"patch":{"tags":["Agents"],"operationId":"updateAgentWebhook","summary":"Set or update agent webhook URL","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWebhookRequest"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWebhookResponse"}}}},"400":{"description":"Invalid webhook URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generations":{"post":{"tags":["Generations"],"operationId":"createGeneration","summary":"Create a generation task","description":"Create image/video/audio/LLM tasks. LLM requests use type=text-to-text and are submitted via this same endpoint (not /v1/chat/completions). Supports either bearer API key auth or x402 payment via the x-payment header.","security":[{"bearerAuth":[]},{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}}},"responses":{"202":{"description":"Task accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationQueuedResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}}}}},"/generations/{id}":{"get":{"tags":["Generations"],"operationId":"getGeneration","summary":"Get generation status/result","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Generation task ID returned by POST /generations"}],"responses":{"200":{"description":"Task status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationStatusResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/predictions/{taskId}/result":{"get":{"tags":["Generations"],"operationId":"getPredictionResultLegacy","deprecated":true,"summary":"Legacy alias for generation status","description":"Deprecated alias for GET /generations/{id}. Use /generations/{id} instead. This endpoint is scheduled for removal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task status","headers":{"Deprecation":{"schema":{"type":"string"},"description":"Always set to true for this legacy alias."},"Sunset":{"schema":{"type":"string"},"description":"RFC1123 sunset date for alias removal (current target: Thu, 11 Jun 2026 03:59:07 GMT)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationStatusResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-deprecation":{"replacement":"/generations/{id}","sunset":"Thu, 11 Jun 2026 03:59:07 GMT","policy":"60-day compatibility window"}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Use Authorization: Bearer rf_... (agent) or sk_/vega_ key."},"x402Payment":{"type":"apiKey","in":"header","name":"x-payment","description":"Base64-encoded x402 payment payload. Used as permissionless payment auth when enabled."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]},"PaymentRequiredError":{"type":"object","properties":{"error":{"type":"string","example":"Payment required"},"message":{"type":"string"},"cost":{"type":"number"},"balance_available":{"type":"number"},"requirements":{"type":"object","additionalProperties":true,"description":"x402 payment requirements object when x402 flow is used"}},"required":["error"]},"ModelCost":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"ModelCapabilities":{"type":"object","properties":{"aspect_ratios":{"type":"array","items":{"type":"string"}},"resolutions":{"type":"array","items":{"type":"string"}},"durations":{"type":"array","items":{"type":"integer"}},"max_outputs":{"type":"integer"},"context_window_tokens":{"type":"integer"},"max_output_tokens":{"type":"integer"},"supports_vision":{"type":"boolean"},"supports_function_calling":{"type":"boolean"},"supports_streaming":{"type":"boolean"},"supports_json_mode":{"type":"boolean"},"input_modalities":{"type":"array","items":{"type":"string"}},"output_modalities":{"type":"array","items":{"type":"string"}}}},"Model":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"provider_slug":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["image-to-image"]},"description":{"type":"string"},"capabilities":{"$ref":"#/components/schemas/ModelCapabilities"},"cost":{"$ref":"#/components/schemas/ModelCost"},"dollar_cost":{"$ref":"#/components/schemas/ModelCost"},"supports_x402":{"type":"boolean"},"supports_webhook":{"type":"boolean"}},"required":["id","name","provider","provider_slug","slug","type","description","capabilities","cost","dollar_cost","supports_x402","supports_webhook"]},"ModelsResponse":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/Model"}},"total":{"type":"integer"}},"required":["models","total"]},"AgentRegisterRequest":{"type":"object","properties":{"agent_name":{"type":"string","minLength":3,"maxLength":50},"webhook_url":{"type":"string","format":"uri"},"source":{"type":"string","maxLength":100},"agent_platform":{"oneOf":[{"type":"string","enum":["openclaw","generic"]},{"type":"string","maxLength":100}]},"agent_version":{"type":"string","maxLength":50}},"required":["agent_name"]},"AgentRegisterResponse":{"type":"object","properties":{"agent_id":{"type":"string"},"api_key":{"type":"string"},"deposit_addresses":{"type":"object","additionalProperties":{"type":"string"}},"asset":{"type":"string","example":"USDC"},"balance":{"type":"string"},"starting_balance":{"type":"string"},"trial_credit_applied":{"type":"boolean"},"webhook_url":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"webhook_secret":{"oneOf":[{"type":"string"},{"type":"null"}]},"activation_tips":{"type":"array","items":{"type":"string"}},"next_steps":{"type":"array","items":{"type":"string"}}},"required":["agent_id","api_key","deposit_addresses","asset","balance","starting_balance","trial_credit_applied","activation_tips","next_steps"]},"AgentDepositRequest":{"type":"object","properties":{"chain":{"type":"string","enum":["base","polygon","ethereum"]},"tx_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["chain","tx_hash"]},"AgentDepositResponse":{"type":"object","properties":{"success":{"type":"boolean"},"amount_credited":{"type":"string"},"new_balance":{"type":"string"},"tx_hash":{"type":"string"},"chain":{"type":"string"},"message":{"type":"string"}},"required":["success","amount_credited","new_balance"]},"AgentBalanceResponse":{"type":"object","properties":{"agent_id":{"type":"string"},"agent_name":{"type":"string"},"balance":{"type":"string"},"status":{"type":"string"},"deposit_addresses":{"type":"object","additionalProperties":{"type":"string"}},"asset":{"type":"string"},"usage":{"type":"object","properties":{"total_requests":{"type":"integer"},"total_usd_spent":{"type":"string"}},"required":["total_requests","total_usd_spent"]},"webhook_url":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"recent_deposits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"chain":{"type":"string"},"amount_usd":{"type":"string"},"tx_hash":{"type":"string"},"status":{"type":"string"},"created_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}},"required":["agent_id","agent_name","balance","status","deposit_addresses","asset","usage"]},"AgentQuoteRequest":{"type":"object","properties":{"type":{"type":"string","enum":["text-to-image","image-to-image","text-to-video","image-to-video","video-to-video","reference-to-video","subject-to-video","upscale","face-swap","lip-sync","text-to-music","text-to-audio","audio-to-audio","speech-to-text","text-to-3d","image-to-3d","text-to-text"]},"model":{"type":"string","enum":["gpt-image-1-mini-i2i"]},"resolution":{"type":"string"},"duration":{"type":"number"},"num_outputs":{"type":"integer","minimum":1},"sound":{"type":"boolean"},"generate_type":{"type":"string","enum":["Normal","LowPoly","Geometry"]}},"required":["type","model"]},"AgentQuoteResponse":{"type":"object","properties":{"cost_usd":{"type":"string"},"your_balance":{"type":"string"},"can_afford":{"type":"boolean"},"shortfall":{"oneOf":[{"type":"string"},{"type":"null"}]},"breakdown":{"type":"object","additionalProperties":true},"deposit_addresses":{"type":"object","additionalProperties":{"type":"string"}},"asset":{"type":"string"}},"required":["cost_usd","your_balance","can_afford","breakdown","deposit_addresses","asset"]},"AgentWebhookRequest":{"type":"object","properties":{"webhook_url":{"type":"string","format":"uri"}},"required":["webhook_url"]},"AgentWebhookResponse":{"type":"object","properties":{"success":{"type":"boolean"},"webhook_url":{"type":"string","format":"uri"},"webhook_secret":{"type":"string"},"message":{"type":"string"},"signature_header":{"type":"string"},"signature_algorithm":{"type":"string"}},"required":["success","webhook_url","webhook_secret"]},"GenerationRequest":{"type":"object","properties":{"type":{"type":"string","enum":["text-to-image","image-to-image","text-to-video","image-to-video","video-to-video","reference-to-video","subject-to-video","upscale","face-swap","lip-sync","text-to-music","text-to-audio","audio-to-audio","speech-to-text","text-to-3d","image-to-3d","text-to-text"]},"model":{"type":"string","enum":["gpt-image-1-mini-i2i"]},"prompt":{"type":"string"},"system_prompt":{"type":"string"},"messages":{"type":"array","description":"Optional OpenAI-style message array for text-to-text. If prompt is omitted, messages are converted into prompt/system_prompt server-side.","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"max_tokens":{"type":"integer","minimum":1},"temperature":{"type":"number"},"top_p":{"type":"number"},"top_k":{"type":"number"},"presence_penalty":{"type":"number"},"frequency_penalty":{"type":"number"},"repetition_penalty":{"type":"number"},"enable_thinking":{"type":"boolean"},"negative_prompt":{"type":"string"},"image_url":{"type":"string","format":"uri"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"video_url":{"type":"string","format":"uri"},"videos":{"type":"array","items":{"type":"string","format":"uri"}},"audio_url":{"type":"string","format":"uri"},"aspect_ratio":{"type":"string"},"resolution":{"type":"string"},"duration":{"type":"integer","minimum":1},"num_outputs":{"type":"integer","minimum":1},"seed":{"type":"integer"},"webhook_url":{"type":"string","format":"uri"}},"required":["type","model"]},"GenerationQueuedResponse":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"model":{"type":"string"},"status":{"type":"string","enum":["queued"]},"cost":{"type":"number"},"cost_formatted":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"poll_url":{"type":"string"}},"required":["id","type","model","status","cost","created_at","poll_url"]},"GenerationStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"model":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"prompt":{"type":"string"},"output":{"type":"string","format":"uri"},"outputs":{"type":"array","items":{"type":"string","format":"uri"}},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"aspect_ratio":{"type":"string"},"duration":{"type":"integer"},"resolution":{"type":"string"},"num_outputs":{"type":"integer"},"cost":{"type":"number"}},"required":["id","model","status"]}}}}