Metadata-Version: 2.4
Name: gradium
Version: 0.5.9
Summary: Python client for Gradium API
Project-URL: Homepage, https://gradium.ai
Project-URL: Repository, https://github.com/gradium/gradium-py
Project-URL: Bug Tracker, https://github.com/gradium/gradium-py/issues
Project-URL: Documentation, https://docs.gradium.ai
Author-email: Gradium AI <contact@gradium.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,gradium,streaming,stt,tts,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: cli
Requires-Dist: sphn; extra == 'cli'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Gradium Python Client

Python client library for the [Gradium Voice AI API](https://gradium.ai).

## Examples

See the [examples/](examples/) directory for usage examples:

- Text-to-Speech Streaming: `examples/tts_streaming.py`
- Speech-to-Text Streaming: `examples/stt_streaming.py`

You can also try it out in Google Colab.

- EU Server <a target="_blank" href="https://colab.research.google.com/github/gradium-ai/gradium-py/blob/main/notebooks/gradium_example_eu.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
- US server <a target="_blank" href="https://colab.research.google.com/github/gradium-ai/gradium-py/blob/main/notebooks/gradium_example_us.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>


## Command Line Interface

The package includes a CLI that can be run via `uvx gradium`:

```bash
# Text-to-speech
uvx gradium tts "Hello world" -o output.wav
uvx gradium tts "Hello world" --voice-id abc123 -o output.ogg

# Speech-to-text
uvx gradium stt audio.wav
uvx gradium stt audio.wav --json  # outputs JSON with timestamps

# To handle non-wav file, additional dependencies are required
uvx --from 'gradium[cli]' gradium stt audio.mp3
```

Run `uvx gradium --help` for all available options.

## Text-to-Speech Streaming Example

You can find some examples in the `examples/` directory. Try them out with
[uv](https://docs.astral.sh/uv/getting-started/installation/). For
the text-to-speech streaming example, run:

```bash
uv run --with sphn examples/tts_streaming.py \
    --text "Hello, this is a test of the Gradium TTS streaming API." \
    --api-key gsk_...
```

## Speech-to-Text Streaming Example

You can also try the speech-to-text streaming example:

```bash
uv run --with sphn examples/stt_streaming.py \
    --audio test_file.mp3 \
    --api-key gsk_...
```
