infinity-ml 0.2.2
Python client for Infinity Media Server - GPU-accelerated image, video, and audio generation
Requires Python: >=3.10
Keywords: ai, gpu, image-generation, video-generation, text-to-speech, flux, diffusion, infinity-ml

# infinity_ml

Python client for Infinity Media Server - GPU-accelerated image, video, and audio generation.

Designed to mirror the [fal_client](https://docs.fal.ai/api-reference) API for familiarity.

## Installation

```bash
pip install infinity_ml
```

## Quick Start

### Module-level Functions (fal_client style)

```python
from infinity_ml import run, submit, subscribe, status

# Simple blocking call
result = run("black-forest-labs/flux-dev", {"prompt": "A cat astronaut in space"})
print(result["images"][0]["download_url"])

# Submit and poll manually
handle = submit("black-forest-labs/flux-dev", {"prompt": "A cat"})
print(f"Submitted: {handle.request_id}")

# Wait with progress updates
for event in handle.iter_events():
    print(f"Status: {event}")
    
result = handle.get()

# Subscribe with callbacks
def on_update(status):
    print(f"Progress: {status}")

result = subscribe(
    "black-forest-labs/flux-dev",
    {"prompt": "A beautiful sunset"},
    on_queue_update=on_update,
)
```

### Client Class Usage

```python
from infinity_ml import InfinitySyncClient, InfinityAsyncClient

# Sync client
client = InfinitySyncClient()

# Run and wait
result = client.run("black-forest-labs/flux-dev", {"prompt": "A cat"})

# Convenience methods with typed results
image_result = client.image("A futuristic city")
print(image_result.images[0].download_url)

video_result = client.video("Ocean waves at sunset", num_frames=16)
print(video_result.video.download_url)

audio_result = client.audio("Hello from Infinity!")
print(audio_result.audio.download_url)

# Download file
client.download(audio_result.audio.download_url, "output.wav")
```

### Async Usage

```python
import asyncio
from infinity_ml import InfinityAsyncClient, run_async, submit_async

async def main():
    # Module-level async functions
    result = await run_async("black-forest-labs/flux-dev", {"prompt": "A cat"})
    
    # Or use InfinityAsyncClient
    async with InfinityAsyncClient() as client:
        handle = await client.submit("black-forest-labs/flux-dev", {"prompt": "A cat"})
        result = await handle.get()

asyncio.run(main())
```

## API Reference

### Module-level Functions

| Function | Description |
|----------|-------------|
| `run(app, args)` | Submit and wait for result (blocking) |
| `submit(app, args)` | Submit job, returns `SyncRequestHandle` |
| `subscribe(app, args, ...)` | Submit with status callbacks |
| `status(app, request_id)` | Get job status |
| `result(app, request_id)` | Get job result |
| `cancel(app, request_id)` | Cancel job (if supported) |

Async versions: `run_async`, `submit_async`, `subscribe_async`, `status_async`, `result_async`, `cancel_async`

### InfinitySyncClient / InfinityAsyncClient

```python
client = InfinitySyncClient(
    base_url="https://api.infinity.inc",  # Or use INFINITY_SERVER_URL env var
    default_timeout=300.0,                 # Max wait time (seconds)
)
```

#### Methods

| Method | Description |
|--------|-------------|
| `run(app, args)` | Submit and wait for result |
| `submit(app, args)` | Submit job, returns handle |
| `subscribe(app, args, ...)` | Submit with callbacks |
| `status(app, request_id)` | Get job status |
| `result(app, request_id)` | Get job result |
| `get_handle(app, request_id)` | Get handle for existing job |
| `health()` | Server health check |
| `ready()` | Server readiness & GPU status |

#### Convenience Methods (typed results)

| Method | Description |
|--------|-------------|
| `image(prompt, ...)` | Generate image, returns `ImageResult` |
| `video(prompt, ...)` | Generate video, returns `VideoResult` |
| `audio(text, ...)` | Generate audio, returns `AudioResult` |
| `download(url, path)` | Download generated file |

### Request Handles

Returned by `submit()`, provides methods to track job progress:

```python
handle = submit("black-forest-labs/flux-dev", {"prompt": "A cat"})

handle.request_id           # Job ID string
handle.status()             # Returns Status (Queued, InProgress, Completed, Failed)
handle.get()                # Wait and return result (blocking)
handle.iter_events()        # Iterate status updates until complete
handle.cancel()             # Cancel job (if supported)
```

### Status Types

```python
from infinity_ml import Queued, InProgress, Completed, Failed

status = handle.status()

if isinstance(status, Queued):
    print(f"Queue position: {status.position}")
elif isinstance(status, InProgress):
    print("Processing...")
elif isinstance(status, Completed):
    print("Done!")
elif isinstance(status, Failed):
    print(f"Error: {status.error}")
```

## Available Models

### LLM Models (OpenAI-compatible)

Use with the standard OpenAI SDK pointing to `https://api.infinity.inc/v1`:

| Model ID | Parameters | Context |
|----------|------------|---------|
| `QuantTrio/DeepSeek-V3.2-AWQ` | 671B MoE | 32K |
| `glm-4.7-fp8` | 358B | 65K |
| `nvidia/Kimi-K2-Thinking-NVFP4` | MoE | 65K |
| `openai/gpt-oss-120b` | 120B | 65K |

### Media Models

| Model ID | Type | Example |
|----------|------|---------|
| `black-forest-labs/flux-dev` | Image | `{"prompt": "A cat"}` |
| `wan-ai/wan2.2-t2v` | Video (2.2) | `{"prompt": "Waves", "guidance_scale": 4.0, "guidance_scale_2": 3.0}` |
| `wan-ai/wan2.1-1.3b` | Video (2.1) | `{"prompt": "Waves", "num_frames": 33}` |
| `wan-ai/wan2.1-14b` | Video (2.1) | `{"prompt": "Waves", "num_frames": 33}` |
| `boson-ai/higgs-audio-v2` | Audio | `{"text": "Hello!"}` |