Scenario provides powerful search APIs for finding both assets and models in your projects. The search supports text queries, semantic similarity search using AI embeddings, image-based search, advanced filtering, and hybrid search modes that combine multiple search methods.

Endpoints:

• Assets: POST /v1/search/assets
• Models: POST /v1/search/models

This documentation covers Asset Search first, followed by Model Search. Both endpoints share similar search methods and syntax.

Asset Search

Quick Start

Basic Text Search

Search for assets by name, description, or prompt:

POST /v1/search/assets
{
  "query": "fantasy castle"
}

Image Similarity Search

Find assets similar to a reference image:

{
  "image": "data:image/png;base64,iVBORw0KGgo..."
}

Filter by Attributes

Find assets matching specific criteria:

{
  "filter": "width >= 1024 AND tags = landscape"
}

Search Methods

1. Text Search

Search assets by text content in names, prompts, descriptions, and tags.

Parameters:

• query (string): Text to search for

Example:

{
  "query": "cat wearing hat"
}

Matches:

• Asset names containing the text
• Generation prompts
• Asset descriptions and captions
• Tags
• Seeds (for reproducibility)

Features:

• Typo tolerance: Handles minor spelling mistakes
• Prefix search: "chris" matches "christmas"
• Word splitting: Finds partial matches

2. Semantic Search

Use AI embeddings to find semantically similar content, even when exact words don't match.

Parameters:

• query (string): Text describing what you're looking for
• querySemanticRatio (number, 0-1, default: 0): Weight of semantic vs. keyword search

Example:

{
  "query": "a man in red outfit for Christmas",
  "querySemanticRatio": 0.75
}

When to use:

• Finding conceptually similar images
• Discovering related content
• Overcoming vocabulary differences

Ratio guide:

• 0.0: Pure keyword search (exact matches)
• 0.5: Balanced hybrid search
• 1.0: Pure semantic search (meaning-based)

3. Image Similarity Search

Find assets visually similar to a reference image.

Parameters:

• image (string): Asset ID or data URL of reference image
• imageSemanticRatio (number, 0-1, default: 1): Weight of visual similarity

Single Image:

{
  "image": "asset_abc123xyz",
  "imageSemanticRatio": 1.0
}

Multiple Images (like/unlike):

{
  "images": {
    "like": ["asset_abc123", "asset_def456"],
    "unlike": ["asset_xyz789"]
  }
}

Use cases:

• Find variations of an image
• Discover similar styles
• Exclude unwanted styles with unlike

Supported formats:

• Asset ID: "asset_abc123xyz"
• Data URL: "data:image/png;base64,..."

4. Combined Hybrid Search

Combine text, semantic, and image search for precise results.

{
  "query": "medieval architecture",
  "querySemanticRatio": 0.5,
  "image": "asset_reference123",
  "imageSemanticRatio": 0.8,
  "filter": "width >= 1024"
}

Filtering

Use filters to narrow results by specific attributes.

Filter Syntax

Basic operators:

• = - Equals
• != - Not equals
• > - Greater than
• >= - Greater than or equal
• < - Less than
• <= - Less than or equal
• IS EMPTY - Field is empty/null
• IS NOT EMPTY - Field has a value

Logical operators:

• AND - Both conditions must be true
• OR - Either condition must be true
• NOT - Negates condition

Grouping:

• Use parentheses for complex logic: (A OR B) AND C

Filterable Fields

Asset Metadata:

Generation Parameters:

Organization:

Timestamps:

User/Project:

Filter Examples

Find large landscape images:

{
  "filter": "width >= 1920 AND height >= 1080 AND tags = landscape"
}

Find safe-for-work assets:

{
  "filter": "nsfw IS EMPTY"
}

Find assets from specific model:

{
  "filter": "modelId = model_abc123 AND kind = image"
}

Find recent high-quality generations:

{
  "filter": "createdAt >= \"2024-01-01\" AND numInferenceSteps >= 50 AND guidance >= 7"
}

Find assets with specific tags:

{
  "filter": "tags = fantasy AND tags = character"
}

Exclude assets with tags:

{
  "filter": "tags = landscape AND NOT tags = nsfw"
}

Complex filter with grouping:

{
  "filter": "(tags = dragon OR prompt:dragon) AND width >= 1024 AND nsfw IS EMPTY"
}

Pagination

Two pagination modes are available:

Offset-based Pagination

Use offset and limit for traditional pagination.

Parameters:

• offset (number, default: 0, min: 0): Number of results to skip
• limit (number, default: 20, min: 1, max: 100): Maximum results per request

Example:

{
  "query": "castle",
  "offset": 0,
  "limit": 20
}

Next page:

{
  "query": "castle",
  "offset": 20,
  "limit": 20
}

Response:

{
  "hits": [...],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 156
}

Page-based Pagination

Use page and hitsPerPage for page-based pagination.

Parameters:

• page (number, min: 1): Page number to retrieve
• hitsPerPage (number, min: 1, max: 100): Results per page

Example:

{
  "query": "castle",
  "page": 1,
  "hitsPerPage": 20
}

Response:

{
  "hits": [...],
  "page": 1,
  "hitsPerPage": 20,
  "totalPages": 8,
  "totalHits": 156
}

Sorting

Sort results by specific attributes.

Parameter:

• sortBy (string[]): Array of attribute:order pairs

Format: ["field:asc"] or ["field:desc"]

Sortable fields:

• createdAt - Creation date
• updatedAt - Last modified date
• width - Image width
• height - Image height
• score - Asset popularity score

Examples:

Sort by newest first:

{
  "sortBy": ["createdAt:desc"]
}

Sort by dimensions:

{
  "sortBy": ["width:desc", "height:desc"]
}

Sort by popularity:

{
  "sortBy": ["score:desc", "createdAt:desc"]
}

Note: When using text or semantic search without explicit sorting, results are automatically ranked by relevance.

Public Search

Search across publicly shared assets from all users.

Parameter:

• public (boolean, default: false): Search public assets instead of your own

Example:

{
  "query": "fantasy landscape",
  "public": true,
  "limit": 50
}

Use cases:

• Discover community creations
• Find inspiration
• Browse trending content

Note: Public search only returns assets explicitly marked as public by their creators.

Response Format

{
  "hits": [
    {
      "id": "asset_abc123xyz",
      "url": "https://cdn.cloud.scenario.com/assets/...",
      "ownerId": "project_def456",
      "authorId": "user_ghi789",
      "privacy": "private",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "mimeType": "image/png",
      "description": "A majestic fantasy castle on a hill",
      "metadata": {
        "name": "Fantasy Castle",
        "kind": "image",
        "type": "inference-txt2img",
        "width": 1024,
        "height": 1024,
        "prompt": "fantasy castle on a hill, dramatic lighting",
        "seed": "1234567890",
        "modelId": "model_xyz789",
        "numInferenceSteps": 50,
        "guidance": 7.5
      },
      "tags": ["fantasy", "castle", "landscape"],
      "collectionIds": ["col_abc123"],
      "nsfw": [],
      "thumbnail": {
        "assetId": "asset_thumb123",
        "url": "https://cdn.cloud.scenario.com/thumbnails/..."
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 156
}

Response Fields

Asset Information:

• id - Asset unique identifier
• url - Signed CDN URL to access the asset
• thumbnail - Preview image for videos/3D models (optional)

Ownership:

• ownerId - Project that owns the asset
• authorId - User who created the asset
• teamId - Team that owns the project

Metadata:

• metadata.kind - Asset type (image, video, 3d, audio)
• metadata.type - Specific asset type (inference-txt2img, canvas, upload, etc.)
• metadata.name - User-assigned name
• metadata.width/height - Dimensions in pixels
• metadata.prompt - Generation prompt used
• metadata.seed - Reproducibility seed
• metadata.modelId - Model used for generation
• metadata.numInferenceSteps - Number of steps
• metadata.guidance - Guidance scale value
• metadata.scheduler - Scheduler algorithm

Organization:

• tags - User-assigned tags
• collectionIds - Collections containing this asset
• nsfw - NSFW classification labels
• description - Caption or user description

Timestamps:

• createdAt - When asset was created (ISO 8601)
• updatedAt - When asset was last modified (ISO 8601)

Pagination:

• offset - Number of results skipped
• limit - Maximum results returned
• estimatedTotalHits - Approximate total matches
• page - Current page (page-based pagination)
• hitsPerPage - Results per page (page-based pagination)
• totalPages - Total pages (page-based pagination)
• totalHits - Exact total matches (page-based pagination)

Complete Examples

Example 1: Find Similar Fantasy Landscapes

{
  "query": "fantasy landscape",
  "querySemanticRatio": 0.7,
  "filter": "width >= 1024 AND nsfw IS EMPTY AND tags = landscape",
  "sortBy": ["score:desc"],
  "limit": 30
}

Example 2: Find Variations of an Image

{
  "images": {
    "like": ["asset_reference123"]
  },
  "imageSemanticRatio": 0.9,
  "filter": "kind = image",
  "limit": 20
}

Example 3: Browse Recent High-Quality Generations

{
  "filter": "numInferenceSteps >= 50 AND guidance >= 7 AND createdAt >= \"2024-01-01\"",
  "sortBy": ["createdAt:desc"],
  "limit": 50
}

Example 4: Search Public Gallery

{
  "public": true,
  "query": "character design",
  "querySemanticRatio": 0.5,
  "filter": "nsfw IS EMPTY AND width >= 512",
  "sortBy": ["score:desc"],
  "page": 1,
  "hitsPerPage": 24
}

Example 5: Find Assets by Multiple Tags

{
  "filter": "tags = character AND tags = fantasy AND tags = warrior",
  "sortBy": ["createdAt:desc"],
  "limit": 40
}

Best Practices

Performance

1. Use filters to narrow results before applying semantic search
2. Limit results appropriately - don't request more than you need
3. Cache results when possible to reduce API calls
4. Use offset pagination for deep pagination (better performance)

Search Quality

1. Combine search methods for best results:

   • Use filter to narrow by concrete attributes
   • Use query for text matching
   • Use semantic search for conceptual matches
   • Use image search for visual similarity

2. Start with filters for specific requirements:

   JSON

   {
     "filter": "width >= 1024 AND nsfw IS EMPTY",
     "query": "dragon",
     "querySemanticRatio": 0.5
   }

3. Use appropriate semantic ratios:

   • High ratio (0.8-1.0): Conceptual search, finding related content
   • Medium ratio (0.4-0.7): Balanced search with keyword preference
   • Low ratio (0.0-0.3): Exact matching with slight semantic boost

Organization

1. Tag your assets consistently for better filtering
2. Use descriptive names to improve text search
3. Organize into collections for easy filtering by collectionIds
4. Add to collections for categorical searches

Rate Limits

Asset search requests count against your account's search quota. The quota depends on your subscription plan.

Quota exceeded response:

{
  "error": "Quota exceeded for search",
  "code": "QUOTA_EXCEEDED"
}

Common Errors

Missing Search Parameters

Error: Must provide at least one search parameter

Cause: Request has no query, filter, image, or images

Solution: Include at least one search parameter

Invalid Filter Syntax

Error: Invalid filter syntax

Cause: Filter contains syntax errors or invalid fields

Solution: Check filter syntax and field names

Invalid Field

Error: "fieldName" is not a filterable field

Cause: Attempting to filter by non-filterable field

Solution: Use only fields from the filterable fields list

Pagination Limits

Error: Limit exceeds maximum (100)

Cause: limit or hitsPerPage set above 100

Solution: Use maximum of 100 results per request

Migration Notes

From Legacy Search

If you're migrating from an older search API:

1. Endpoint changed: Use POST /v1/search/assets instead of previous endpoints
2. Semantic search is opt-in: Set querySemanticRatio > 0 to enable
3. Filter syntax: Use standard operators (=, >=, etc.) instead of custom syntax
4. Image search: Use image or images parameter with asset IDs or data URLs
5. Response format: Assets include full metadata and signed URLs

Model Search

Overview

Search for AI models in your projects using the model search API. Model search supports text queries, semantic image-based search, filtering by capabilities and metadata, and discovering public community models.

Endpoint: POST /v1/search/models

Quick Start

Basic Text Search

Search for models by name or description:

POST /v1/search/models
{
  "query": "character"
}

Image-Based Model Discovery

Find models by providing an example image:

{
  "image": "asset_abc123xyz"
}

Filter by Capabilities

Find models with specific capabilities:

{
  "filter": "capabilities = img2img AND type = flux.1-lora"
}

Search Methods

Model search supports the same search methods as asset search:

1. Text Search - Search by model name, description, tags, and capabilities
2. Semantic Search - Use querySemanticRatio for meaning-based search
3. Image Similarity - Find models using reference images (searches against model example images)
4. Hybrid Search - Combine multiple search methods

See the Asset Search Methods section for detailed documentation on each method.

Model-Specific Filters

Filterable Fields

Model Metadata:

Capabilities & Features:

Training Data:

Compliance:

Organization:

Timestamps:

Common Model Capabilities

Models can have the following capabilities:

Image Generation:

• txt2img - Text to image generation
• img2img - Image to image transformation

Video Generation:

• txt2video - Text to video generation
• img2video - Image to video generation
• video2video - Video to video transformation
• video2img - Video to image extraction

3D Generation:

• txt23d - Text to 3D model generation
• img23d - Image to 3D model generation
• 3d23d - 3D to 3D transformation

Audio Generation:

• txt2audio - Text to audio generation (music, speech, sound effects)
• audio2audio - Audio to audio transformation

Other:

• txt2txt - Text to text (language models, analysis)
• img2txt - Image to text (captioning, analysis)

Filter Examples

Find Flux models for image generation:

{
  "filter": "type = \"flux.1-lora\" AND capabilities = txt2img"
}

Find trained models with sufficient training data:

{
  "filter": "source = training AND trainingImagesNumber >= 20"
}

Find models by provider:

{
  "filter": "complianceMetadata.modelProvider = Scenario"
}

Find models with specific capabilities:

{
  "filter": "capabilities = txt2img AND capabilities = img2img"
}

Find public models with tags:

{
  "public": true,
  "filter": "tags = character AND tags = fantasy"
}

Response Format

{
  "hits": [
    {
      "id": "model_abc123xyz",
      "name": "Fantasy Character Generator",
      "shortDescription": "Generate detailed fantasy characters",
      "type": "flux.1",
      "source": "training",
      "ownerId": "project_def456",
      "authorId": "user_ghi789",
      "privacy": "private",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "capabilities": ["txt2img", "img2img"],
      "tags": ["character", "fantasy"],
      "collectionIds": ["col_abc123"],
      "trainingImagesNumber": 25,
      "exampleAssetIds": ["asset_example1", "asset_example2"],
      "concepts": [
        { "modelId": "model_concept1" }
      ],
      "complianceMetadata": {
        "subProcessor": "Modal",
        "modelProvider": "Scenario",
        "maintainer": "Scenario"
      },
      "thumbnail": {
        "assetId": "asset_thumb123",
        "url": "https://cdn.cloud.scenario.com/thumbnails/..."
      },
      "score": 95.5
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 42
}

Response Fields

Model Information:

• id - Model unique identifier
• name - Model display name
• shortDescription - Brief description
• type - Model type (e.g., "flux.1", "sd-1_5")
• source - Origin (e.g., "training", "import")
• parentModelId - Parent model if derived

Capabilities:

• capabilities - Array of model capabilities
• trainingImagesNumber - Number of training images used
• exampleAssetIds - Array of example asset IDs
• concepts - Array of linked concept models

Organization:

• tags - User-assigned tags
• collectionIds - Collections containing this model
• privacy - Privacy setting

Compliance:

• complianceMetadata - Compliance and licensing information
  • subProcessor - Infrastructure provider
  • modelProvider - Model provider/creator
  • maintainer - Who maintains the model
  • licenseTerms - License URL
  • dataProcessingComment - Data retention policy

Metadata:

• thumbnail - Preview image (if available)
• score - Popularity/usage score
• ownerId - Project that owns the model
• authorId - User who created the model
• createdAt / updatedAt - Timestamps

Public Model Search

Discover models shared by the community:

{
  "public": true,
  "query": "fantasy",
  "filter": "capabilities = txt2img",
  "limit": 50
}

Public search features:

• Browse community-created models
• Find pre-trained models
• Discover popular styles and concepts

Complete Examples

Example 1: Find Custom Trained Models

{
  "filter": "source = training AND trainingImagesNumber >= 15",
  "sortBy": ["createdAt:desc"],
  "limit": 20
}

Example 2: Discover Image-to-Image Models

{
  "filter": "capabilities = img2img",
  "sortBy": ["score:desc"],
  "limit": 30
}

Example 3: Find Models Similar to Reference Image

{
  "image": "asset_reference123",
  "imageSemanticRatio": 0.9,
  "filter": "capabilities = txt2img",
  "limit": 10
}

Example 4: Search Public Flux Models

{
  "public": true,
  "query": "character design",
  "filter": "type = \"flux.1-lora\" AND capabilities = txt2img",
  "sortBy": ["score:desc"],
  "page": 1,
  "hitsPerPage": 24
}

Pagination, Sorting & Public Search

Model search uses the same pagination, sorting, and public search features as asset search. See the corresponding sections in Asset Search for details.

Rate Limits & Errors

Model search shares the same rate limits and error handling as asset search. See Rate Limits and Common Errors sections for details.