Third Party Image Model Generation

Introduction

The Scenario API offers a powerful suite of tools for programmatic access to AI-powered content generation.

This article will guide you through the process of using the Scenario API to generate images with your custom models, focusing on POST /generate/custom/{modelId} endpoint.

The Custom Model Endpoint

For generating images with custom models, as well as for other advanced generation tasks like creating videos or 3D models, the Scenario API provides a flexible endpoint:

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

This endpoint is designed to handle the complexities of various generative models. When you make a request to this endpoint, the API initiates a job in the background and returns a jobId. You can then use this jobId to poll for the status of your generation and retrieve the final asset once it's complete. It is important to note that for some specific base models like SDXL, and Flux.1, including LoRAs, you should use the /generate/txt2img or /generate/prompt-editing endpoints instead.

Authentication

The Scenario API uses Basic Authentication. You will need to provide your API key and secret, encoded in Base64, in the Authorization header of your request.

Crafting Your Request

To generate an image, you will need to send a JSON payload in the body of your POST request. The parameters in this payload will vary depending on the model you are using. You can retrieve the specific inputs for any model by using the GET /models/{modelId} endpoint.

For our example, we will use the model_imagen4-ultra model. The key parameters for a text-to-image generation request with this model are prompt and aspectRatio.

Code Example: Generating an Image

Here is a Python example demonstrating how to make a request to the custom model endpoint to generate an image. This snippet initiates the generation process.

import requests
import os

# It is recommended to use environment variables for your API key and secret
api_key = os.environ.get("SCENARIO_API_KEY")
api_secret = os.environ.get("SCENARIO_API_SECRET")

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

headers = {
    "Content-Type": "application/json"
}

payload = {
    "prompt": "a futuristic cityscape at sunset, with flying cars and neon signs, photorealistic",
    "aspectRatio": "16:9"
}

response = requests.post(url, headers=headers, json=payload, auth=(api_key, api_secret))

if response.status_code == 200:
    data = response.json()
    job_id = data.get("job", {}).get("jobId")
    if job_id:
        print(f"Image generation job initiated successfully. Job ID: {job_id}")
    else:
        print("Error: Could not retrieve job ID from the response.")
else:
    print(f"Error: {response.status_code} - {response.text}")

Handling the Asynchronous Response

After initiating the generation, you need to poll the /jobs/{jobId} endpoint to check the status of your request. The job will go through queued and processing states before reaching success, failed, or canceled.

Code Example: Polling for Results

This Python script shows how to poll for the job status and retrieve the asset ID of the generated image upon successful completion.

import requests
import time
import os

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

# Replace with the job_id from the previous step
job_id = "your_job_id_here"

polling_url = f"https://api.scenario.com/v1/jobs/{job_id}"

headers = {
    "Authorization": f"Basic {requests.auth._basic_auth_str(api_key, api_secret)}"
}

while True:
    response = requests.get(polling_url, headers=headers)
    if response.status_code == 200:
        data = response.json()
        status = data.get("job", {}).get("status")
        print(f"Job status: {status}")

        if status == "success":
            asset_ids = data.get("job", {}).get("metadata", {}).get("assetIds", [])
            if asset_ids:
                print(f"Job complete. Asset ID: {asset_ids[0]}")
            else:
                print("Job complete, but no asset IDs found.")
            break
        elif status in ["failed", "canceled"]:
            print(f"Job ended with status: {status}")
            break
    else:
        print(f"Error polling job status: {response.status_code} - {response.text}")
        break

    time.sleep(3) # Wait for 3 seconds before polling again

Conclusion

Generating images with custom models via the Scenario API is a straightforward process that opens up a world of creative possibilities. By using the POST /generate/custom/{modelId} endpoint and implementing a simple polling mechanism, you can integrate powerful, customized image generation directly into your applications and workflows. The flexibility of the API allows you to tailor your requests with specific parameters like prompt and aspectRatio, giving you fine-grained control over the creative output.