HTTP Speech
Speech (OpenAI-compatible)
Use Bland voices through the OpenAI text-to-speech request and error shapes.
POST
/
v2
/
audio
/
speech
Speech (OpenAI-compatible)
curl --request POST \
--url https://api.bland.ai/v2/audio/speech \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"model": "<string>",
"input": "<string>",
"voice": "<string>",
"response_format": "<string>",
"speed": 123,
"stream_format": "<string>",
"instructions": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/audio/speech"
payload = {
"model": "<string>",
"input": "<string>",
"voice": "<string>",
"response_format": "<string>",
"speed": 123,
"stream_format": "<string>",
"instructions": "<string>"
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
input: '<string>',
voice: '<string>',
response_format: '<string>',
speed: 123,
stream_format: '<string>',
instructions: '<string>'
})
};
fetch('https://api.bland.ai/v2/audio/speech', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/audio/speech",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => '<string>',
'voice' => '<string>',
'response_format' => '<string>',
'speed' => 123,
'stream_format' => '<string>',
'instructions' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/audio/speech"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/audio/speech")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/audio/speech")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"x-request-id": "<string>"
}Overview
This endpoint implements OpenAI’s/audio/speech contract. If you already use an OpenAI SDK or a compatible router such as LiteLLM, change the base URL, API key, and model to route speech through Bland.
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["BLAND_API_KEY"],
base_url="https://api.bland.ai/v2",
)
with client.audio.speech.with_streaming_response.create(
model="btts-3",
voice="coral",
input="Hello from Bland.",
) as response:
response.stream_to_file(Path("hello.mp3"))
Headers
Bearer <your API key>. OpenAI SDKs send this from their api_key or apiKey configuration.Body parameters
btts-3 or btts-2.OpenAI model IDs such as tts-1 and gpt-4o-mini-tts are not aliased. Unknown IDs return 400 with code model_not_found.The model must match the selected Bland voice. A mismatch returns 400 with code model_voice_mismatch.A recognized OpenAI voice name, mapped to a Bland core voice, or a Bland voice UUID for the full catalog.
Names are case-insensitive. An unrecognized name returns
| OpenAI name | Bland voice |
|---|---|
alloy, ash, coral, fable | River |
amber, august, lily, nova, shimmer | Karen |
ballad, blue, echo, onyx, sage, verse | Matthew |
400.mp3, opus, aac, flac, wav, or pcm.pcm is raw 24 kHz signed 16-bit little-endian mono audio. The other formats use a 48 kHz render and include their normal file or stream framing.Only
1.0 is accepted. Other values return 400 because Bland does not currently expose speed control on this endpoint.Response
The response body contains audio bytes.Content-Type matches the requested format:
response_format | Content-Type |
|---|---|
mp3 | audio/mpeg |
opus | audio/ogg |
aac | audio/aac |
flac | audio/flac |
wav | audio/wav |
pcm | audio/pcm |
Errors
Errors use OpenAI’s envelope so SDK error handling remains readable:{
"error": {
"message": "The model 'tts-1' does not exist. Supported models: btts-3, btts-2.",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}
| Condition | HTTP | Code |
|---|---|---|
| Missing or malformed field | 400 | null |
| Unknown model | 400 | model_not_found |
| Model does not match the selected voice | 400 | model_voice_mismatch |
| Unsupported voice type | 400 | null |
| Out of credits | 402 | insufficient_quota |
| Professional voice is still a draft | 403 | voice_not_live |
| Voice UUID is not found or accessible | 404 | voice_not_found |
| Synthesis fails before audio begins | 500 | synthesis_failed |
Examples
curl -X POST "https://api.bland.ai/v2/audio/speech" \
-H "Authorization: Bearer $BLAND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "btts-3",
"input": "Hello from Bland.",
"voice": "coral",
"response_format": "mp3"
}' \
--output hello.mp3
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["BLAND_API_KEY"],
base_url="https://api.bland.ai/v2",
)
with client.audio.speech.with_streaming_response.create(
model="btts-3",
voice="coral",
input="Hello from Bland.",
) as response:
response.stream_to_file(Path("hello.mp3"))
import os
import litellm
litellm.speech(
model="openai/btts-3",
voice="coral",
input="Hello from Bland.",
api_base="https://api.bland.ai/v2",
api_key=os.environ["BLAND_API_KEY"],
)
import fs from "node:fs/promises";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.BLAND_API_KEY,
baseURL: "https://api.bland.ai/v2",
});
const response = await client.audio.speech.create({
model: "btts-3",
voice: "coral",
input: "Hello from Bland.",
});
await fs.writeFile("hello.mp3", Buffer.from(await response.arrayBuffer()));
Docs for agents: llms.txt
Was this page helpful?
⌘I
Speech (OpenAI-compatible)
curl --request POST \
--url https://api.bland.ai/v2/audio/speech \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"model": "<string>",
"input": "<string>",
"voice": "<string>",
"response_format": "<string>",
"speed": 123,
"stream_format": "<string>",
"instructions": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/audio/speech"
payload = {
"model": "<string>",
"input": "<string>",
"voice": "<string>",
"response_format": "<string>",
"speed": 123,
"stream_format": "<string>",
"instructions": "<string>"
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
input: '<string>',
voice: '<string>',
response_format: '<string>',
speed: 123,
stream_format: '<string>',
instructions: '<string>'
})
};
fetch('https://api.bland.ai/v2/audio/speech', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/audio/speech",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'input' => '<string>',
'voice' => '<string>',
'response_format' => '<string>',
'speed' => 123,
'stream_format' => '<string>',
'instructions' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/audio/speech"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/audio/speech")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/audio/speech")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"input\": \"<string>\",\n \"voice\": \"<string>\",\n \"response_format\": \"<string>\",\n \"speed\": 123,\n \"stream_format\": \"<string>\",\n \"instructions\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"x-request-id": "<string>"
}