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

# Quickstart

> Generate your first AI voice with FineVoice in minutes

## Overview

This guide walks you through the complete FineVoice API workflow: from getting your API key to generating speech, converting voices, creating sound effects, and separating audio tracks. All audio processing tasks follow the same async pattern — submit a request, get a `task_id`, then poll for the result.

## Get your API Key

<AccordionGroup>
  <Accordion title="Create a FineVoice account" icon="user">
    1. Open [FineVoice](https://finevoice.ai/) and click **Sign up** in the top-right corner.
    2. Choose a sign-up method: Google, Apple, or Email.
    3. After logging in, navigate to the [User Center](https://finevoice.ai/usercenter).

    <Tip>
      Keep your API key secret. Never commit it to version control or expose it in client-side code.
    </Tip>
  </Accordion>

  <Accordion title="Generate your API key" icon="key">
    1. Go to [https://finevoice.ai/usercenter](https://finevoice.ai/usercenter)
    2. Navigate to **API Tokens**
    3. Click **Generate Secret Key** and copy the key

    Store it as an environment variable for all examples below:

    ```bash theme={null}
    export FINEVOICE_API_KEY="your_api_key_here"
    ```

    Windows Command Prompt:

    ```bat theme={null}
    set FINEVOICE_API_KEY=your_api_key_here
    ```
  </Accordion>
</AccordionGroup>

***

## Async Task Pattern

All audio processing endpoints work the same way:

<Steps>
  <Step title="Submit the request">
    Send a POST request with your audio task parameters. The API immediately returns a `task_id`.

    ```json theme={null}
    { "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    ```
  </Step>

  <Step title="Poll for the result">
    Use `GET /v1/task/{task_id}` to check status. Poll every 2–3 seconds until `status` is `completed`.

    ```json theme={null}
    {
      "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "url": "https://dlfile.fineshare.net/audio/a1b2c3d4.mp3",
      "error": null
    }
    ```

    | Status       | Meaning                                          |
    | ------------ | ------------------------------------------------ |
    | `pending`    | Task queued, not yet started                     |
    | `processing` | Task is being processed                          |
    | `completed`  | Task finished — `url` contains the download link |
    | `failed`     | Task failed — `error` contains the reason        |
  </Step>

  <Step title="Download the output">
    ```bash theme={null}
    curl -L -o output.mp3 "https://dlfile.fineshare.net/output/a1b2c3d4.mp3"
    ```
  </Step>
</Steps>

***

## 1. Text to Speech

Convert text into natural-sounding speech. Supports 1,500+ AI voices and emotion tags like `[happy]`, `[sad]`, `[breathe]`.

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Submit the TTS request">
        ```bash theme={null}
        curl -X POST https://apis.finevoice.ai/v1/audio/speech-synthesis \
          -H "Authorization: Bearer $FINEVOICE_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "voice": "james",
            "text": "[happy] Hi, welcome to FineVoice! [breathe] Let me show you what I can do."
          }'
        ```

        **Response:**

        ```json theme={null}
        { "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
        ```
      </Step>

      <Step title="Poll for result">
        ```bash theme={null}
        curl -X GET https://apis.finevoice.ai/v1/task/p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
          -H "Authorization: Bearer $FINEVOICE_API_KEY"
        ```

        **Response when completed:**

        ```json theme={null}
        {
          "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "status": "completed",
          "url": "https://dlfile.fineshare.net/output/a1b2c3d4.mp3",
          "error": null
        }
        ```
      </Step>

      <Step title="Download the audio">
        ```bash theme={null}
        curl -L -o tts_output.mp3 "https://dlfile.fineshare.net/output/a1b2c3d4.mp3"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    # 1. Submit TTS request
    res = requests.post(f"{BASE_URL}/v1/audio/speech-synthesis", headers=HEADERS,
                        json={"voice": "james",
                              "text": "[happy] Hi, welcome to FineVoice! [breathe] Let me show you what I can do."})
    task_id = res.json()["task_id"]
    print(f"Task submitted: {task_id}")

    # 2. Poll for result
    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        print(f"Status: {result['status']}")
        if result["status"] == "completed":
            print(f"Download URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(2)

    # 3. Download
    with open("tts_output.mp3", "wb") as f:
        f.write(requests.get(result["url"]).content)
    print("Saved to tts_output.mp3")
    ```
  </Tab>
</Tabs>

<Tip>
  Use the [List Voices API](https://api.finevoice.ai/api-reference/ai-voices/getvoices) to browse all available voice models and find the right `voice` name for your project.
</Tip>

***

## 2. Voice Conversion

Transform the voice in an existing audio file to a different AI voice while preserving the original content and timing.

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Submit the conversion request">
        ```bash theme={null}
        curl -X POST https://apis.finevoice.ai/v1/audio/voice-conversion \
          -H "Authorization: Bearer $FINEVOICE_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "voice": "madison",
            "sourceUrl": "https://dlaudio.fineshare.net/cover/speak/30f23d17-634d-420e-99e7-d24097dc669b.mp3",
            "outputFormat": "mp3",
            "useAsync": true
          }'
        ```

        **Response:**

        ```json theme={null}
        { "task_id": "p1-b2c3d4e5-f6a7-8901-bcde-f12345678901" }
        ```
      </Step>

      <Step title="Poll for result">
        ```bash theme={null}
        curl -X GET https://apis.finevoice.ai/v1/task/p1-b2c3d4e5-f6a7-8901-bcde-f12345678901 \
          -H "Authorization: Bearer $FINEVOICE_API_KEY"
        ```
      </Step>

      <Step title="Download converted audio">
        ```bash theme={null}
        curl -L -o converted.mp3 "https://dlfile.fineshare.net/output/b2c3d4e5.mp3"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/audio/voice-conversion", headers=HEADERS,
                        json={"voice": "madison",
                              "sourceUrl": "https://dlaudio.fineshare.net/cover/speak/30f23d17-634d-420e-99e7-d24097dc669b.mp3",
                              "outputFormat": "mp3",
                              "useAsync": True})
    task_id = res.json()["task_id"]

    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        if result["status"] == "completed":
            print(f"Download URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(2)

    with open("converted.mp3", "wb") as f:
        f.write(requests.get(result["url"]).content)
    ```
  </Tab>
</Tabs>

***

## 3. Sound Effect Generation

Generate royalty-free sound effects from a text description. Perfect for videos, games, and podcasts.

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Submit the SFX request">
        ```bash theme={null}
        curl -X POST https://apis.finevoice.ai/v1/audio/sfx-generation \
          -H "Authorization: Bearer $FINEVOICE_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "prompt": "Thunderstorm with heavy rain and distant thunder",
            "negative_prompt": "music, voices",
            "duration": 5.0,
            "useAsync": true
          }'
        ```

        **Response:**

        ```json theme={null}
        { "task_id": "p1-c3d4e5f6-a7b8-9012-cdef-123456789012" }
        ```
      </Step>

      <Step title="Poll and download">
        ```bash theme={null}
        curl -X GET https://apis.finevoice.ai/v1/task/p1-c3d4e5f6-a7b8-9012-cdef-123456789012 \
          -H "Authorization: Bearer $FINEVOICE_API_KEY"

        curl -L -o thunderstorm.mp3 "https://dlfile.fineshare.net/output/c3d4e5f6.mp3"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/audio/sfx-generation", headers=HEADERS,
                        json={"prompt": "Thunderstorm with heavy rain and distant thunder",
                              "negative_prompt": "music, voices",
                              "duration": 5.0,
                              "useAsync": True})
    task_id = res.json()["task_id"]

    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        if result["status"] == "completed":
            print(f"Download URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(2)

    with open("thunderstorm.mp3", "wb") as f:
        f.write(requests.get(result["url"]).content)
    ```
  </Tab>
</Tabs>

You can also generate effects directly from a video by providing `sourceUrl` and `sourceType`:

```json theme={null}
{
  "sourceUrl": "https://example.com/video/clip.mp4",
  "sourceType": "video",
  "duration": 10.0,
  "useAsync": true
}
```

***

## 4. Audio Separation

Separate vocals from background music in any audio file. Ideal for remixing, karaoke creation, or vocal extraction.

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Submit the separation request">
        ```bash theme={null}
        curl -X POST https://apis.finevoice.ai/v1/audio/separation \
          -H "Authorization: Bearer $FINEVOICE_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "sourceUrl": "https://webresources.fineshare.net/finevoice3/audio/isolator-original.mp3",
            "model": "vocal-remover",
            "useAsync": true
          }'
        ```

        **Response:**

        ```json theme={null}
        { "task_id": "p1-d4e5f6a7-b8c9-0123-defa-234567890123" }
        ```
      </Step>

      <Step title="Poll and download">
        ```bash theme={null}
        curl -X GET https://apis.finevoice.ai/v1/task/p1-d4e5f6a7-b8c9-0123-defa-234567890123 \
          -H "Authorization: Bearer $FINEVOICE_API_KEY"

        curl -L -o vocals.mp3 "https://dlfile.fineshare.net/output/d4e5f6a7.mp3"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/audio/separation", headers=HEADERS,
                        json={"sourceUrl": "https://webresources.fineshare.net/finevoice3/audio/isolator-original.mp3",
                              "model": "vocal-remover",
                              "useAsync": True})
    task_id = res.json()["task_id"]

    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        if result["status"] == "completed":
            print(f"Download URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(2)

    with open("vocals.mp3", "wb") as f:
        f.write(requests.get(result["url"]).content)
    ```
  </Tab>
</Tabs>

***

## 5. Speech to Text

Transcribe speech from an audio or video URL. Supports optional speaker diarization and word-level timestamps.

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Submit the STT request">
        ```bash theme={null}
        curl -X POST https://apis.finevoice.ai/v1/audio/stt \
          -H "Authorization: Bearer $FINEVOICE_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "url": "https://example.com/interview.mp3",
            "language": "en",
            "format": "json",
            "speaker_diarization": true,
            "max_speakers": 2,
            "useAsync": true
          }'
        ```

        **Response:**

        ```json theme={null}
        { "task_id": "p1-e5f6a7b8-c9d0-1234-efab-345678901234" }
        ```
      </Step>

      <Step title="Poll for result">
        ```bash theme={null}
        curl -X GET https://apis.finevoice.ai/v1/task/p1-e5f6a7b8-c9d0-1234-efab-345678901234 \
          -H "Authorization: Bearer $FINEVOICE_API_KEY"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/audio/stt", headers=HEADERS,
                        json={"url": "https://example.com/interview.mp3",
                              "language": "en",
                              "format": "json",
                              "speaker_diarization": True,
                              "max_speakers": 2,
                              "useAsync": True})
    task_id = res.json()["task_id"]

    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        if result["status"] == "completed":
            print(f"Transcript URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(2)
    ```
  </Tab>
</Tabs>

***

## 6. Voice Cloning

Train a custom AI voice model from a short audio recording. Once trained, the voice name can be used in any TTS or Voice Conversion request.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/voice/train \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My Custom Voice",
        "languageCode": "en-US",
        "gender": "female",
        "audioUrl": "https://example.com/my_voice_sample.wav"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/voice/train", headers=HEADERS,
                        json={"name": "My Custom Voice",
                              "languageCode": "en-US",
                              "gender": "female",
                              "audioUrl": "https://example.com/my_voice_sample.wav"})
    print(res.json())
    ```
  </Tab>
</Tabs>

<Tip>
  For best results, use a clean 30–120 second recording with no background noise. After training completes, use the voice `name` you provided in any TTS or Voice Conversion request.
</Tip>

***

## 7. Music Generation

### By Prompt

Generate a music track from a text description.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/music/musicgenbyprompt \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "Upbeat electronic dance music with heavy bass and synth leads",
        "instrumental": true,
        "duration": 30
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/music/musicgenbyprompt", headers=HEADERS,
                        json={"prompt": "Upbeat electronic dance music with heavy bass and synth leads",
                              "instrumental": True,
                              "duration": 30})
    print(res.json())
    ```
  </Tab>
</Tabs>

### With Lyrics

Generate a full song with vocals using your own lyrics and style description.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/music/musicgen \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Morning Light",
        "style": "pop, warm, acoustic guitar",
        "lyrics": "[Verse 1]\nWake up to the morning light\nEverything is gonna be alright",
        "instrumental": false,
        "modelVersion": "v3"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/music/musicgen", headers=HEADERS,
                        json={"title": "Morning Light",
                              "style": "pop, warm, acoustic guitar",
                              "lyrics": "[Verse 1]\nWake up to the morning light\nEverything is gonna be alright",
                              "instrumental": False,
                              "modelVersion": "v3"})
    print(res.json())
    ```
  </Tab>
</Tabs>

### Music Cover

Replace the vocals of an existing song with an AI voice.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/music/cover \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "voice": "james",
        "sourceUrl": "https://example.com/original_song.mp3",
        "engine": "v5",
        "pitch": 0,
        "outputFormat": "mp3"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/music/cover", headers=HEADERS,
                        json={"voice": "james",
                              "sourceUrl": "https://example.com/original_song.mp3",
                              "engine": "v5",
                              "pitch": 0,
                              "outputFormat": "mp3"})
    print(res.json())
    ```
  </Tab>
</Tabs>

***

## 8. Audio Enhancement

### Quick Enhancement

Reduce background noise from a single audio file.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/enhancer/speech_enhancement \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com/noisy_recording.mp3",
        "model": "MossFormer2_SE_48K",
        "output_format": "mp3"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/enhancer/speech_enhancement", headers=HEADERS,
                        json={"url": "https://example.com/noisy_recording.mp3",
                              "model": "MossFormer2_SE_48K",
                              "output_format": "mp3"})
    print(res.json())
    ```
  </Tab>
</Tabs>

### All-in-One Pipeline

Run multiple enhancement steps in a single request — noise reduction, filler word removal, silence trimming, and loudness normalization.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/enhancer/process/pipeline \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com/podcast_raw.mp3",
        "step_speech_enhancement": true,
        "step_remove_long_silences": true,
        "step_filler_words_remove": true,
        "step_audio_normalization": true,
        "filler_use_whisper": true,
        "filler_language": "en",
        "norm_method": "peak",
        "output_format": "mp3"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/enhancer/process/pipeline", headers=HEADERS,
                        json={"url": "https://example.com/podcast_raw.mp3",
                              "step_speech_enhancement": True,
                              "step_remove_long_silences": True,
                              "step_filler_words_remove": True,
                              "step_audio_normalization": True,
                              "filler_use_whisper": True,
                              "filler_language": "en",
                              "norm_method": "peak",
                              "output_format": "mp3"})
    # Returns a download URL directly
    print(res.json())
    ```
  </Tab>
</Tabs>

<Tip>
  The Pipeline processes steps in a fixed order: Speech Enhancement → Remove Mouth Sounds → Remove Long Silences → Super Resolution → Filler Words Removal → Stuttering Removal → Audio Normalization. Enable only the steps you need.
</Tip>

***

## 9. Podcast Generation

### Podcast Generation

Generate a multi-speaker AI podcast from a prompt or script.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://apis.finevoice.ai/v1/audio/podcastgen \
      -H "Authorization: Bearer $FINEVOICE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "A friendly 3-minute discussion about the future of AI voice technology",
        "speakers": ["olivia", "ethan"],
        "style": "conversational",
        "expectedDuration": "3min",
        "useAsync": true
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests, time

    API_KEY = "your_api_key_here"
    BASE_URL = "https://apis.finevoice.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    res = requests.post(f"{BASE_URL}/v1/audio/podcastgen", headers=HEADERS,
                        json={"prompt": "A friendly 3-minute discussion about the future of AI voice technology",
                              "speakers": ["olivia", "ethan"],
                              "style": "conversational",
                              "expectedDuration": "3min",
                              "useAsync": True})
    task_id = res.json()["task_id"]

    while True:
        result = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
        if result["status"] == "completed":
            print(f"Download URL: {result['url']}")
            break
        elif result["status"] == "failed":
            print(f"Error: {result['error']}")
            break
        time.sleep(3)
    ```
  </Tab>
</Tabs>

***

## Support

Need help? Check out these resources:

* [**API Reference**](https://api.finevoice.ai/api-reference/introduction) — Complete API documentation
* [**Discord Community**](https://discord.com/invite/HquSyU4Dy8) — Get help from the community
* [**Support Email**](mailto:support@finevoice.ai) — Contact our support team