Imagine Python 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

• Installation
• Usage
  • Imagine Client
  • Response
  • Image
  • Some More Usage Examples
• Integration With Other Libraries
  • Pillow (PIL)
  • Numpy
• Support
• License

Installation

The API works for python 3.6 and above. To install the package, execute the following command:

pip install imaginesdk

Usage

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

from imagine import Imagine
from imagine.styles import GenerationsStyle
from imagine.models import Status

# 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=GenerationsStyle.IMAGINE_V5,
)

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

Result:

Imagine Client

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[Image]
• Image-Remix: image_remix() -> Response[Image]
• Super-Resolution: super_resolution() -> Response[Image]
• Variations: variations() -> Response[Image] (Currently Not Supported)
• In-Painting: in_painting() -> Response[Image] (Currently Not Supported)

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

Response

Response is the return type for each of our functions. It contains the following:

• status: Status property which returns an enum containing the status code of the response.
• data: A 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(): 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.

Image

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

bytes

Returns the bytes received after a request operation

image.bytes # -> bytes

as_file(file_path: str)

Stores the image in the specified path and returns the path.

image.as_file("file_path") # -> str (file_path)

to_pil_image()

The module is loaded dynamically and is not included in the default package, you can choose to forgo this dependency. See this for more information.

to_numpy()

The module is loaded dynamically and is not included in the default package, you can choose to forgo this dependency. See this for more information.

Some More Usage Examples

Variations

Currently Not Supported

from imagine import Imagine
from imagine.styles import GenerationsStyle
from imagine.models import Status

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

# Generate an image using the variations feature
response = client.variate(
    image_path="anime_girl.png",
    prompt="a cute anime girl in a forest",
    style=GenerationStyle.ANIME,
)

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

Result:

In-Painting

Currently Not Supported

from imagine import Imagine
from imagine.styles import InPaintingStyle
from imagine.models import Status

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

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

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

Result:

Integration With Other Libraries

The Imagine SDK has two levels of dependencies. By default, only the requests library is shipped as a dependency. If you want to use Pillow and Numpy as well, execute the following command:

pip install imaginesdk[all]

If you want one but not the other dependency then you also have the option of installing the module separately.

Pillow (PIL)

If you installed imaginesdk[all], you can skip the first step.

First, get the dependency for Pillow

pip install Pillow

After running the aforementioned command you can now use the response data as a pillow object:

image.to_pil_image() # -> PIL_Image

Numpy

If you installed imaginesdk[all], you can skip the first step.

First, get the dependency for Numpy

pip install numpy

After running the aformentioned command you can now use the response data as a numpy object:

image.to_numpy() # -> numpy.ndarray

Support

If you run into any version issues, please contact us at [email protected] or support.imagine.api

License

This project is licensed under the Apache 2 License.