imaginesdk 1.0.0b2

Python client library for the Imagine API

Imagine SDK

Imagine SDK is a Python library that provides a convenient interface to interact with the Imagine API for image generation and manipulation. This README provides an overview of the library's features, installation instructions, and usage examples.

Table of Contents

• Features
• Requirements
• Installation
• Usage
• License

Features

• Seamless integration with the Imagine API for image generation, remixing, super-resolution, and more.
• Clean and Pythonic API design for ease of use.
• Strongly typed responses and error handling for reliable interaction.

Requirements

• Python 3.6+ (Required)
• NumPy (Optional)
• Pillow (Optional)
• Requests (Optional)

The optioal dependencies can be opted in for by using:

pip install -e .

Or manually installing the components you need. You have the option of plugging in your own implementation of certain components if you so choose to forgo using the provided ones. If you run into any version issues, please contact us at [e-mail].

Installation

Pip Install

The SDK is available as a package on PyPI.

Simply run the following command:

pip install vyroimagine

Cloning The Repository

You won't have need for this unless you want to modify the package itself.

• Clone the repository to your local machine:

git clone https://github.com/Vyro-ai/imagine-sdk-python.git

• Open up the imagine-sdk-python directory
• Install the library and its dependencies using pip (Preferably activate a virtual environment before you proceed with this step)

pip install .

Usage

The SDK needs to be cnfigured with an api key which is available here. It will be passed to the Imagine class as an argument while instantiating it.

from imagine.client import Imagine

# Initialize the Imagine client with your API token
client = Imagine(token="your-api-token")

# Generate an image using the generations feature
response = client.generations(prompt="A vibrant and whimsical fantasy forest with magical creatures, glowing plants, and a flowing river, in a digital painting style inspired by video games like Ori and the Blind Forest.", style_id=GenerationsStyle.STYLE_IMAGINE_V5)

# Check if the request was successful
if response.status.value == 200:
    image = response.data
    image.to_pil_image().save("result.png")
else:
    print(f"Status Code: {response.status.value}")

Result:

The Imagine class acts as a facade, providing an interface to interact with all of our endpoints. It currently provides the following features:

• Text-To-Image: generations() -> Response[ResponseImage]
• Image-Remix: image_remix() -> Response[ResponseImage]
• Super-Resolution: super_resolution -> Response[ResponseImage]
• Variate: variate -> Response[ResponseImage]
• In-Painting: in_painting() -> Response[ResponseImage]
• Alter-Image: alter_image() -> Response[ResponseImage]

For the full list of arguments and other details, check out the documentation.

ImaineResponse is the response type for each of our functions. It contains the following:

• A status: ImagineError property which returns an enum contatining the status code of the response.
• A data property which contains the request response.
• get_or_throw() -> either returns the response content or raises an Error if the response content was empty.
• get_or_else(default: T) -> either returns the response content or returns the default value if its empty.

For the full list of arguments and other details, check out the documentation.

All the functions related to Images contain an ImagineImage data type as the data in their ImagineResponse. It currently provides the following:

• bytes: bytes returns the response bytes as they are.
• as_file(file_path: str) -> str (file_path)
• to_pil_image() -> PIL_Image (The module is loaded dynamically, you can choose to forgo this dependency)
• to_numpy() -> numpy.ndarray (The module is loaded dynamically, you can choose to forgo this dependency)

Some More Usage Examples:

Variate:

from imagine.client import Imagine

# Initialize the Imagine client with your API token
client = Imagine(token="your-api-token")

# Generate an image using the generations feature
for i in range(2):
    response = client.variate(image_path="anime_girl.png", prompt="a cute anime girl in a forest", style_id=ImagineGenerations.ANIME)

    # Check if the request was successful
    if response.status.value == 200:
        image = response.data
        image.as_file(f"result{i}.png")
    else:
        print(f"Status Code: {response.status.value}")

Result:

In-Painting:

from imagine.client import Imagine

# Initialize the Imagine client with your API token
client = Imagine(token="your-api-token")

# Generate an image using the generations feature
response = client.in_painting(image_path="couple.png", mask_path="mask.png", prompt="woman sitting next to a teddy bear")

# Checking the request status in a try-catch block
try:
    image = response.get_or_throw()
    image.to_pil_image().save("result.png")

except ValueError as e:
    print("An error occurred:", e)
    print(f"Error Code: {result.status.value}")

Result:

License

This project is licensed under the MIT License.