# 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](installation.md) 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. ```python from pyflowery import FloweryAPI, FloweryAPIConfig config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@foobar.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. ```python # Set up the API client from pyflowery import FloweryAPI, FloweryAPIConfig config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@foobar.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. ```python 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@foobar.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@foobar.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@foobar.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. ```python import asyncio from pyflowery import FloweryAPI, FloweryAPIConfig config = FloweryAPIConfig(user_agent="PyFlowery Documentation Example/example@foobar.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) ```