# RunBlob Python SDK

Official async Python SDK for the [RunBlob](https://runblob.com) AI generation platform.

Currently supported: **Nano Banana (Gemini)** image generation, **Kling** video and image generation (12+ models including O1, O3, Motion Control), **Veo 3** video generation (Fast, Quality, up to 4K), **ChatGPT** image generation and editing. More models coming in future updates.

For pricing, available models and API documentation visit [runblob.com](https://runblob.com).

## Install

```bash
pip install runblob
```

## Configuration

```python
from runblob import RunBlob

client = RunBlob(
    api_key="sk-...",
    max_connections=200,
    rate_limit_rps=100.0,
    max_retries=5,
    timeout=60.0,
    circuit_breaker_threshold=10,
)
```

## Nano Banana (Gemini) — Image Generation

```python
import asyncio
from runblob import RunBlob

async def main():
    async with RunBlob(api_key="sk-...") as client:
        result = await client.nanobanana.generate_and_wait(
            prompt="A cute orange cat on a windowsill",
            model="pro",
            quality="4k",
        )
        print(result.result_image_url)

asyncio.run(main())
```

## Kling — Video Generation

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.kling.generate_and_wait(
        prompt="A cinematic sunset over the ocean",
        model="kling_2.5_turbo",
        duration="10",
        aspect_ratio="16:9",
    )
    print(result.video_url)
```

## Kling — O3 Video (up to 15s)

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.kling.generate_o3_video_and_wait(
        prompt="A dog running through a field of flowers",
        model="kling_o3_pro",
        duration="15",
    )
    print(result.video_url)
```

## Kling — O3 Photo (up to 4K)

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.kling.generate_o3_photo_and_wait(
        prompt="A portrait in studio lighting",
        img_resolution="4k",
        aspect_ratio="3:4",
    )
    print(result.image_url)
```

## Kling — Image-to-Video

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.kling.generate_and_wait(
        prompt="Make this photo come alive",
        model="kling_2.1",
        image_url="https://example.com/photo.jpg",
    )
    print(result.video_url)
```

## Veo 3 — Fast Video

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.veo.generate_and_wait(
        prompt="A cinematic drone shot flying over a mountain lake at sunrise",
        model="veo_3_fast",
        aspect_ratio="16:9",
    )
    print(result.video_url)
```

## Veo 3 — Quality 4K

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.veo.generate_and_wait(
        prompt="Slow motion shot of rain drops falling on autumn leaves",
        model="veo_3_quality_4k",
        aspect_ratio="16:9",
    )
    print(result.video_url)
```

## Veo 3 — Image-to-Video

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.veo.generate_and_wait(
        prompt="Make this photo come alive with gentle camera movement",
        model="veo_3_fast",
        bytes_image="base64_encoded_image_here",
    )
    print(result.video_url)
```

## ChatGPT — Image Generation

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.chatgpt.generate_and_wait(
        prompt="A cute cat illustration in watercolor style",
        aspect_ratio="1:1",
    )
    print(result.result_image_url)
```

## ChatGPT — Image Editing

```python
async with RunBlob(api_key="sk-...") as client:
    result = await client.chatgpt.generate_and_wait(
        prompt="Remove the background and add a sunset",
        images=["https://example.com/photo.jpg"],
        aspect_ratio="4:3",
    )
    print(result.result_image_url)
```

## Batch generation

```python
async with RunBlob(api_key="sk-...") as client:
    results = await client.nanobanana.generate_batch_and_wait(
        prompts=[
            "A red apple on a white table",
            "A mountain peak covered in snow",
            "An anime girl with blue hair",
        ],
        model="standard",
        concurrency=5,
    )
    for r in results:
        print(r.result_image_url)
```

## Webhooks

```python
async with RunBlob(api_key="sk-...") as client:
    await client.kling.generate(
        prompt="A forest at dawn",
        callback_url="https://your-server.com/webhook",
    )
```

```python
from runblob import parse_webhook_payload

event = parse_webhook_payload(request_body)
if event.is_completed:
    print(event.result_image_url)
```

## Error handling

```python
from runblob import RunBlob, AuthenticationError, RateLimitError, RunBlobError

async with RunBlob(api_key="sk-...") as client:
    try:
        result = await client.kling.generate(prompt="test")
    except AuthenticationError:
        print("Invalid API key")
    except RateLimitError as e:
        print(f"Rate limited, retry after {e.retry_after}s")
    except RunBlobError as e:
        print(f"SDK error: {e}")
```

## Requirements

- Python 3.10+
- [runblob.com](https://runblob.com) API key
