> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

[![PyPI - Version](https://img.shields.io/pypi/v/sunra_client)](https://pypi.org/project/sunra_client)

### Introduction

The client library for Python offers an easy-to-use interface to interact with Sunra's services.

### Installation

To integrate the client into your project, install it using pip:

```bash theme={null}
pip install sunra-client
```

### Features

#### Calling Endpoints

Sunra manages endpoint requests through a queue system, ensuring reliability and scalability. Use the `subscribe` method to submit a request and await the result.

**Example:**

```python theme={null}
import sunra_client

result = sunra_client.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={
    	"prompt": 'A Studio Ghibli-inspired seaside town with colorful houses, laundry flapping, and cats sleeping on windowsills.',
    	"width": 1024,
    	"height": 768,
    	"output_format": 'jpeg'
    },
    with_logs=True,
    on_enqueue=print,
    on_queue_update=print,
)
print(result)
```

#### Queue Management

Manage your requests with these methods:

##### Submitting a Request

Submit a request and retrieve the `request_id` for later use.

**Example:**

```python theme={null}
import sunra_client

handler = sunra_client.submit(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={
      "prompt": 'A Studio Ghibli-inspired seaside town with colorful houses, laundry flapping, and cats sleeping on windowsills.',
      "width": 1024,
      "height": 768,
      "output_format": 'jpeg'
    },
    webhook_url="https://optional.webhook.url/for/results",
)
request_id = handler.request_id
```

##### Checking Request Status

Retrieve the status of a request.

**Example:**

```python theme={null}
import sunra_client
status = sunra_client.status(request_id, with_logs=True)
```

##### Retrieving Request Results

Fetch the result of a completed request.

**Example:**

```python theme={null}
import sunra_client
result = sunra_client.result(request_id)
```

#### File Uploads

Upload files to obtain URLs for use in asynchronous requests. This is essential for models that process files, such as image-to-video or speech-to-text converters.

<Note>Maximum file size: 100MB</Note>

##### Uploading a Local File

You can easily upload a file from your local filesystem. This is useful for scripts or applications that process local data.

```python theme={null}
import sunra_client

# Initialize the synchronous client
client = sunra_client.SyncClient()

try:
  # Upload a file from a given path
  file_url = client.upload_file(path="path/to/your/image.png")
  print(f"File uploaded successfully: {file_url}")
  # This URL can now be used with a model endpoint
except FileNotFoundError:
  print("Error: The file was not found at the specified path.")
except Exception as e:
  print(f"An error occurred: {e}")
```

##### Uploading In-Memory Data

You can also upload data that is held in memory, such as the content of an image created with PIL (Pillow) or a file received in a web request.

<CodeGroup>
  ```python PIL Image theme={null}
  import sunra_client
  from PIL import Image
  import io

  # Initialize the synchronous client
  client = sunra_client.SyncClient()

  # Create an image in memory, for example with Pillow
  image = Image.new("RGB", (600, 400), color = 'red')
  byte_arr = io.BytesIO()
  image.save(byte_arr, format='PNG')
  image_bytes = byte_arr.getvalue()

  # Upload the in-memory image data using the `upload` method
  image_url = client.upload(
      data=image_bytes,
      content_type="image/png"
  )
  print(f"Image uploaded successfully: {image_url}")
  ```

  ```python Raw Bytes theme={null}
  import sunra_client

  # Initialize the synchronous client
  client = sunra_client.SyncClient()

  # Some raw bytes you might have from reading a file or a web request
  raw_data = b"some file content here"

  # Upload the raw bytes
  data_url = client.upload(
      data=raw_data,
      content_type="application/octet-stream"
  )
  print(f"Data uploaded successfully: {data_url}")
  ```
</CodeGroup>

### Support

Join our community for help or discussions:

* **Discord Community**: [Join us](https://discord.gg/897qCzvCcU)
* **GitHub Repository**: [Visit here](https://github.com/sunra-ai/sunra-clients)

We're here to assist you!