VoiceFlow API Documentation

Integrate ultra-realistic text-to-speech into your applications with our REST API. Powered by Microsoft Edge TTS for free, high-quality voice generation.

API Status: Operational Check health: GET /api/health

99.9%

Uptime SLA

<150ms

Avg Latency

v2.5

Latest Version

Base URL

https://api.voiceflow.com/v2

Local development

For local testing run the backend (default port 3000). Use the local API base URL below or, when the frontend proxies requests, the relative path /api/v2/text-to-speech.

Local (dev)

curl -X POST http://localhost:3000/api/v2/text-to-speech \
  -H "x-api-key: vf_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "voice_id": "en-US-AriaNeural"}'

Authentication

API Key Authentication

All API requests require authentication using your API key. Include it in the x-api-key header.

Security Critical

Never expose your API key in client-side JavaScript, HTML, or public repositories. Always proxy requests through your backend server.

Correct: Server-side usage (Node.js)

Safe: API key in environment variable

const response = await fetch('https://api.voiceflow.com/v2/text-to-speech', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICEFLOW_API_KEY, // Server-side only
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Hello', voice_id: 'en-US-AriaNeural' })
});

❌

Never do this in frontend code:

headers: { 'x-api-key': 'vf_sk_123...' } // Exposed to all users!

Getting Your API Key

Sign up for a VoiceFlow account
Navigate to Dashboard -> Settings -> API Keys
Click "Generate New Key"
Copy and store securely in environment variables

Quickstart

cURL example

curl -X POST https://api.voiceflow.com/v2/text-to-speech \
  -H "x-api-key: $VOICEFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "voice_id": "en-US-AriaNeural"}'

Python example

import os
import requests

response = requests.post(
    "https://api.voiceflow.com/v2/text-to-speech",
    headers={
        "x-api-key": os.environ["VOICEFLOW_API_KEY"],
        "Content-Type": "application/json"
    },
    json={"text": "Hello world!", "voice_id": "en-US-AriaNeural"}
)

with open("speech.mp3", "wb") as f:
    f.write(response.content)
print("Audio saved!")

Node.js example (ES Modules)

const response = await fetch('https://api.voiceflow.com/v2/text-to-speech', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICEFLOW_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello world!',
    voice_id: 'en-US-AriaNeural'
  })
});
const data = await response.json();
console.log('Audio URL:', data.generation.audio_url);

Go example

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    body := map[string]string{"text": "Hello", "voice_id": "en-US-AriaNeural"}
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.voiceflow.com/v2/text-to-speech", bytes.NewBuffer(jsonBody))
    req.Header.Set("x-api-key", os.Getenv("VOICEFLOW_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))

Text to Speech

POST /v2/text-to-speech

Generate natural-sounding speech from text input.

Request Body Parameters

Parameter	Type	Required	Default	Description
`text`	string	Yes	-	Text to convert (max 5000 chars)
`voice_id`	string	Yes	-	Voice ID (e.g., en-US-AriaNeural)
`model`	string	No	multilingual_v2	multilingual_v2, flash_v2.5, v3_alpha
`stability`	float	No	0.5	Voice stability (0.0 - 1.0)

Response (200 OK)

{
  "success": true,
  "generation": {
    "id": "gen_abc123",
    "audio_url": "/audio/tts_abc123.mp3",
    "duration": 2.5,
    "credits_used": 25,
    "credits_remaining": 9975
  }
}

Voices

GET /v2/voices

Retrieve available voices for text-to-speech generation.

Query Parameters

Parameter	Type	Description
`language`	string	Filter by language (e.g., en-US, es-ES, fr-FR)
`gender`	string	Filter: male, female

Models

GET /v2/models

Model ID	Languages	Quality	Latency
multilingual_v2	70	High	~500ms
flash_v2.5	32	High	<200ms
v3_alpha	70	Ultra	~800ms

History

GET /v2/history

Get your generation history, sorted by newest first.

DELETE /v2/history/:id

Delete a specific generation by its ID.

SDKs & Libraries

Python SDK

Official Python client for VoiceFlow.

pip install voiceflow-sdk

Node.js SDK

JavaScript/TypeScript client.

npm install @voiceflow/sdk

Rate Limits

Plan	Requests/min	Credits/month	Max text length
Free	30	10,000	500 chars
Starter	60	30,000	2,000 chars
Creator	120	100,000	5,000 chars
Pro	300	500,000	5,000 chars

Note: rate limit headers are included in responses: X-RateLimit-Remaining, X-RateLimit-Reset

Error Codes

Code	Meaning
400	Bad request - missing required parameters
401	Unauthorized - invalid or missing API key
402	Payment required - insufficient credits
429	Too many requests - rate limit exceeded
500	Internal server error - try again later

API Playground

Test the API directly from your browser. Your API key is only used for this request and not stored.

API Key

Text

Voice

Model

Response