sunra-client 0.3.0

Python client for sunra.ai

sunra.ai Python Client

This is a Python client library for interacting with ML models deployed on sunra.ai.

Getting Started

To install the client, run:

pip install sunra-client

Before using the client, you'll need to:

1. Sign up at sunra.ai
2. Get your API key from the dashboard
3. Set your API key as an environment variable: export SUNRA_KEY=your-api-key

Configuration

There are two ways to configure your API key:

Method 1: Global Configuration (Recommended)

import sunra_client

# Configure the client with your API key
sunra_client.config(credentials="your-api-key")

# Now you can use the client without passing the key explicitly
response = sunra_client.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={"prompt": "a cute cat, realistic, orange"}
)

Method 2: Environment Variable

Set your API key as an environment variable:

export SUNRA_KEY=your-api-key

Method 3: Explicit Client Configuration

import sunra_client

# Create a client with explicit API key
client = sunra_client.SyncClient(key="your-api-key")

# Or for async client
async_client = sunra_client.AsyncClient(key="your-api-key")

Usage Examples

Now you can use the client to interact with your models. Here's an example of how to use it:

import sunra_client

response = sunra_client.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={
      "prompt": "a cute cat, realistic, orange"
    },
    with_logs=True,
    on_enqueue=print,
    on_queue_update=print
)
print(response["images"][0]["url"])

Streaming Responses

You can stream real-time updates as your request is being processed:

import sunra_client

application = "black-forest-labs/flux-kontext-pro/text-to-image"
arguments = {"prompt": "a cute cat, realistic, orange"}

for event in sunra_client.stream(application, arguments):
    print(f"Received event: {event}")

Asynchronous Requests

The client also supports asynchronous requests out of the box. Here's an example:

import asyncio
import sunra_client

async def main():
    response = await sunra_client.subscribe_async(
        "black-forest-labs/flux-kontext-pro/text-to-image",
        arguments={"prompt": "a cute cat, realistic, orange"}
        with_logs=True,
        on_enqueue=print,
        on_queue_update=print
    )
    print(response["images"][0]["url"])

asyncio.run(main())

Queuing Requests

When you want to send a request and keep receiving updates on its status, you can use the submit method:

import asyncio
import sunra_client

async def main():
    response = await sunra_client.submit_async(
        "black-forest-labs/flux-kontext-pro/text-to-image",
        arguments={"prompt": "a cute cat, realistic, orange"}
    )

    async for event in response.iter_events():
        if isinstance(event, sunra_client.Queued):
            print("Queued. Position:", event.position)
        elif isinstance(event, (sunra_client.InProgress, sunra_client.Completed)):
            print(event)

    result = await response.get()
    print(result["images"][0]["url"])

asyncio.run(main())

File Upload Support

The client supports uploading files to sunra.ai:

import sunra_client
from PIL import Image

# Create a sync client
client = sunra_client.SyncClient()

# Upload an image file
image = Image.new("RGB", (100, 100), color="red")
image_url = client.upload_image(image)

# Upload any file from local path
file_url = client.upload_file("path/to/your/file.txt")

# Upload raw data
data_url = client.upload(
    data=b"Hello, World!",
    content_type="text/plain",
    file_name="hello.txt"
)

File Upload Limits:

• Maximum file size: 100MB
• Supported formats: Images, videos, audio, documents, and other file types as supported by the specific model

Automatic Input Transformation

The Python SDK automatically transforms file inputs when you call submit() or subscribe(). This means you can pass various file types directly in your input arguments, and they will be automatically uploaded and replaced with URLs.

Supported Input Types

The SDK automatically handles:

• PIL Image objects - Automatically uploaded as images
• Base64 data URIs - Decoded and uploaded with appropriate content type
• File paths - Local files uploaded to CDN
• File-like objects - Objects with read() method (e.g., io.BytesIO, open file handles)

Automatic Transformation Example

import sunra_client
from PIL import Image
import io

client = sunra_client.SyncClient()

# Create a PIL image
image = Image.new("RGB", (100, 100), color="blue")

# You can pass the image directly - it will be automatically uploaded
response = client.subscribe(
    "black-forest-labs/flux-kontext-pro/image-to-image", 
    arguments={
        "prompt": "Make this image more artistic",
        "image": image,  # PIL Image - automatically uploaded
        "reference": "path/to/reference.jpg",  # File path - automatically uploaded
        "mask": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",  # Data URI - automatically uploaded
    }
)

Manual Input Transformation

You can also manually transform inputs if needed:

# For async client
transformed = await async_client.transform_input({
    "image": pil_image,
    "files": ["file1.txt", "file2.jpg"],
    "data": data_uri,
    "metadata": {"nested": {"file": "path/to/file.pdf"}}
})

# For sync client  
transformed = sync_client.transform_input({
    "image": pil_image,
    "document": "path/to/document.pdf"
})

Nested Object Support

The transformation works recursively on nested objects and arrays:

input_data = {
    "prompt": "Process these images",
    "images": [image1, image2, image3],  # All PIL images will be uploaded
    "settings": {
        "reference": "path/to/reference.jpg",  # Nested file path will be uploaded
        "masks": [mask1_data_uri, mask2_data_uri]  # Nested data URIs will be uploaded
    }
}

# All file inputs will be automatically transformed when submitted
response = client.subscribe("some-endpoint", arguments=input_data)

Error Handling

The client provides comprehensive error handling with detailed error information:

import sunra_client

try:
    response = sunra_client.subscribe(
        "black-forest-labs/flux-kontext-pro/text-to-image",
        arguments={
            "prompt": "a cute cat, realistic, orange",
            "seed": -2  # Invalid seed (should be >= 0)
        },
        with_logs=True,
        on_enqueue=print,
        on_queue_update=print
    )
    print(response["images"][0]["url"])
    
except sunra_client.SunraClientError as e:
    print(f"Error: {e}")
    
    # Access detailed error information
    print(f"Error Code: {e.code}")           # e.g., "invalid_input"
    print(f"Error Message: {e.message}")     # e.g., "Validation error: seed must be >= 0"
    print(f"Error Details: {e.details}")     # Additional error details
    print(f"Timestamp: {e.timestamp}")       # When the error occurred

Error Types

The client handles different types of errors:

Validation Errors (from model processing):

try:
    response = sunra_client.subscribe(
        "black-forest-labs/flux-kontext-pro/text-to-image",
        arguments={"prompt": "test", "seed": -1}  # Invalid seed
    )
except sunra_client.SunraClientError as e:
    # e.code: "invalid_input"
    # e.message: "Validation error: seed must be >= 0"
    pass

HTTP Errors (from API requests):

try:
    response = sunra_client.subscribe(
        "non-existent-model/endpoint",
        arguments={"prompt": "test"}
    )
except sunra_client.SunraClientError as e:
    # e.code: "Bad Request"
    # e.message: "Model endpoint is required"
    # e.timestamp: "2025-01-16T12:00:00.000Z"
    pass

Conditional Error Handling:

try:
    response = sunra_client.subscribe("model/endpoint", arguments={})
except sunra_client.SunraClientError as e:
    if e.code == "invalid_input":
        print("Please check your input parameters")
    elif e.code == "Bad Request":
        print("Invalid API request")
    else:
        print(f"Unexpected error: {e}")

Credits

This project is derived from:

• fal-ai/fal-js
• fal-ai/fal-java
• fal-ai/fal

and adapted to work with sunra.ai. The original projects are licensed under the MIT/Apache 2.0 License. We extend our gratitude to the original authors for their contributions.