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

# Python SDK

> Official Python client for the Rimp API. Sync first, async-friendly via httpx.

## Install

```bash theme={null}
pip install rimp
```

Python 3.9+ supported. Uses `httpx` under the hood.

## Initialize

```python theme={null}
from rimp import Client

client = Client(api_key=os.environ["RIMP_API_KEY"])
# base_url defaults to https://api.rimp.example
```

## Generations

### Image (sync)

```python theme={null}
gen = client.generations.create_image(
    model="flux-pro",
    prompt="a red rimp on chrome",
    aspect_ratio="1:1",
)
print(gen["outputs"][0]["url"])
```

### Video (async + wait\_for)

```python theme={null}
job = client.generations.create_video(
    model="veo-3-1-fast",
    prompt="waves at golden hour",
    duration_s=4,
)
final = client.generations.wait_for(job["id"], poll_interval_s=2.0, timeout_s=1800)
```

### Cancel

```python theme={null}
client.generations.cancel(job_id)
```

## Comparisons

```python theme={null}
cmp = client.comparisons.create(
    prompt="cinematic portrait",
    models=["flux-pro", "imagen-4"],
)
result = client.comparisons.wait_for(cmp["id"])
for g in result["generations"]:
    print(g["model"], g["outputs"][0]["url"])
```

## Models, uploads, webhooks, usage

```python theme={null}
models = client.models.list()
upload = client.uploads.create_presigned("image/png")
client.webhooks.create(url="https://...", events=["generation.completed"])
usage = client.usage.get(start="2026-05-01", end="2026-05-31", group_by="model")
```

## Error handling

```python theme={null}
from rimp import RimpApiError

try:
    client.generations.create_image(model="flux-pro", prompt="...")
except RimpApiError as err:
    print(err.status, err.code, err.message, err.request_id)
```

## Async clients (coming in 0.2)

```python theme={null}
# Not yet released. Track at https://github.com/rimp-labs/rimp-python/issues/3
```

For now, the sync client works with `asyncio` via `asyncio.to_thread`:

```python theme={null}
import asyncio

async def main():
    gen = await asyncio.to_thread(
        client.generations.create_image,
        model="flux-pro", prompt="..."
    )
```

## Custom httpx client

```python theme={null}
import httpx
from rimp import Client

http = httpx.Client(timeout=60.0, proxies="http://corp-proxy:8080")
client = Client(api_key=KEY, http_client=http)
```