Metadata-Version: 2.5
Name: dhivehigpt-sdk
Version: 1.1.0
Summary: Python SDK for the DhivehiGPT API
Project-URL: Homepage, https://dhivehigpt.com
Project-URL: Documentation, https://docs.javaabu.com/docs/dhivehigpt-sdk-python
Project-URL: Repository, https://github.com/Javaabu/dhivehigpt-sdk-python
Project-URL: Issues, https://github.com/Javaabu/dhivehigpt-sdk-python/issues
Project-URL: Changelog, https://github.com/Javaabu/dhivehigpt-sdk-python/blob/main/CHANGELOG.md
Author-email: "Javaabu Pvt. Ltd." <info@javaabu.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,dhivehi,dhivehigpt,sdk,tts
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

# DhivehiGPT SDK for Python

[![Latest Version on PyPI](https://img.shields.io/pypi/v/dhivehigpt-sdk.svg?style=flat-square)](https://pypi.org/project/dhivehigpt-sdk/)
[![Test Status](https://github.com/Javaabu/dhivehigpt-sdk-python/actions/workflows/run-tests.yml/badge.svg)](https://github.com/Javaabu/dhivehigpt-sdk-python/actions/workflows/run-tests.yml)
![Code Coverage Badge](https://raw.githubusercontent.com/Javaabu/dhivehigpt-sdk-python/main/.github/coverage.svg)
[![Total Downloads](https://img.shields.io/pypi/dm/dhivehigpt-sdk.svg?style=flat-square)](https://pypi.org/project/dhivehigpt-sdk/)

A lightweight, zero-dependency Python SDK for the [DhivehiGPT API](https://dhivehigpt.com/docs).

## Requirements

- Python 3.8 or higher
- No runtime dependencies — the SDK only uses the Python standard library.

## Installation

```bash
pip install dhivehigpt-sdk
```

## Getting an API key

API keys are generated from your DhivehiGPT team's [API Keys](https://dhivehigpt.com/team/api-keys) page. You'll need:

- A DhivehiGPT team account with an **active subscription**.
- To be a **team owner** or **team admin** — only owners and admins can generate API keys.

## Quick start

The client reads the API key from the `DHIVEHIGPT_API_KEY` environment variable by default:

```bash
export DHIVEHIGPT_API_KEY="your-api-key"
```

```python
from dhivehigpt_sdk import DhivehiGPT

client = DhivehiGPT()

# or pass the API key explicitly
client = DhivehiGPT(api_key="your-api-key")
```

`base_url` and `api_version` are optional and default to `https://api.dhivehigpt.com` and `v1`:

```python
client = DhivehiGPT(
    api_key="your-api-key",
    base_url="https://api.dhivehigpt.com",
    api_version="v1",
)
```

## Usage

### Voices

```python
voices = client.voices.list(gender="female", is_premium=False)
voice = client.voices.get("hajja")
```

### Text-to-Speech (TTS)

```python
audio = client.tts.generate(text="ދިވެހިޖީޕީޓީއަށް މަރުޙަބާ", voice="hajja")

audios = client.tts.list(voice="hajja", per_page=20)
one = client.tts.get(audio["data"]["uuid"])
client.tts.update(audio["data"]["uuid"], title="Welcome message")
client.tts.delete(audio["data"]["uuid"])
```

### Balance

```python
balance = client.balance.get()
print(balance["billing_period"]["balance"])
```

### Tasks

```python
tasks = client.tasks.list(platform="tts")
task = client.tasks.get("audio_generation")
cost = client.tasks.calculate(task="audio_generation", units=1000)
```

## Error handling

All errors raised by the SDK inherit from `dhivehigpt_sdk.DhivehiGPTError`:

```python
from dhivehigpt_sdk import DhivehiGPT, DhivehiGPTError, NotFoundError

client = DhivehiGPT()

try:
    client.voices.get("does-not-exist")
except NotFoundError as e:
    print(e.status_code, e.message)
except DhivehiGPTError as e:
    print("Something else went wrong:", e)
```

| Exception               | Cause                                              |
|--------------------------|-----------------------------------------------------|
| `AuthenticationError`    | Missing, invalid, or revoked API key (401)          |
| `PermissionDeniedError`  | Not enough credits, etc. (403)                      |
| `NotFoundError`          | Resource does not exist (404)                       |
| `ValidationError`        | Invalid request data (422); see `error.errors`      |
| `RateLimitError`         | Exceeded 60 requests/minute per API key (429)       |
| `ServerError`            | Upstream error (5xx)                                |
| `APIConnectionError`     | Could not reach the API                             |

## Documentation

Full documentation is available at [https://docs.javaabu.com/docs/dhivehigpt-sdk-python](https://docs.javaabu.com/docs/dhivehigpt-sdk-python).

The full DhivehiGPT API reference is available at [https://dhivehigpt.com/docs](https://dhivehigpt.com/docs).

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions? Feel free to create an [issue](https://github.com/Javaabu/dhivehigpt-sdk-python/issues) on GitHub, we'll try to address it as soon as possible.

If you've found a bug regarding security please mail [info@javaabu.com](mailto:info@javaabu.com) instead of using the issue tracker.

## Testing

```bash
pip install -e ".[test]"
pytest
```

## Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

## Security

If you discover any security related issues, please email [info@javaabu.com](mailto:info@javaabu.com) instead of using the issue tracker.


## Credits

- [Javaabu Pvt. Ltd.](https://github.com/javaabu)
- [All Contributors](https://github.com/Javaabu/dhivehigpt-sdk-python/contributors)

## License

The MIT License (MIT). Please see [License File](LICENSE) for more information.
