{ "openapi": "3.1.0", "info": { "title": "Runware API - Model Search", "version": "1.0.0", "description": "Search for models." }, "servers": [ { "url": "https://api.runware.ai/v1", "description": "Runware REST API" } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Runware API Key (e.g., Bearer )" } }, "schemas": { "AuthenticationTask": { "title": "Authentication", "description": "Authenticates a connection using an API key. Can be sent as the first element of the request array as an alternative to using the Authorization header.", "type": "object", "x-response-schema": "https://schemas.runware.ai/responses/utilities/authentication.json", "properties": { "taskType": { "$id": "https://schemas.runware.ai/requests/parameters/api/task-type.json", "title": "Task Type", "description": "Identifier for the type of task being performed.", "type": "string", "const": "authentication" }, "apiKey": { "$id": "https://schemas.runware.ai/requests/parameters/authentication/api-key.json", "title": "API Key", "description": "Your Runware API key.", "type": "string" }, "connectionSessionUUID": { "$id": "https://schemas.runware.ai/requests/parameters/authentication/connection-session-uuid.json", "title": "Connection Session UUID", "description": "Optional session UUID to resume a previous connection and receive any buffered results.", "type": "string", "format": "uuid" } }, "required": [ "taskType", "apiKey" ], "additionalProperties": false }, "RequestBody": { "type": "array", "items": { "title": "Model Search", "description": "Search for models.", "type": "object", "properties": { "taskType": { "title": "Task Type", "description": "Identifier for the type of task being performed.", "type": "string", "const": "modelSearch" }, "taskUUID": { "title": "Task UUID", "description": "UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.", "type": "string", "format": "uuid" }, "search": { "title": "Search", "description": "Search query to find models by name, description or AIR ID.", "type": "string" }, "source": { "title": "Source", "description": "Filter by model source.", "type": "string", "enum": [ "featured", "community" ] }, "category": { "title": "Category", "description": "Filter models by category.", "type": "string", "enum": [ "checkpoint", "lora", "lycoris", "vae", "embeddings" ] }, "architecture": { "title": "Architecture", "description": "Filter by model architecture.", "type": "string" }, "capabilities": { "title": "Capabilities", "description": "Filter by model capabilities.", "type": "array", "items": { "type": "string" } }, "visibility": { "title": "Visibility", "description": "Filter by visibility status.", "type": "string", "enum": [ "public", "private", "favorite", "owned" ] }, "limit": { "title": "Limit", "description": "Maximum number of results to return.", "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "offset": { "title": "Offset", "description": "Number of results to skip for pagination.", "type": "integer", "minimum": 0, "default": 0 }, "sort": { "title": "Sort", "description": "Sort order for results. A bare field name sorts ascending and a `-` prefix sorts descending, except `popularity`, whose bare value is already descending (most popular first).", "type": "string", "enum": [ "popularity", "-popularity", "name", "-name", "addedUnixTimestamp", "-addedUnixTimestamp", "updatedDateUnixTimestamp", "-updatedDateUnixTimestamp" ], "default": "popularity" } }, "required": [ "taskType", "taskUUID", "search" ], "allOf": [ { "if": { "properties": { "category": { "const": "checkpoint" } }, "required": [ "category" ] }, "then": { "properties": { "architecture": { "enum": [ "exactlyai_image", "flux1d", "flux1s", "fluxkontextdev", "illustrious", "noobai", "pony", "sd1x", "sdxl", "sdxllightning", "sdxlturbo", "z_image", "z_image_turbo" ] } } } }, { "if": { "properties": { "category": { "const": "lora" } }, "required": [ "category" ] }, "then": { "properties": { "architecture": { "enum": [ "flux1d", "flux1s", "flux2klein_4b", "flux2klein_9b", "flux2klein_base_4b", "flux2klein_base_9b", "flux_2_dev", "fluxkontextdev", "hidreamdev", "hidreamfast", "hidreamfull", "illustrious", "ltx_2_3_video", "noobai", "pony", "qwen_image", "qwen_image_edit", "qwen_image_edit_plus", "qwen_image_layered", "sd1x", "sd3", "sdxl", "sdxllightning", "sdxlturbo", "z_image", "z_image_turbo" ] } } } }, { "if": { "properties": { "category": { "const": "lycoris" } }, "required": [ "category" ] }, "then": { "properties": { "architecture": { "enum": [ "flux1d", "flux1s", "flux2klein_4b", "flux2klein_9b", "flux2klein_base_4b", "flux2klein_base_9b", "flux_2_dev", "fluxkontextdev", "hidreamdev", "hidreamfast", "hidreamfull", "illustrious", "noobai", "pony", "qwen_image", "qwen_image_edit", "qwen_image_edit_plus", "qwen_image_layered", "sd1x", "sd3", "sdxl", "sdxllightning", "sdxlturbo", "z_image", "z_image_turbo" ] } } } }, { "if": { "properties": { "category": { "const": "vae" } }, "required": [ "category" ] }, "then": { "properties": { "architecture": { "enum": [ "illustrious", "noobai", "pony", "sd1x", "sdxl", "sdxllightning", "sdxlturbo" ] } } } }, { "if": { "properties": { "category": { "const": "embeddings" } }, "required": [ "category" ] }, "then": { "properties": { "architecture": { "enum": [ "illustrious", "noobai", "pony", "sd1x", "sdxl", "sdxllightning", "sdxlturbo" ] } } } } ], "additionalProperties": false }, "description": "You must always POST an array of task objects." }, "ResponseBody": { "type": "object", "properties": { "data": { "type": "array", "items": { "title": "Model Search Response", "type": "object", "properties": { "taskType": { "title": "Task Type", "description": "Identifier for the type of task this response belongs to.", "type": "string", "const": "modelSearch" }, "taskUUID": { "title": "Task UUID", "description": "UUID v4 identifier echoed from the original request, used to match async responses to their tasks.", "type": "string", "format": "uuid" }, "totalResults": { "title": "Total Results", "description": "Total number of models matching the search criteria.", "type": "integer", "minimum": 0 }, "results": { "title": "Results", "description": "List of models found.", "type": "array", "items": { "type": "object", "properties": { "air": { "title": "AIR", "description": "Artificial Intelligence Resource identifier.", "type": "string" }, "name": { "title": "Name", "description": "Model name.", "type": "string" }, "category": { "title": "Category", "description": "Model category.", "type": "string", "enum": [ "checkpoint", "lora", "lycoris", "vae", "embeddings" ] }, "architecture": { "title": "Architecture", "description": "Model architecture.", "type": [ "string", "null" ] }, "capabilities": { "title": "Capabilities", "description": "Model capabilities.", "type": "array", "items": { "type": "string" } }, "source": { "title": "Source", "description": "Model source.", "type": "string", "enum": [ "featured", "community" ] }, "heroImage": { "title": "Hero Image", "description": "Representative image URL.", "type": [ "string", "null" ], "format": "uri" }, "private": { "title": "Private", "description": "Whether the model is private.", "type": "boolean" }, "isFavorite": { "title": "Is Favorite", "description": "Whether the model is favorited.", "type": "boolean" }, "provider": { "title": "Provider", "description": "Model provider.", "type": "string" }, "shortDescription": { "title": "Short Description", "description": "Short description.", "type": "string" }, "positiveTriggerWords": { "title": "Positive Trigger Words", "description": "Positive trigger words.", "type": "string" }, "negativeTriggerWords": { "title": "Negative Trigger Words", "description": "Negative trigger words.", "type": "string" } }, "required": [ "air", "name", "category", "architecture", "capabilities", "source", "heroImage", "private" ], "additionalProperties": true } } }, "required": [ "taskType", "taskUUID", "totalResults", "results" ], "additionalProperties": true } } } }, "ErrorResponse": { "title": "Error Response", "description": "Standard error response returned by the Runware API.", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "A short identifier for the error (e.g., invalidApiKey, timeoutProvider)." }, "message": { "type": "string", "description": "A human-readable explanation of what went wrong." }, "parameter": { "type": "string", "description": "The request parameter related to the error, if applicable." }, "taskType": { "type": "string", "description": "The task type of the request that failed." }, "taskUUID": { "type": "string", "description": "The unique identifier of the failed request." }, "documentation": { "type": "string", "description": "A link to relevant documentation." } } } } }, "required": [ "errors" ], "additionalProperties": false } } }, "paths": { "/": { "post": { "summary": "Run Model Search", "description": "Search for models.", "operationId": "run_model_search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestBody" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseBody" } } } }, "400": { "description": "Bad Request — Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — No valid API key provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment Required — Insufficient account balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — The API key lacks permissions for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests — Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error — Something went wrong on Runware's end.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable — Temporarily unavailable (maintenance or capacity).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }