Base URL: https://modelslab.com/api/agents/v1
Authorization: Bearer <agent_access_token>

import requests

BASE = "https://modelslab.com/api/agents/v1"

def headers(token):
    return {"Authorization": f"Bearer {token}"}

def search_models(token, search=None, feature=None, provider=None,
                  model_type=None, base_model=None, tags=None,
                  sort="recommended", per_page=20):
    """Search the ModelsLab model library.

    Args:
        search: Free text search query
        feature: Filter by feature — "imagen", "video_fusion", "audio_gen",
                 "llmaster", "threed", "interior", "deepfake"
        provider: Filter by provider name
        model_type: Filter by model type
        base_model: Filter by base model (e.g., "SDXL", "Flux")
        tags: Comma-separated tags
        sort: "recommended" (default), "newest", "popular"
        per_page: Results per page (default 20)
    """
    params = {"sort": sort, "per_page": per_page}
    if search: params["search"] = search
    if feature: params["feature"] = feature
    if provider: params["provider"] = provider
    if model_type: params["model_type"] = model_type
    if base_model: params["base_model"] = base_model
    if tags: params["tags"] = tags

    resp = requests.get(
        f"{BASE}/models",
        headers=headers(token),
        params=params
    )
    return resp.json()["data"]

# Search for Flux image models
models = search_models(token, search="flux", feature="imagen", sort="popular")
for m in models:
    print(f"{m['model_id']}: {m['name']}")

# Image generation models
image_models = search_models(token, feature="imagen", per_page=10)

# Video generation models
video_models = search_models(token, feature="video_fusion", per_page=10)

# Audio generation models
audio_models = search_models(token, feature="audio_gen", per_page=10)

# LLM / Chat models
llm_models = search_models(token, feature="llmaster", per_page=10)

# 3D generation models
threed_models = search_models(token, feature="threed", per_page=10)

# Interior design models
interior_models = search_models(token, feature="interior", per_page=10)

def get_model_detail(token, model_id):
    """Get full details for a specific model.

    Returns: capabilities, endpoint configurations with agent-friendly
    `parameters` JSON Schema (types, constraints, defaults), pricing, etc.
    """
    resp = requests.get(
        f"{BASE}/models/{model_id}",
        headers=headers(token)
    )
    return resp.json()["data"]

# Usage
model = get_model_detail(token, "flux-dev")
print(f"Name: {model['name']}")
print(f"Type: {model.get('model_type')}")
print(f"Provider: {model.get('provider')}")

# Access agent-friendly parameters for each endpoint
for ep in model.get("endpoint_configurations", []):
    params = ep.get("parameters")
    if params:
        print(f"\nEndpoint: {ep['name']}")
        for name, schema in params["properties"].items():
            print(f"  {name}: {schema['type']}", end="")
            if "enum" in schema:
                print(f" (options: {schema['enum']})", end="")
            if "default" in schema:
                print(f" [default: {schema['default']}]", end="")
            print()

def get_model_filters(token):
    """Get all available filter options (features, types, categories)."""
    resp = requests.get(f"{BASE}/models/filters", headers=headers(token))
    return resp.json()["data"]

def get_model_tags(token):
    """Get all available model tags."""
    resp = requests.get(f"{BASE}/models/tags", headers=headers(token))
    return resp.json()["data"]

def get_model_providers(token):
    """Get all model providers."""
    resp = requests.get(f"{BASE}/models/providers", headers=headers(token))
    return resp.json()["data"]

# Usage
filters = get_model_filters(token)
tags = get_model_tags(token)
providers = get_model_providers(token)
print(f"Available features: {[f['name'] for f in filters.get('features', [])]}")
print(f"Top tags: {tags[:10]}")
print(f"Providers: {[p['name'] for p in providers]}")

def get_usage_summary(token):
    """Get overall API usage summary — total calls, credits used, etc."""
    resp = requests.get(f"{BASE}/usage/summary", headers=headers(token))
    return resp.json()["data"]

# Usage
summary = get_usage_summary(token)
print(f"Total API calls: {summary.get('total_calls', 0)}")
print(f"Credits used: {summary.get('credits_used', 0)}")

def get_usage_by_product(token):
    """Get usage breakdown by product (image, video, audio, etc.)."""
    resp = requests.get(f"{BASE}/usage/products", headers=headers(token))
    return resp.json()["data"]

# Usage
products = get_usage_by_product(token)
for product in products:
    print(f"{product['name']}: {product.get('calls', 0)} calls")

def get_usage_history(token, from_date=None, to_date=None, limit=100):
    """Get detailed generation history with optional date filters.

    Args:
        from_date: Start date (YYYY-MM-DD)
        to_date: End date (YYYY-MM-DD)
        limit: Max items (1-200, default 100)
    """
    params = {"limit": limit}
    if from_date: params["from"] = from_date
    if to_date: params["to"] = to_date

    resp = requests.get(
        f"{BASE}/usage/history",
        headers=headers(token),
        params=params
    )
    return resp.json()["data"]

# Get last 7 days of history
history = get_usage_history(token, from_date="2025-01-01", to_date="2025-01-07")
for item in history:
    print(f"{item['created_at']}: {item.get('endpoint')} - {item.get('status')}")

def find_best_model(token, task_description, feature):
    """Search for the best model for a given task."""
    models = search_models(
        token,
        search=task_description,
        feature=feature,
        sort="recommended",
        per_page=5
    )

    if not models:
        print("No models found. Try broader search terms.")
        return None

    best = models[0]
    print(f"Recommended: {best['model_id']} — {best['name']}")
    return best["model_id"]

# Find best model for realistic portraits
model_id = find_best_model(token, "realistic portrait photography", "imagen")

# Find best video model
model_id = find_best_model(token, "text to video cinematic", "video_fusion")

def check_usage_health(token, max_daily_spend=100):
    """Monitor usage and alert if spending too fast."""
    from datetime import date

    today = date.today().isoformat()
    history = get_usage_history(token, from_date=today, to_date=today)

    daily_cost = sum(item.get("cost", 0) for item in history)
    daily_calls = len(history)

    print(f"Today: {daily_calls} API calls, ${daily_cost:.2f} spent")

    if daily_cost > max_daily_spend:
        print(f"WARNING: Daily spend ${daily_cost:.2f} exceeds ${max_daily_spend}")
        return False
    return True

def select_model_for_generation(token, prompt, media_type="image"):
    """Full pipeline: search models, check usage, select best model."""

    # Map media type to feature
    feature_map = {
        "image": "imagen",
        "video": "video_fusion",
        "audio": "audio_gen",
        "3d": "threed",
        "chat": "llmaster"
    }
    feature = feature_map.get(media_type, "imagen")

    # Search models
    models = search_models(token, search=prompt, feature=feature, per_page=5)

    if not models:
        # Fallback: search without prompt
        models = search_models(token, feature=feature, sort="popular", per_page=5)

    # Check usage
    summary = get_usage_summary(token)
    print(f"Credits remaining: {summary.get('credits_remaining', 'N/A')}")

    # Return top model
    if models:
        model = models[0]
        print(f"Selected: {model['model_id']} ({model['name']})")
        return model["model_id"]
    return None

# Usage
model_id = select_model_for_generation(token, "anime character", "image")

# More efficient than broad text search
models = search_models(token, feature="imagen", sort="popular")

# Model lists don't change frequently
import functools

@functools.lru_cache(maxsize=32)
def cached_search(feature, sort="recommended"):
    return search_models(token, feature=feature, sort=sort)

detail = get_model_detail(token, model_id)
# Verify model supports your use case, check pricing, etc.

# Set up daily usage checks
summary = get_usage_summary(token)
if summary.get("credits_remaining", 0) < 100:
    print("Low credits — consider topping up wallet")