> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Tags

Voice tags are free-form labels attached to each voice, useful for filtering, grouping, and discovery. Tags are best for vocal style, voice quality, and use-case descriptors.

<Note>
  Tags are **not** where gender, age group, or categories go. Those are separate structured fields with fixed enums (`gender`, `ageGroup`, `categories`) — set them via [UpdateVoice](/api-reference/voiceAPI/voiceservice/update-voice) after cloning. Putting `"female"` or `"adult"` in `tags` will not populate those fields.
</Note>

## Understanding voice tags

Each voice includes a `tags` array with free-form labels such as:

* **Vocal style**: `energetic`, `calm`, `professional`, `friendly`, `warm`
* **Voice quality**: `smooth`, `clear`, `expressive`, `conversational`
* **Use-case hints**: `narrator`, `announcer`, `character`

Structured metadata (set via [UpdateVoice](/api-reference/voiceAPI/voiceservice/update-voice), not `tags`):

* **`gender`**: `male`, `female`, `neutral`
* **`ageGroup`**: `young`, `middle_aged`, `elderly`
* **`categories`**: `companions`, `developer_assistants`, `education_training`, `enterprise`, `healthcare`, `interactive_media`

## Adding voice tags

You can add custom tags to a voice when cloning it in the [TTS Playground](https://platform.inworld.ai/tts-playground):

1. In the TTS Playground, click **Create a Voice** and select **Clone**.
2. Enter a name for your voice, then add tags — press Enter after each tag to add it to the list.
   <img src="https://mintcdn.com/inworldaidev/3rlRKo3pNdVqmyFj/img/tts/voice_tags.svg?fit=max&auto=format&n=3rlRKo3pNdVqmyFj&q=85&s=4b59031c2ed617077f2162b2bd33f7a4" alt="Voice tags" width="1200" height="1120" data-path="img/tts/voice_tags.svg" />
3. Upload or record your audio sample and complete the cloning flow. See [Voice Cloning](/tts/instant-voice-cloning) for the full walkthrough.
4. Your new voice will appear in your voice list with the assigned tags.
   <img src="https://mintcdn.com/inworldaidev/3rlRKo3pNdVqmyFj/img/tts/saved_voice_tags.svg?fit=max&auto=format&n=3rlRKo3pNdVqmyFj&q=85&s=613b29c7da3bfe7ad9af546c40a9eda9" alt="Saved voice tags" width="728" height="660" data-path="img/tts/saved_voice_tags.svg" />

## Using voice tags

Voice tags are returned in the [List voices in a workspace](/api-reference/voiceAPI/voiceservice/list-voices) endpoint response, so you can filter and select voices programmatically:

```json theme={"system"}
{
  "voices": [
    {
      "voiceId": "my_workspace__my_custom_voice",
      "displayName": "My Custom Voice",
      "description": "A warm narrator voice",
      "promptLanguages": ["en-US"],
      "tags": ["warm", "expressive", "narrator"],
      "gender": "female",
      "ageGroup": "young",
      "categories": ["companions"],
      "source": "IVC"
    }
  ],
  "totalSize": 1,
  "nextPageToken": ""
}
```