Search

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:

Field	Type	Description	Example
kind	string	Asset type	kind = image
width	number	Width in pixels	width >= 1024
height	number	Height in pixels	height <= 2048
size	number	File size in bytes	size < 1000000
aspectRatio	string	Aspect ratio	aspectRatio = "16:9"
mimeType	string	MIME type	mimeType = "image/png"
name	string	Asset name	name = "my-asset"

Generation Parameters:

Field	Type	Description	Example
prompt	string	Generation prompt	prompt:dragon
text	string	Text content (TTS)	text:hello
negativePrompt	string	Negative prompt	negativePrompt:blurry
seed	string	Random seed	seed = "1234567890"
modelId	string	Model ID used	modelId = "model_abc123"
baseModelId	string	Base model ID	baseModelId = "stable-diffusion-xl"
modelType	string	Model type	modelType = "flux.1"
numInferenceSteps	number	Inference steps	numInferenceSteps >= 50
guidance	number	Guidance scale	guidance = 7.5
scheduler	string	Scheduler used	scheduler = "euler"

Organization:

Field	Type	Description	Example
tags	string[]	Asset tags	tags = landscape
collectionIds	string[]	Collection IDs	collectionIds = col_abc123
nsfw	string[]	NSFW labels	nsfw IS EMPTY
privacy	string	Privacy setting	privacy = public

Timestamps:

Field	Type	Description	Example
createdAt	date	Creation date	createdAt >= "2024-01-01"
updatedAt	date	Last modified	updatedAt < "2024-12-31"

User/Project:

Field	Type	Description	Example
authorId	string	Creator user ID	authorId = user_abc123
ownerId	string	Project ID	Auto-filtered by API

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"]
}

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

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:

   {
     "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:

Field	Type	Description	Example
name	string	Model name	name:character
type	string	Model type	type = "flux.1-lora"
source	string	Model origin	source = training
parentModelId	string	Parent model ID	parentModelId = model_abc123

Capabilities & Features:

Field	Type	Description	Example
capabilities	string[]	Model capabilities	capabilities = img2img
tags	string[]	User-assigned tags	tags = character
collectionIds	string[]	Collection IDs	collectionIds = col_abc123
concepts	string[]	Linked concept models	concepts = model_xyz789

Training Data:

Field	Type	Description	Example
trainingImagesNumber	number	Number of training images	trainingImagesNumber >= 10
exampleAssetIds	string[]	Example asset IDs	exampleAssetIds = asset_abc123

Compliance:

Field	Type	Description	Example
complianceMetadata.subProcessor	string	Sub-processor	complianceMetadata.subProcessor = Modal
complianceMetadata.modelProvider	string	Model provider	complianceMetadata.modelProvider = Scenario
complianceMetadata.maintainer	string	Model maintainer	complianceMetadata.maintainer = Scenario

Organization:

Field	Type	Description	Example
privacy	string	Privacy setting	privacy = public
ownerId	string	Project ID	Auto-filtered by API
authorId	string	Creator user ID	authorId = user_abc123

Timestamps:

Field	Type	Description	Example
createdAt	date	Creation date	createdAt >= "2024-01-01"
updatedAt	date	Last modified	updatedAt < "2024-12-31"

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.