Quickstart

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

Create a FineVoice account

Open FineVoice and click Sign up in the top-right corner.
Choose a sign-up method: Google, Apple, or Email.
After logging in, navigate to the User Center.

Keep your API key secret. Never commit it to version control or expose it in client-side code.

Generate your API key

Go to https://finevoice.ai/usercenter
Navigate to API Tokens
Click Generate Secret Key and copy the key

Store it as an environment variable for all examples below:

export FINEVOICE_API_KEY="your_api_key_here"

Windows Command Prompt:

set FINEVOICE_API_KEY=your_api_key_here

Async Task Pattern

All audio processing endpoints work the same way:

Submit the request

Send a POST request with your audio task parameters. The API immediately returns a task_id.

{ "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890" }

Poll for the result

Use GET /v1/task/{task_id} to check status. Poll every 2–3 seconds until status is completed.

{
  "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

Download the output

curl -L -o output.mp3 "https://dlfile.fineshare.net/output/a1b2c3d4.mp3"

1. Text to Speech

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

cURL
Python

Submit the TTS request

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:

{ "task_id": "p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890" }

Poll for result

curl -X GET https://apis.finevoice.ai/v1/task/p1-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $FINEVOICE_API_KEY"

Response when completed:

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

Download the audio

curl -L -o tts_output.mp3 "https://dlfile.fineshare.net/output/a1b2c3d4.mp3"

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")

Use the List Voices API to browse all available voice models and find the right voice name for your project.

2. Voice Conversion

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

cURL
Python

Submit the conversion request

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:

{ "task_id": "p1-b2c3d4e5-f6a7-8901-bcde-f12345678901" }

Poll for result

curl -X GET https://apis.finevoice.ai/v1/task/p1-b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer $FINEVOICE_API_KEY"

Download converted audio

curl -L -o converted.mp3 "https://dlfile.fineshare.net/output/b2c3d4e5.mp3"

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)

3. Sound Effect Generation

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

cURL
Python

Submit the SFX request

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:

{ "task_id": "p1-c3d4e5f6-a7b8-9012-cdef-123456789012" }

Poll and download

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"

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)

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

{
  "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.

cURL
Python

Submit the separation request

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:

{ "task_id": "p1-d4e5f6a7-b8c9-0123-defa-234567890123" }

Poll and download

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"

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)

5. Speech to Text

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

cURL
Python

Submit the STT request

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:

{ "task_id": "p1-e5f6a7b8-c9d0-1234-efab-345678901234" }

Poll for result

curl -X GET https://apis.finevoice.ai/v1/task/p1-e5f6a7b8-c9d0-1234-efab-345678901234 \
  -H "Authorization: Bearer $FINEVOICE_API_KEY"

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)

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.

cURL
Python

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"
  }'

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())

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.

7. Music Generation

By Prompt

Generate a music track from a text description.

cURL
Python

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
  }'

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())

With Lyrics

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

cURL
Python

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"
  }'

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())

Music Cover

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

cURL
Python

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"
  }'

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())

8. Audio Enhancement

Quick Enhancement

Reduce background noise from a single audio file.

cURL
Python

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"
  }'

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())

All-in-One Pipeline

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

cURL
Python

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"
  }'

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())

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.

9. Podcast Generation

Podcast Generation

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

cURL
Python

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
  }'

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)

Support

Need help? Check out these resources:

API Reference — Complete API documentation
Discord Community — Get help from the community
Support Email — Contact our support team

Getting started

Pricing

Resources

Overview

Get your API Key

Async Task Pattern

1. Text to Speech

2. Voice Conversion

3. Sound Effect Generation

4. Audio Separation

5. Speech to Text

6. Voice Cloning

7. Music Generation

By Prompt

With Lyrics

Music Cover

8. Audio Enhancement

Quick Enhancement

All-in-One Pipeline

9. Podcast Generation

Podcast Generation

Support

​Overview

​Get your API Key

​Async Task Pattern

​1. Text to Speech

​2. Voice Conversion

​3. Sound Effect Generation

​4. Audio Separation

​5. Speech to Text

​6. Voice Cloning

​7. Music Generation

​By Prompt

​With Lyrics

​Music Cover

​8. Audio Enhancement

​Quick Enhancement

​All-in-One Pipeline

​9. Podcast Generation

​Podcast Generation

​Support

Overview

Get your API Key

Async Task Pattern

1. Text to Speech

2. Voice Conversion

3. Sound Effect Generation

4. Audio Separation

5. Speech to Text

6. Voice Cloning

7. Music Generation

By Prompt

With Lyrics

Music Cover

8. Audio Enhancement

Quick Enhancement

All-in-One Pipeline

9. Podcast Generation

Podcast Generation

Support