vyroimagine 1.0.0b1
Python client library for the Imagine API
License: MIT
Requires Python: >=3.6

# 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](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Results](#results)
- [License](#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)

If you run into any version issues, please contact us on our [support page](#).

## Installation

### Pip Install
The SDK is available as a package on PyPI.

**Simply run the following command:**
```bash
pip install imaginesdk
```

### 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:**
```bash
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)**
```bash
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.
```python
import imaginesdk

# 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="cute small cartoonic creatures in a jungle", style_id=ImagineGenerations.DISNEY)

# Check if the request was successful
if response.status.value == 200:
    image = response.data
    image.pil_image().save("result.png")
else:
    print("Something went wrong!")
```
**Result**:
![Generations](https://vyroai.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Feb3b1f83-c1c0-4f07-a206-d317d7f89403%2F2.jpg?table=block&id=2f702a9a-89fb-4529-9a17-c9f36af33843&spaceId=60572bb8-cbeb-42ba-b882-c88845384d44&width=2000&userId=&cache=v2)

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() -> ImagineResponse
- **Image-Remix**: image_remix() -> ImagineResponse
- **Super-Resolution**: super_resolution -> ImagineResponse
- **Variate**: variate -> ImagineResponse
- **In-Painting**: in_painting() -> ImagineResponse
- **Alter-Image**: alter_image() -> ImagineResponse

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.
- pil_image() -> PIL_Image
- numpy() -> numpy.ndarray

### Some More Usage Examples:
**Variate**:
```python
import imaginesdk

# 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.pil_image().save(f"result{i}.png")
    else:
        print("Something went wrong!")
```
**Result**:
![Variate](https://vyroai.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2F7a2a54f2-c762-45ea-a1bd-c655ed421caa%2Fbanner_2.png?table=block&id=d60f4549-e35c-4044-afaa-7cd9d17803a2&spaceId=60572bb8-cbeb-42ba-b882-c88845384d44&width=2000&userId=&cache=v2)

**In-Painting**:
```python
import imaginesdk

# 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.pil_image().save("result.png")

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

```
**Result**:
![InPainting](https://vyroai.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2F7017cedd-aeda-4a3e-ad09-54eb8b93399d%2Finpainting.jpg?table=block&id=1bc58f0f-1d7f-465f-b414-200ceb2464b1&spaceId=60572bb8-cbeb-42ba-b882-c88845384d44&width=2000&userId=&cache=v2)

## License
This project is licensed under the MIT License.