PyFlowery/docs/getting-started/usage.md

Usage

This page contains a few examples of how to use the pyflowery package. This page does not cover installation, for that see the installation page.

Creating an API client

To create an API client, you need to first import the pyflowery.pyflowery.FloweryAPI class. Then, you can create an instance of the class by passing in a pyflowery.models.FloweryAPIConfig class.

from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config)

Okay, now we have a FloweryAPI class. Let's move on to the next example.

Retrieving a voice

So, whenever a FloweryAPI class is instantiated, it will automatically fetch a list of voices from the Flowery API, and cache it in the class. You can access this cache by calling the get_voices method with either a voice's ID or the name of a voice. If you want to get a list of all voices, you can call the get_voices method without any arguments.

# Set up the API client
from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config) # This will fetch all of the voices from the API and cache them automatically, you don't need to do that manually

voices = api.get_voices(name="Alexander")
print(voices) # (Voice(id='fa3ea565-121f-5efd-b4e9-59895c77df23', name='Alexander', gender='Male', source='TikTok', language=Language(name='English (United States)', code='en-US')),)
print(voices[0].id) # 'fa3ea565-121f-5efd-b4e9-59895c77df23'

Updating the API client's voice cache

In most use cases, it is not necessary to manually update the voice cache. But, for applications that run for an extended period of time, it may be necessary to manually update the voice cache. To do this, you can call the _populate_voices_cache() async method.

import asyncio # This is required to run asynchronous code outside of async functions
from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config) # This will fetch all of the voices from the API and cache them automatically, you don't need to do that manually

asyncio.run(api._populate_voices_cache()) # This will update the voice cache. This is what `FloweryAPI` calls automatically when it is instantiated

Retrieving a list of voices from the API directly

If necessary, you can call the fetch_voices() or fetch_voice() methods. These methods will fetch the voices from the API directly, skipping the cache. This isn't recommended, though, as it puts more strain on the Flowery API.

=== "fetch_voices()" fetch_voices() returns an AsyncContextManager, so you need to iterate through it when you call it.

```python
import asyncio
from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config)

async def fetch_voices():
    voices_list = []
    async for voice in api.fetch_voices():
        voices_list.append(voice)
    return voices_list

voices = asyncio.run(fetch_voices())
```

=== "fetch_voice()"

```python
import asyncio
from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config)

voice_id = "38f45366-68e8-5d39-b1ef-3fd4eeb61cdb"

voice = asyncio.run(api.fetch_voice(voice_id))
print(voice) # Voice(id='38f45366-68e8-5d39-b1ef-3fd4eeb61cdb', name='Jacob', gender='Male', source='Microsoft Azure', language=Language(name='English (United States)', code='en-US'))
```

Converting text to audio

Finally, let's convert some text into audio. To do this, you can call the fetch_tts() method. This will return the bytes of the audio file.

import asyncio
from pyflowery import FloweryAPI, FloweryAPIConfig
config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@gmail.com")
api = FloweryAPI(config)

voice = api.get_voices(name="Alexander")[0]

tts = asyncio.run(api.fetch_tts("Hello, world!", voice))
with open("hello_world.mp3", "wb") as f:
    f.write(tts)