Scenario Tools

Scenario's Tools are specialised models that perform image‑level or sequence‑level transformations. These include cutting an image into equal slices, assembling several images into a grid, or turning a series of frames into a video. They all use the same custom endpoint for generation:

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

You replace {modelId} with the identifier of the tool model you want to run. This endpoint accepts a JSON payload whose fields depend on the model and returns a jobId so you can poll for the result. The endpoint documentation notes that you must provide the model ID and an asset ID for your input image, and that the actual parameters vary by model.

Because image and video transformations can take time, the API responds immediately with a job ID. You then poll GET https://api.cloud.scenario.com/v1/jobs/{jobId} to monitor progress. When the job status becomes success, the response will include the asset IDs of the generated outputs.

The following sections describe each tool available in the Tools – Parameters Reference page and show how to call them.

Example with Scenario Image Slicer

The Image Slicer divides a single image into a grid of equal parts. This is useful for creating spritesheets, breaking down large backgrounds, or extracting parts of a picture for further processing. The model ID is model_scenario-image-slicer.

Parameters

1. Example Request (Python)

import requests
import os

api_key = os.environ.get("SCENARIO_API_KEY")
api_secret = os.environ.get("SCENARIO_API_SECRET")

# Replace with your image asset ID
image_asset = "assetId"
model_id = "model_scenario-image-slicer"

url = f"https://api.cloud.scenario.com/v1/generate/custom/{model_id}"

payload = {
    "image": image_assetId,
    "xSubdivisions": 3,
    "ySubdivisions": 2
}

response = requests.post(url, json=payload, auth=(api_key, api_secret))
if response.status_code == 200:
    job_id = response.json()["job"]["jobId"]
    print(f"Image slicing job started: {job_id}")
else:
    print(f"Error: {response.status_code} – {response.text}")

2. Monitor Job Status

Similar to other asynchronous operations in the Scenario API, you need to poll the API to check the status of your image editing job. You will make GET requests to the /v1/jobs/{jobId} endpoint until the job reaches a final status (e.g., success, failure, or canceled).

Endpoint:

GET https://api.cloud.scenario.com/v1/jobs/{jobId}

Path Parameters:

Example Request (Python):

import time
import requests

# Assuming job_id is obtained from the editing initiation step
# job_id = "your_job_id"

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

url = f"https://api.cloud.scenario.com/v1/jobs/{job_id}"
headers = {"Authorization": f"Basic {requests.utils.b64encode(f'{api_key}:{api_secret}'.encode()).decode()}"}

while True:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # Raise an exception for HTTP errors
    data = response.json()
    status = data["job"]["status"]

    print(f"Job status: {status}")

    if status == "success":
        asset_ids = data["job"]["metadata"].get("assetIds", [])
        print(f"Job completed. Asset IDs: {asset_ids}")
        break
    elif status in ["failure", "canceled"]:
        raise Exception(f"Job ended with status: {status}")

    time.sleep(3) # Poll every 3 seconds

3. Retrieve Edited Image

Once the job status is success, the metadata field of the job response will contain the assetIds of the newly generated (edited) images. You can then use these assetIds to retrieve the actual image data, for example, by using the GET /v1/assets/{assetId} endpoint if available, or by constructing a direct download URL if the API provides one.

Example of successful job response (relevant part):

{
  "job": {
    "jobId": "job_tool_example",
    "status": "success",
    "metadata": {
      "assetIds": [
        "asset_image_1",
        "asset_image_2"
      ]
    }
    // ... other job details
  }
}