Model Search API

Search and discover AI models available in the Runware platform. Filter and find the right model for your generation tasks.

Introduction

The Model Search API enables discovery of available models on the Runware platform, providing search and filtering capabilities across public models from the community and private models within your organization.

Models discovered through this API can be used immediately in generation tasks by referencing their AIR identifiers. This enables dynamic model selection in applications and helps discover new models for specific use cases.

The search works across model names, versions, tags, and other metadata. Multiple filters can be combined to narrow results by category, type, architecture, and visibility. Results are returned in a paginated format with a default of 20 models per page, controlled by the limit and offset parameters.

Request

The Runware API always accepts an array of objects as input, where each object represents a specific task to be performed. The structure of the object varies depending on the type of the task. For this section, we will focus on the parameters related to the model search task.

The following JSON snippet shows the basic structure of a request object.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const result = await client.modelSearch({
  search: 'realistic',
  tags: 'photorealistic',
  category: 'checkpoint',
  type: 'base',
  architecture: 'sdxl',
  visibility: 'all',
  offset: 0,
  limit: 20
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        result = await client.model_search({
            "search": "realistic",
            "tags": "photorealistic",
            "category": "checkpoint",
            "type": "base",
            "architecture": "sdxl",
            "visibility": "all",
            "offset": 0,
            "limit": 20
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "modelSearch",
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "search": "realistic",
      "tags": "photorealistic",
      "category": "checkpoint",
      "type": "base",
      "architecture": "sdxl",
      "visibility": "all",
      "offset": 0,
      "limit": 20
    }
  ]'

runware model search \
  -q realistic \
  --tags photorealistic \
  --category checkpoint \
  --type base \
  --architecture sdxl \
  --visibility all \
  --offset 0 \
  --limit 20

{
  "taskType": "modelSearch",
  "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
  "search": "realistic",
  "tags": "photorealistic",
  "category": "checkpoint",
  "type": "base",
  "architecture": "sdxl",
  "visibility": "all",
  "offset": 0,
  "limit": 20
}

taskType stringrequiredvalue: modelSearch: Identifier for the type of task being performed

taskUUID stringrequiredUUID v4: UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.

search stringrequired: Search query to find models by name, description or AIR ID.

source string: Filter by model source.
Allowed values2 values

category string: Filter models by category.
Allowed values5 values

architecture string: Filter by model architecture.

capabilities array of strings: Filter by model capabilities.

visibility string: Filter by visibility status.
Allowed values4 values

limit integermin: 1max: 100default: 20: Maximum number of results to return.

offset integermin: 0default: 0: Number of results to skip for pagination.

sort stringdefault: popularity: 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).
Allowed values8 values

Response

Results will be delivered in the format below.

{
  "data": [
    {
      "results": [
        {
          "name": "Promissing_Realistic_XL",
          "air": "civitai:305149@392545",
          "tags": [
            "photorealistic",
            "base model",
            "sci-fi",
            "photo",
            "woman",
            "fantasy",
            "photorealism",
            "rpg",
            "general use",
            "close up",
            "close up shot",
            "promissing_realistic_xl"
          ],
          "heroImage": "https://mim.runware.ai/r/66a70a0bb7c38-450x450.jpg",
          "category": "checkpoint",
          "private": false,
          "comment": "",
          "version": "v22",
          "architecture": "sdxl",
          "type": "base",
          "defaultWidth": 1024,
          "defaultHeight": 1024,
          "defaultSteps": 20,
          "defaultScheduler": "Default",
          "defaultCFG": 7.5
        }
      ],
      "taskUUID": "50836053-a0ee-4cf5-b9d6-ae7c5d140ada",
      "taskType": "modelSearch",
      "totalResults": 2
    }
  ]
}

taskType stringrequiredvalue: modelSearch: Identifier for the type of task this response belongs to.

taskUUID stringrequiredUUID v4: UUID v4 identifier echoed from the original request, used to match async responses to their tasks.

totalResults integerrequiredmin: 0: Total number of models matching the search criteria.

results array of objectsrequired

List of models found.

Properties13 properties

results » air air stringrequired: Artificial Intelligence Resource identifier.

results » name name stringrequired: Model name.

results » category category stringrequired: Model category.
Possible values5 values

results » architecture architecture string | nullrequired: Model architecture.

results » capabilities capabilities array of stringsrequired: Model capabilities.

results » source source stringrequired: Model source.
Possible values2 values

results » heroImage heroImage string | nullrequireduri: Representative image URL.

results » private private booleanrequired: Whether the model is private.

results » isFavorite isFavorite boolean: Whether the model is favorited.

results » provider provider string: Model provider.

results » shortDescription shortDescription string: Short description.

results » positiveTriggerWords positiveTriggerWords string: Positive trigger words.

results » negativeTriggerWords negativeTriggerWords string: Negative trigger words.