Training Models

Training custom models is a powerful feature of the Scenario API, allowing you to create specialized AI models tailored to your specific needs. This guide will walk you through the process of training both Flux Dev LoRA and SDXL LoRA models, detailing the necessary steps, API endpoints, and parameters. We will also provide code examples to help you integrate model training into your applications.

🚀 Key Concepts

Before diving into the training process, it's important to understand a few key concepts:

• Model: In the context of the Scenario API, a model refers to a custom-trained AI model capable of generating images. You provide training images and define specific parameters, and we handle the intricate training process.

• LoRA (Low-Rank Adaptation): LoRA is a technique that significantly reduces the number of trainable parameters for downstream tasks by freezing the pre-trained model weights and injecting trainable rank decomposition matrices into the Transformer architecture. This makes training more efficient and less resource-intensive.

• Flux Dev LoRA: A LoRA model specifically designed for use with Flux Dev base model.

• SDXL LoRA: A LoRA model specifically designed for use with Stable Diffusion XL (SDXL) base model.

• Training Images: These are the images you provide to the API to teach your model a specific style, object, or concept. The quality and diversity of your training images directly impact the performance and output of your trained model. More info about your training images dataset here.

• Captioning: Automatic captioning is applied to uploaded training images, providing textual descriptions that help the model understand the content of each image. You have the option to modify these captions for greater accuracy. More info about captioning here.

• Asynchronous Training: Model training is an asynchronous process, meaning it runs in the background and can take a significant amount of time (from minutes to several hours, depending on the dataset size). You will need to poll the API to check the status of your training job.

⚡️ Training Workflow

The general workflow for training a model involves the following steps:

1. Create a Model: Initialize a new model by specifying its name and type.
2. Add Training Images: Upload a dataset of images that the model will learn from. Each image can be accompanied by a caption.
3. (Optional) Modify Captions: Adjust the automatically generated captions for your training images to improve training accuracy.
4. Initiate Training: Start the training process for your model.
5. Monitor Training Status: Periodically check the status of your training job until it is complete.

Let's explore each step in detail.

1. Create a Model

To begin, you need to create a new model instance. This involves making a POST request to the /v1/models endpoint, providing a name for your model and specifying its type. The type parameter is crucial as it determines the underlying architecture and capabilities of your model. For training, you will typically use flux.1-lora for Flux Dev LoRA models or sd-xl-lora for SDXL LoRA models.

Endpoint:

POST https://api.cloud.scenario.com/v1/models

Request Body Parameters:

Example Request (Python):

import requests

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

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

payload = {
    "name": "My First LoRA Model",
    "type": "flux.1-lora" # or "sd-xl-lora" for SDXL LoRA
}

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

if response.status_code == 200:
    model_data = response.json()
    model_id = model_data["id"]
    print(f"Model created successfully! Model ID: {model_id}")
else:
    print(f"Error creating model: {response.status_code} - {response.text}")

Upon successful creation, the response will include the modelId, which you will need for subsequent steps.

2. Add Training Images

Once your model is created, you need to provide it with training images. These images are crucial for teaching your model the specific characteristics you want it to learn. You will make a POST request to the /v1/models/{modelId}/training-images endpoint for each image you want to add. It is recommended to add between 5 and 100 images for effective training.

Endpoint:

POST https://api.cloud.scenario.com/v1/models/{modelId}/training-images

Path Parameters:

Request Body Parameters:

Example Request (Python):

import requests

# Assuming model_id is obtained from the previous step
# model_id = "your_model_id"

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

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

# Replace with your actual image data URL
image_data_url = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=" # Example: a 1x1 transparent PNG

payload = {
    "data": image_data_url,
    "name": "Training Image 1"
}

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

if response.status_code == 200:
    asset_data = response.json()
    asset_id = asset_data["id"]
    print(f"Training image added successfully! Asset ID: {asset_id}")
else:
    print(f"Error adding training image: {response.status_code} - {response.text}")

Repeat this step for all your training images.

3. (Optional) Modify Captions of Training Images

While automatic captioning is applied to uploaded images, you can refine these captions to improve the training process. Accurate captions help the model better understand the content of each image. To modify a caption, you will make a PUT request to the /v1/assets/{assetId} endpoint.

Endpoint:

PUT https://api.cloud.scenario.com/v1/assets/{assetId}

Path Parameters:

Request Body Parameters:

Example Request (Python):

import requests

# Assuming asset_id is obtained from the previous step
# asset_id = "your_asset_id"

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

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

payload = {
    "description": "A detailed description of the image content, e.g., a red car on a sunny street"
}

response = requests.put(url, headers=headers, json=payload)

if response.status_code == 200:
    print(f"Caption for asset {asset_id} modified successfully!")
else:
    print(f"Error modifying caption: {response.status_code} - {response.text}")

4. Initiate Training

Once you have uploaded all your training images (and optionally modified their captions), you can initiate the model training process. This is done by making a PUT request to the /v1/models/{modelId}/train endpoint. You can include specific training parameters in the request body, though for many cases, default parameters are sufficient.

Endpoint:

PUT https://api.cloud.scenario.com/v1/models/{modelId}/train

Path Parameters:

Request Body Parameters:

Example Request (Python):

import requests

# Assuming model_id is obtained from the model creation step
# model_id = "your_model_id"

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

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

payload = {
    "parameters": {
        # Example parameters (refer to API reference for full list)
        "learningRate": 0.0004,
        "maxTrainSteps": 750,
        optimizeFor: undefined,
    }
}

response = requests.put(url, headers=headers, json=payload)

if response.status_code == 200:
    job_data = response.json()
    job_id = job_data["job"]["jobId"]
    print(f"Model training initiated successfully! Job ID: {job_id}")
else:
    print(f"Error initiating training: {response.status_code} - {response.text}")

5. Monitor Training Status

Model training is an asynchronous process. After initiating training, you will receive a jobId. You need to poll the API using this jobId to check the training progress and status. The method for checking status can vary slightly depending on the model type:

• Flux Dev LoRA: Poll the GET /v1/jobs/{jobId} endpoint.
• SDXL LoRA: Poll the GET /v1/models/{modelId} endpoint, as the model status itself will update.

Monitoring Flux Dev LoRA Training (Polling Job Status)

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 training 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 complete. 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

Monitoring SDXL LoRA Training (Polling Model Status)

Endpoint:

GET https://api.cloud.scenario.com/v1/models/{modelId}

Path Parameters:

Example Request (Python):

import time
import requests

# Assuming model_id is obtained from the model creation step
# model_id = "your_model_id"

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

url = f"https://api.cloud.scenario.com/v1/models/{model_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()
    model_status = data["status"]

    print(f"Model status: {model_status}")

    if model_status == "trained":
        print("Model training complete!")
        break
    elif model_status == "failed":
        raise Exception(f"Model training failed. Status: {model_status}")

    time.sleep(5) # Poll every 5 seconds

Once the model status is trained (for SDXL LoRA) or the job status is success (for Flux Dev LoRA), your model is ready for use in image generation tasks.

📚 References

• Scenario API Reference: POST /v1/models
• Scenario API Reference: PUT /v1/models/{modelId}/train