Scenario API Examples - Quick Start Guide

The Scenario API uses a unified endpoint for generation types other than SDXL or Flux LoRA. Whether you are creating a video, a 3D model, or a sound effect, the pattern is always the same:

Endpoint: POST https://api.cloud.scenario.com/v1/generate/custom/{modelId}

The Workflow

Select a Model ID: Choose the specific model for your modality (e.g., model_kling-v2-6-t2v-pro for video).
Send Request: POST your prompt and parameters to the endpoint.
Poll for Result: Receive a jobId and check its status until the asset is ready.

Python Code Example

This script includes a reusable polling function and examples for Video, Audio, 3D, and Third-Party Images.

Prerequisites:

Get your keys from the Scenario Webapp.
Install requests: pip install requests


import requests
import time
import base64

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

# Basic Auth Header
auth_str = f"{API_KEY}:{API_SECRET}"
b64_auth = base64.b64encode(auth_str.encode()).decode()
headers = {
    "Authorization": f"Basic {b64_auth}",
    "Content-Type": "application/json"
}

def run_generation(model_id, payload):
    """
    Generic function to trigger generation and poll for the result.
    """
    url = f"{BASE_URL}/generate/custom/{model_id}"
    
    print(f"\n--- Starting Generation: {model_id} ---")
    
    # 1. Start the Job
    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        job_data = response.json()
        job_id = job_data['job']['jobId']
        print(f"Job Initiated. ID: {job_id}")
    except requests.exceptions.RequestException as e:
        print(f"Error starting job: {e}")
        if response.text: print(response.text)
        return

    # 2. Poll for Completion
    poll_url = f"{BASE_URL}/jobs/{job_id}"
    while True:
        resp = requests.get(poll_url, headers=headers)
        status_data = resp.json()
        status = status_data['job']['status']
        
        if status == 'success':
            # Result is usually a list of assetIds or a direct URL depending on model
            result = status_data['job'].get('result', {})
            metadata = status_data['job'].get('metadata', {})
            
            # Try to grab the Asset ID or URL
            asset_ids = metadata.get('assetIds', [])
            print(f"SUCCESS! Assets created: {asset_ids}")
            print(f"Full Result: {result}")
            break
        elif status in ['failed', 'cancelled']:
            print(f"Job Failed: {status_data['job'].get('error')}")
            break
            
        print(".", end="", flush=True)
        time.sleep(3) # Wait 3 seconds before next check

# ==========================================
# UNCOMMENT A BLOCK BELOW TO TEST A MODALITY
# ==========================================

# --- 1. VIDEO GENERATION ---
# Model: Kling v2.6 T2V Pro
# Docs: https://docs.scenario.com/docs/video-generation
# video_model = "model_kling-v2-6-t2v-pro"
# video_payload = {
#     "prompt": "A cinematic drone shot of a futuristic city at sunset, highly detailed",
#     "aspectRatio": "16:9",
#     "duration": 5
# }
# run_generation(video_model, video_payload)


# --- 2. AUDIO GENERATION (Music) ---
# Model: Google Lyria 2
# Docs: https://docs.scenario.com/docs/audio-generation
# audio_model = "model_lyria-2"
# audio_payload = {
#     "prompt": "Futuristic country music, steel guitar, huge 808s, synth wave elements space western cosmic twang soaring vocals",
# }
# run_generation(audio_model, audio_payload)


# --- 3. 3D GENERATION (Text-to-3D) ---
# Model: Meshy Text to 3D
# Docs: https://docs.scenario.com/docs/3d-model-generation
# threed_model = "model_meshy-txt23d" 
# threed_payload = {
#     "prompt": "A low-poly treasure chest with gold coins"
# }
# run_generation(threed_model, threed_payload)


# --- 4. THIRD-PARTY IMAGE GENERATION ---
# Model: Imagen 4 Ultra
# Docs: https://docs.scenario.com/docs/third-party-model-generation
# image_model = "model_imagen4-ultra"
# image_payload = {
#     "prompt": "A photorealistic portrait of an astronaut in a garden",
#     "aspectRatio": "4:3"
# }
# run_generation(image_model, image_payload)

Important Notes

Model IDs: The IDs used above (model_kling-v2-1, model_imagen4-ultra) are examples. You must check the Parameters Reference in GENERATION API CALLS section for the latest available Model IDs.
Payloads: Each model requires specific parameters (e.g., lyrics for music vs prompt for video). Always verify the JSON structure in the docs.
Assets: For Image-to-Video or Image-to-3D, you must first upload an image to Scenario to get an assetId, which you then pass in the payload. See documentation here.
Download your asset: please check our dedicated article to download your asset after the generation is completed.

Official Documentation

For the complete list of parameters and model IDs, refer to the specific guides:

Was this helpful?

Quick Start: Universal Generation (Video, Audio, 3D, Image)

The Workflow

Python Code Example

Important Notes

Official Documentation