Metadata-Version: 2.4
Name: aigateway-py
Version: 0.1.2
Summary: Official Python SDK for AIgateway — async jobs, sub-accounts, evals, replays, webhook verification. Install as aigateway-py; import as aigateway.
Project-URL: Homepage, https://aigateway.sh
Project-URL: Documentation, https://aigateway.sh/docs
Project-URL: Examples, https://github.com/Rakesh1002/ai-gateway-examples
Project-URL: Issues, https://aigateway.sh/support
Author: AIgateway
License: MIT License
        
        Copyright (c) 2026 AIgateway
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,aigateway,llm,mcp,openai-compatible,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Requires-Dist: typing-extensions>=4.7
Provides-Extra: dev
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# aigateway-py (Python)

Official Python SDK for [AIgateway](https://aigateway.sh) — one OpenAI-compatible API for every frontier and open-weight model, every modality.

> Distribution name on PyPI is **`aigateway-py`** (the bare `aigateway` name was unavailable). The import path is still `aigateway`.

For **chat, embeddings, images, STT, TTS, moderation** — just use the `openai` package with `base_url='https://api.aigateway.sh/v1'`. AIgateway is drop-in.

This SDK covers the aggregator-native surface OpenAI doesn't model:

- **Async jobs** — text-to-video, music, 3D with a typed `jobs.wait(id)` helper
- **Sub-accounts** — one scoped key per end customer with spend caps
- **Evals** — pick the winning model from a candidate set; alias as `eval:<run_id>`
- **Replays** — re-run any past request on a new model and diff the output
- **Signed file URLs** — share job results without handing out the gateway key
- **Webhook signature verification** — HMAC-SHA256 with `verify_webhook()`

## Install

```sh
pip install aigateway-py
```

You still `import aigateway` in code — the PyPI distribution name and the import name are intentionally different.

Requires Python 3.9+.

## Quickstart

```python
import os
from aigateway import AIgateway

client = AIgateway(api_key=os.environ["AIGATEWAY_API_KEY"])

# 1. Submit a video job with a webhook.
job = client.jobs.create_video(
    prompt="a sunset over mountains, cinematic",
    model="runwayml/gen-4",
    duration=5,
    webhook_url="https://yourapp.com/hooks/aigateway",
)

# 2. Or poll until it's done:
done = client.jobs.wait(job.id, timeout_seconds=600)
print(done.result_url)

# 3. Mint a shareable signed URL:
signed = client.files.signed_url(job.id, "video.mp4", expires_in=3600)
print(signed["url"])
```

## Async

```python
import asyncio
from aigateway import AsyncAIgateway

async def main():
    async with AsyncAIgateway(api_key="sk-aig-...") as client:
        job = await client.jobs.create_video(prompt="a cat")
        result = await client.jobs.wait(job.id)
        print(result.result_url)

asyncio.run(main())
```

## Webhook verification

```python
from aigateway import verify_webhook
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["AIGATEWAY_WEBHOOK_SECRET"]

@app.post("/hooks/aigateway")
async def hook(request: Request):
    raw = await request.body()
    sig = request.headers.get("x-gateway-signature", "")
    if not verify_webhook(SECRET, raw, sig):
        raise HTTPException(status_code=401)
    # ... handle the payload
```

Fetch your webhook secret with `client.webhook_secret.get()` or rotate it with `client.webhook_secret.rotate()`.

## Examples + bug reports

Working examples: [github.com/Rakesh1002/ai-gateway-examples](https://github.com/Rakesh1002/ai-gateway-examples). Bug reports + feature requests: **support@aigateway.sh** · X: [@buildwithrakesh](https://x.com/buildwithrakesh) · LinkedIn: [in/rakeshroushan1002](https://www.linkedin.com/in/rakeshroushan1002).

## License

MIT © AIgateway
