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.
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.
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/tasks/{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 pendingTask queued, not yet started processingTask is being processed completedTask finished — url contains the download link failedTask 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].
Submit the TTS request
curl -X POST https://devapi.fineshare.net/v1/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://devapi.fineshare.net/v1/tasks/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://devapi.fineshare.net" HEADERS = { "Authorization" : f "Bearer { API_KEY } " , "Content-Type" : "application/json" } # 1. Submit TTS request res = requests.post( f " { BASE_URL } /v1/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/tasks/ { 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.
Submit the conversion request
curl -X POST https://devapi.fineshare.net/v1/voice-conversion \ -H "Authorization: Bearer $FINEVOICE_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "voice": "madison", "sourceUrl": "https://dlaudio.fineshare.net/web/finevoice3/audio/avc-example-1.mp3", "outputFormat": "mp3", "useAsync": true }'
Response: { "task_id" : "p1-b2c3d4e5-f6a7-8901-bcde-f12345678901" }
Poll for result
curl -X GET https://devapi.fineshare.net/v1/tasks/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://devapi.fineshare.net" HEADERS = { "Authorization" : f "Bearer { API_KEY } " , "Content-Type" : "application/json" } res = requests.post( f " { BASE_URL } /v1/voice-conversion" , headers = HEADERS , json = { "voice" : "madison" , "sourceUrl" : "https://dlaudio.fineshare.net/web/finevoice3/audio/avc-example-1.mp3" , "outputFormat" : "mp3" , "useAsync" : True }) task_id = res.json()[ "task_id" ] while True : result = requests.get( f " { BASE_URL } /v1/tasks/ { 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.
Submit the SFX request
curl -X POST https://devapi.fineshare.net/v1/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://devapi.fineshare.net/v1/tasks/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://devapi.fineshare.net" HEADERS = { "Authorization" : f "Bearer { API_KEY } " , "Content-Type" : "application/json" } res = requests.post( f " { BASE_URL } /v1/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/tasks/ { 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.
Submit the separation request
curl -X POST https://devapi.fineshare.net/v1/separation \ -H "Authorization: Bearer $FINEVOICE_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "sourceUrl": "https://webresources.fineshare.net/finevoice3/audio/isolator-original.mp3", "model": "default", "useAsync": true }'
Response: { "task_id" : "p1-d4e5f6a7-b8c9-0123-defa-234567890123" }
Poll and download
curl -X GET https://devapi.fineshare.net/v1/tasks/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://devapi.fineshare.net" HEADERS = { "Authorization" : f "Bearer { API_KEY } " , "Content-Type" : "application/json" } res = requests.post( f " { BASE_URL } /v1/separation" , headers = HEADERS , json = { "sourceUrl" : "https://webresources.fineshare.net/finevoice3/audio/isolator-original.mp3" , "model" : "default" , "useAsync" : True }) task_id = res.json()[ "task_id" ] while True : result = requests.get( f " { BASE_URL } /v1/tasks/ { 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)
Support Need help? Check out these resources:
