IllyVoIPdevelopers

Speech APIs

Generate speech

Generates speech audio from text.

Try in API Playground ↗Sign in to prepare and run this request.
POST/api/v1/tts/synthesize

Before you start

Provide text and a voice from the correct catalog; choose the supported audio format.

Result

Use the returned audio response and inspect the documented billing information.

Charges and safe retries

Submitted text is billable by character. Check the detailed limits and retry rules before submitting again.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X POST "https://api.illyvoip.com/api/v1/tts/synthesize" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Call routing is now active.",
    "language": "en-US",
    "voice": "illyvoip-emma",
    "format": "wav",
    "sample_rate_hz": 22050,
    "channels": 1
}'

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/tts/synthesize", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "text": "Call routing is now active.",
    "language": "en-US",
    "voice": "illyvoip-emma",
    "format": "wav",
    "sample_rate_hz": 22050,
    "channels": 1
})
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/tts/synthesize');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY'),
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => '{
    "text": "Call routing is now active.",
    "language": "en-US",
    "voice": "illyvoip-emma",
    "format": "wav",
    "sample_rate_hz": 22050,
    "channels": 1
}',
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "POST",
    "https://api.illyvoip.com/api/v1/tts/synthesize",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"],
        'Content-Type': 'application/json'
    },
    json=json.loads("{\n    \"text\": \"Call routing is now active.\",\n    \"language\": \"en-US\",\n    \"voice\": \"illyvoip-emma\",\n    \"format\": \"wav\",\n    \"sample_rate_hz\": 22050,\n    \"channels\": 1\n}"),
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request body

application/json

Body required.

textstringrequired

Text to synthesize, maximum 2,000 characters.

maxLength 2000
languagestringoptional

Optional TTS language. Use the canonical code returned by List TTS voices, such as en-US.

voicestringoptional

Voice name from List TTS voices, such as illyvoip-emma.

formatstringoptional

wav or mp3.

enum ["wav", "mp3"]
sample_rate_hzintegeroptional

Integer from 8000 through 48000.

minimum 8000maximum 48000
channelsintegeroptional

1 for mono or 2 for stereo.

enum [1, 2]

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 2000,
      "description": "Text to synthesize, maximum 2,000 characters."
    },
    "language": {
      "type": "string",
      "description": "Optional TTS language. Use the canonical code returned by `List TTS voices`, such as `en-US`."
    },
    "voice": {
      "type": "string",
      "description": "Voice name from `List TTS voices`, such as `illyvoip-emma`."
    },
    "format": {
      "type": "string",
      "enum": [
        "wav",
        "mp3"
      ],
      "description": "`wav` or `mp3`."
    },
    "sample_rate_hz": {
      "type": "integer",
      "minimum": 8000,
      "maximum": 48000,
      "description": "Integer from `8000` through `48000`."
    },
    "channels": {
      "type": "integer",
      "enum": [
        1,
        2
      ],
      "description": "`1` for mono or `2` for stereo."
    }
  },
  "required": [
    "text"
  ]
}
Example body
JSON
{
  "text": "Call routing is now active.",
  "language": "en-US",
  "voice": "illyvoip-emma",
  "format": "wav",
  "sample_rate_hz": 22050,
  "channels": 1
}

Request behavior

Returns base64 audio for the public IllyVoIP voice you selected. Text is limited to 2,000 characters. format must be wav or mp3, sample_rate_hz must be between 8,000 and 48,000, and channels must be 1 or 2.

Conditions and examples

Synthesis is billed per text character. Retry and duplicate-charge protection is automatic. Use List TTS languages to get the language options, then List TTS voices to get the exact voice names for that language.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • voice: Public voice key used for synthesis.
  • mime_type: Media MIME type of the returned audio.
  • audio_base64: Base64-encoded audio. Decode it before saving or playing it.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "voice": "illyvoip-emma",
  "mime_type": "audio/wav",
  "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
}
statusstringrequired
enum ["success"]
voicestringrequired
mime_typestringrequired
audio_base64stringrequired

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "voice": {
      "type": "string"
    },
    "mime_type": {
      "type": "string"
    },
    "audio_base64": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "voice",
    "mime_type",
    "audio_base64"
  ]
}
400 The request failed validation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key or browser token is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
402 The account has insufficient available credit.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 The account is not allowed to perform this operation.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
409 The request conflicts with the current resource or operation state.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected service error occurred.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 The service is temporarily unavailable.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable, insufficient-credit, unavailable

Try this operation in Sandbox · Environment setup and limitations

List STT languagesTranscribe audioList TTS languagesList TTS voices

Search API operations, parameters, SDK and webhooks.