GET and Filter Models

One of the most common API tasks is retrieving the right model for your generation. The GET /models endpoint offers flexible filtering to help you distinguish between your private models, official Scenario models, and third-party community models.

Endpoint: GET https://api.cloud.scenario.com/v1/models

Filtering by Privacy

Private Models: By default, calling GET /models with your credentials returns only your private models (models you have trained).

Public Models: To access public models, you can use the GET /models/public endpoint or specific tag filters.

Filtering by Tags (Scenario vs. Third-Party)

You can use the tags query parameter to find specific categories of models. This is essential for building UIs that separate "Official" models from "Community" ones.

Tag	Description
`sc:scenario`	Official Scenario Models. High-quality base models and styles curated by the Scenario team.
`sc:third-party`	Third-Party Models. Public models created by partners or the community.

To retrieve Public Models (including Scenario's official models and community public models), you typically use the dedicated public path or a privacy filter depending on your specific integration level.

Endpoint: GET https://api.cloud.scenario.com/v1/models/public

cURL Examples

Get Official Scenario Models:

curl -X GET "https://api.cloud.scenario.com/v1/models/public?tags=sc:scenario" \
  -H "Authorization: Basic <YOUR_BASE64_CREDENTIALS>

Get Third-Party Models:

curl -X GET "https://api.cloud.scenario.com/v1/models?tags=sc:third-party" \
  -H "Authorization: Basic <YOUR_BASE64_CREDENTIALS>"

Integration Code Examples

Below are practical scripts in Python and JavaScript to authenticate and fetch models based on the tags discussed above.

Python Example - `requests`

import requests
import base64

# CONFIGURATION
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
BASE_URL = "https://api.cloud.scenario.com/v1/models"

def get_models(tag=None):
    # 1. Encode Credentials
    credentials = f"{API_KEY}:{API_SECRET}"
    encoded_creds = base64.b64encode(credentials.encode()).decode()
    
    headers = {
        "Authorization": f"Basic {encoded_creds}",
        "Accept": "application/json"
    }

    # 2. Set Parameters
    params = {"limit": 10, "offset": 0}
    if tag:
        params["tags"] = tag

    # 3. Fetch Data
    try:
        response = requests.get(BASE_URL, headers=headers, params=params)
        response.raise_for_status()
        models = response.json().get("models", [])
        
        print(f"--- Found {len(models)} models for tag: {tag} ---")
        for m in models:
            print(f"- {m['name']} (ID: {m['id']})")
            
    except Exception as e:
        print(f"Error: {e}")

# Usage
get_models(tag="sc:scenario")    # Fetch Official Models
get_models(tag="sc:third-party") # Fetch Community Models

JavaScript Example - Node.js / `fetch`

const API_KEY = "YOUR_API_KEY";
const API_SECRET = "YOUR_API_SECRET";
const BASE_URL = "https://api.cloud.scenario.com/v1/models";

async function getModels(tag = null) {
    // 1. Encode Credentials
    const creds = Buffer.from(`${API_KEY}:${API_SECRET}`).toString('base64');
    
    const headers = {
        "Authorization": `Basic ${creds}`,
        "Accept": "application/json"
    };

    // 2. Build URL with Params
    const url = new URL(BASE_URL);
    url.searchParams.append("limit", "10");
    if (tag) url.searchParams.append("tags", tag);

    // 3. Fetch Data
    try {
        const response = await fetch(url, { headers });
        if (!response.ok) throw new Error(`Status: ${response.status}`);
        
        const data = await response.json();
        console.log(`--- Found ${data.models.length} models for tag: ${tag} ---`);
        
        data.models.forEach(m => console.log(`- ${m.name} (${m.id})`));
        
    } catch (error) {
        console.error("Error:", error);
    }
}

// Usage
getModels("sc:scenario");    // Fetch Official Models
getModels("sc:third-party"); // Fetch Community Models

👉 Download OpenAPI spec