Integrating Visionatrix: Getting Started¶

This guide will help you get started with programmatically interacting with Visionatrix.

Note

SDXL Lighting and Remove Background (Birefnet) flows should be installed on the Visionatrix instance.

This guide only covers how to create tasks from a flow, fetch their progress, and receive the results.

Info

We constantly strive to make our API more comfortable to use with code generated by Claude, Qwen, or ChatGPT.

However, this guide is primarily focused on understanding the lifespan of a task. It does not describe how to automatically create a Gradio application for the specified flow or any other such topics.

Table of Contents¶

Authentication
Task Lifecycle
Full Working Examples in Python
- Example 1: Using the "SDXL Lighting" Flow
- Example 2: Using the "Remove Background (Birefnet)" Flow

Authentication¶

Visionatrix currently supports Basic Authentication only. Depending on the mode in which Visionatrix is running, you may or may not need to provide authentication credentials:

SERVER Mode: If Visionatrix is running in SERVER mode, you must specify your username and password in your API requests.
DEFAULT Mode: If Visionatrix is running in DEFAULT mode, no authentication is required.

For the purposes of this guide, we will assume that authentication is required.

By default, we use admin as both the username and password in our development setups for SERVER mode when testing Visionatrix. Replace these with your actual credentials if they are different.

Task Lifecycle¶

The typical lifecycle of a task in Visionatrix involves the following steps:

Creating a Task: You send a PUT request to the /api/tasks/create/{name} endpoint, where {name} is the ID of the flow you want to use. The request must use multipart/form-data and include the necessary parameters for the flow.
For the SDXL Lighting (sdxl_lighting) flow, required parameters are:
- prompt (string): The text prompt for image generation.
- steps_number (string): The number of steps to use.
Optional Parameters:
- negative_prompt (string): The "negative" text prompt for image generation.
- seed (integer): The seed for random number generation. If not specified, a random seed will be used.
For the Remove Background (Birefnet) (remove_background_birefnet) flow, required parameters are:
- input_image (file): The image file from which to remove the background.
Other Parameters:
- There are additional optional parameters such as webhook_url, webhook_headers, translate, group_scope, etc. These parameters are not covered in this beginner guide.
Checking Task Progress: After creating a task, you can check its progress using the /api/tasks/progress/{task_id} endpoint. The response includes details such as the task's progress, error (if any), and a list of outputs.
Progress Values:
- 0.0: Task is queued and has not started yet.
- Between 0.1 and 99.9: Task is in progress.
- 100.0: Task is completed.
Error Handling:
- If the error field is not empty, the task has encountered an error.
- You can retry the task or investigate the issue based on the error message.
Retrieving Task Results: Once a task is completed (progress reaches 100.0), you can retrieve the results using the /api/tasks/results endpoint. The outputs from the task details contain a list of output nodes, each with a comfy_node_id. You should iterate over all the outputs to retrieve all results.
To retrieve each result, you send a GET request to /api/tasks/results with the task_id and node_id (which is the comfy_node_id from the outputs).
The result files can then be saved locally. The format of the result file depends on the flow and the output node's type.

Note

We are currently in the process of automatically creating OpenAPI specifications for the flows: Flows API.

You can easily take a look at the flow parameters there.

Full Working Examples in Python¶

Below are full working examples in Python using the httpx library. These scripts demonstrate how to create a task, check its progress, and retrieve all the results for both the sdxl_lighting and remove_background_birefnet flows.

Before running the scripts, make sure you have the httpx library installed:

pip install httpx

Example 1: Using the "SDXL Lighting" Flow¶

import httpx
import time

# Replace with your Visionatrix server URL
base_url = "http://localhost:8288"
username = "admin"
password = "admin"


def create_sdxl_lighting_task():
    # Task parameters
    params = {
        'prompt': 'A beautiful sunset over the mountains',
        'steps_number': '8 steps',
        # 'negative_prompt' is optional
        # 'negative_prompt': 'blurry, low resolution',
        # 'seed' is optional; if not specified, a random seed will be used
        # 'seed': '12345',
    }

    # Convert parameters to the format expected by the 'files' parameter
    files = {key: (None, value) for key, value in params.items()}

    # Create the task
    response = httpx.put(
        f"{base_url}/api/tasks/create/sdxl_lighting",
        auth=(username, password),
        files=files
    )

    # Check if the request was successful
    if response.status_code == 200:
        data = response.json()
        task_ids = data.get('tasks_ids', [])
        if task_ids:
            task_id = task_ids[0]
            print("Task created successfully. Task ID:", task_id)
            return task_id
        else:
            print("No task ID returned.")
    else:
        print("Failed to create task:", response.text)
    return None


def check_task_progress(task_id):
    while True:
        response = httpx.get(
            f"{base_url}/api/tasks/progress/{task_id}",
            auth=(username, password)
        )

        if response.status_code == 200:
            task_details = response.json()
            progress = task_details.get('progress', 0)
            error = task_details.get('error', '')
            print(f"Task {task_id} progress: {progress}%")
            if error:
                print(f"Task {task_id} encountered an error: {error}")
                return None
            if progress >= 100:
                print("Task completed.")
                outputs = task_details.get('outputs', [])
                return outputs  # Return outputs to avoid additional server call
        else:
            print("Failed to get task progress:", response.text)
            return None

        # Wait before polling again
        time.sleep(5)


def retrieve_task_results(task_id, outputs):
    if outputs:
        for output in outputs:
            node_id = output.get('comfy_node_id')
            if node_id is not None:
                # Retrieve the result for each output node
                params = {
                    'task_id': task_id,
                    'node_id': node_id
                }
                result_response = httpx.get(
                    f"{base_url}/api/tasks/results",
                    auth=(username, password),
                    params=params
                )
                if result_response.status_code == 200:
                    # Save the result to a file
                    result_filename = f"result_{task_id}_{node_id}.png"
                    with open(result_filename, 'wb') as f:
                        f.write(result_response.content)
                    print(f"Result saved to {result_filename}")
                else:
                    print(f"Failed to retrieve result for node {node_id}:", result_response.text)
            else:
                print("Output node ID not found.")
    else:
        print("No outputs found in task details.")


def main():
    task_id = create_sdxl_lighting_task()
    if task_id:
        outputs = check_task_progress(task_id)
        if outputs is not None:
            retrieve_task_results(task_id, outputs)


if __name__ == "__main__":
    main()

Example 2: Using the "Remove Background (Birefnet)" Flow¶

import httpx
import time

# Replace with your Visionatrix server URL
base_url = "http://localhost:8288"
username = "admin"
password = "admin"
input_image_path = "image.jpg"


def create_remove_background_task():
    # Open the image file in binary mode
    with open(input_image_path, 'rb') as image_file:
        files = {
            'input_image': image_file
        }

        # Create the task
        response = httpx.put(
            f"{base_url}/api/tasks/create/remove_background_birefnet",
            auth=(username, password),
            files=files
        )

    # Check if the request was successful
    if response.status_code == 200:
        data = response.json()
        task_ids = data.get('tasks_ids', [])
        if task_ids:
            task_id = task_ids[0]
            print("Task created successfully. Task ID:", task_id)
            return task_id
        else:
            print("No task ID returned.")
    else:
        print("Failed to create task:", response.text)
    return None


def check_task_progress(task_id):
    while True:
        response = httpx.get(
            f"{base_url}/api/tasks/progress/{task_id}",
            auth=(username, password)
        )

        if response.status_code == 200:
            task_details = response.json()
            progress = task_details.get('progress', 0)
            error = task_details.get('error', '')
            print(f"Task {task_id} progress: {progress}%")
            if error:
                print(f"Task {task_id} encountered an error: {error}")
                return None
            if progress >= 100:
                print("Task completed.")
                outputs = task_details.get('outputs', [])
                return outputs  # Return outputs to avoid additional server call
        else:
            print("Failed to get task progress:", response.text)
            return None

        # Wait before polling again
        time.sleep(5)


def retrieve_task_results(task_id, outputs):
    if outputs:
        for output in outputs:
            node_id = output.get('comfy_node_id')
            if node_id is not None:
                # Retrieve the result for each output node
                params = {
                    'task_id': task_id,
                    'node_id': node_id
                }
                result_response = httpx.get(
                    f"{base_url}/api/tasks/results",
                    auth=(username, password),
                    params=params
                )
                if result_response.status_code == 200:
                    # Save the result to a file
                    result_filename = f"result_{task_id}_{node_id}.png"
                    with open(result_filename, 'wb') as f:
                        f.write(result_response.content)
                    print(f"Result saved to {result_filename}")
                else:
                    print(f"Failed to retrieve result for node {node_id}:", result_response.text)
            else:
                print("Output node ID not found.")
    else:
        print("No outputs found in task details.")


def main():
    task_id = create_remove_background_task()
    if task_id:
        outputs = check_task_progress(task_id)
        if outputs is not None:
            retrieve_task_results(task_id, outputs)


if __name__ == "__main__":
    main()

Notes:

Replace base_url with your actual Visionatrix server URL if it's different.
For the second example, replace input_image_path with the path to your input image file. Ensure that the file exists at the specified path.
When creating a task, the API expects a PUT request with multipart/form-data. Therefore, even if you are not uploading any files (as in the sdxl_lighting flow), you should use files=params to ensure the request uses the correct content type.
These scripts include basic error handling and polling logic.
The check_task_progress function polls the task progress every 5 seconds. Adjust the sleep time as needed.
The retrieve_task_results function uses the outputs obtained from the check_task_progress function, avoiding an additional call to the server.
The result files are saved in the current working directory with filenames that include the task ID and node ID.
Ensure that the required flows (sdxl_lighting and remove_background_birefnet) are installed on your Visionatrix instance before running these scripts.
Additional optional parameters like webhook_url, translate, group_scope, seed, etc., are available but are not covered in this beginner guide.