Metadata-Version: 2.4
Name: aiutils-sdk
Version: 0.1.0
Summary: Python SDK for the AiUtils Developer API — 100+ AI models via one unified API
Author-email: AiUtils Team <dev@aiutils.io>
License: MIT
Keywords: ai,llm,openai,anthropic,generation,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0

# AiUtils Python SDK

Official Python SDK for the [AiUtils Developer API](https://developer.aiutils.io) — access 100+ AI models (LLM, image, video, audio, 3D) through one unified API.

## Install

```bash
pip install aiutils-sdk
```

## Quick Start

```python
from aiutils_sdk import AiUtils

client = AiUtils(api_key="ak-dev-YOUR_KEY")

# Chat completion (OpenAI-compatible)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing in one sentence."}],
)
print(response.choices[0].message.content)

# Image generation
image = client.images.generate.generate(
    model="fal:fal-ai/flux/dev",
    prompt="A futuristic city at sunset, cyberpunk style",
)
print(image.data[0].url)

# Video generation (async with auto-polling)
video = client.generations.create(
    model="fal:fal-ai/kling-video/v1.6/pro/image-to-video",
    parameters={"prompt": "Camera orbits a mountain lake", "image_url": "..."},
    wait_for_completion=True,
    timeout=300,
)
print(video.download_urls)

# Embeddings
embeddings = client.embeddings.create.create(
    model="text-embedding-3-small",
    input="Hello world",
)
print(len(embeddings.data[0].embedding))

# Browse model catalog
models = client.models.list(category="image", vendor="fal")
for m in models.data:
    print(f"{m.id} — {m.label}")
```

## API Reference

### `AiUtils(api_key, base_url=..., timeout=60.0)`

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | `str` | required | Your developer API key (`ak-dev-...`) |
| `base_url` | `str` | `https://developer-api.aiutils.io` | API base URL |
| `timeout` | `float` | `60.0` | Request timeout in seconds |

### Resources

- `client.chat.completions.create(...)` — OpenAI-compatible chat completions
- `client.images.generate.generate(...)` — Image generation
- `client.embeddings.create.create(...)` — Text embeddings
- `client.generations.create(...)` — Universal generation (image/video/audio/3D)
- `client.generations.get(id)` — Poll generation status
- `client.models.list(...)` — Browse model catalog
- `client.models.get(id)` — Get model details + schemas

### Error Handling

```python
from aiutils_sdk import AiUtils, AuthenticationError, InsufficientDTError, RateLimitError

try:
    response = client.chat.completions.create(...)
except AuthenticationError:
    print("Bad API key")
except InsufficientDTError:
    print("Top up your DT balance")
except RateLimitError:
    print("Slow down")
```

### Context Manager

```python
with AiUtils(api_key="ak-dev-YOUR_KEY") as client:
    response = client.chat.completions.create(...)
```

## Billing

All usage is billed in DT (Developer Tokens). `1 DT = $0.001 USD`. Cost = provider cost + 8% platform fee.

## Links

- [Developer Console](https://developer.aiutils.io)
- [API Documentation](https://developer.aiutils.io/docs)
- [Get API Key](https://developer.aiutils.io/api-keys)
