C++ Voice API

Generate spoken audio from C++ using the Narakeet REST API. The example on this page uses libcurl — the most portable and widely deployed HTTP client library in the C/C++ ecosystem — as the only external dependency. It compiles on Linux, macOS, and Windows without changes.

For endpoint details, authentication, and features common to all languages, see the main Text to Speech API reference.

C++ Text to Speech Example

The program below sends text to the Narakeet API and writes the audio response to an MP3 file. The text_to_speech function accepts all parameters explicitly, keeping the API logic self-contained and easy to integrate into larger projects.

#include <cstdlib>
#include <fstream>
#include <iostream>
#include <string>
#include <curl/curl.h>

static size_t write_callback(void *contents, size_t size, size_t nmemb, void *userp) {
	std::string *response = static_cast<std::string *>(userp);
	size_t total = size * nmemb;
	response->append(static_cast<char *>(contents), total);
	return total;
}

int text_to_speech(const std::string &api_key, const std::string &voice, const std::string &text, const std::string &output_path) {
	CURL *curl = curl_easy_init();
	if (!curl) {
		std::cerr << "Error: failed to initialize curl" << std::endl;
		return 1;
	}

	std::string url = "https://api.narakeet.com/text-to-speech/mp3?voice=" + voice;
	std::string response_body;

	struct curl_slist *headers = NULL;
	headers = curl_slist_append(headers, "Accept: application/octet-stream");
	headers = curl_slist_append(headers, "Content-Type: text/plain");
	headers = curl_slist_append(headers, ("x-api-key: " + api_key).c_str());

	curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
	curl_easy_setopt(curl, CURLOPT_POST, 1L);
	curl_easy_setopt(curl, CURLOPT_POSTFIELDS, text.c_str());
	curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, static_cast<long>(text.size()));
	curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
	curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback);
	curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response_body);
	curl_easy_setopt(curl, CURLOPT_TIMEOUT, 30L);

	CURLcode res = curl_easy_perform(curl);

	if (res != CURLE_OK) {
		std::cerr << "Error: " << curl_easy_strerror(res) << std::endl;
		curl_slist_free_all(headers);
		curl_easy_cleanup(curl);
		return 1;
	}

	long http_code = 0;
	curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http_code);

	curl_slist_free_all(headers);
	curl_easy_cleanup(curl);

	if (http_code != 200) {
		std::cerr << "API error " << http_code << ": " << response_body << std::endl;
		return 1;
	}

	std::ofstream file(output_path, std::ios::binary);
	if (!file.is_open()) {
		std::cerr << "Error: could not create file " << output_path << std::endl;
		return 1;
	}

	file.write(response_body.data(), response_body.size());
	file.close();

	return 0;
}

int main() {
	const char *env_key = std::getenv("NARAKEET_API_KEY");
	if (!env_key || std::string(env_key).empty()) {
		std::cerr << "Please set NARAKEET_API_KEY environment variable" << std::endl;
		return 1;
	}

	std::string api_key(env_key);

	int result = text_to_speech(api_key, "emma", "Hi there from C++", "output.mp3");
	if (result != 0) {
		return 1;
	}

	std::cout << "File saved at: output.mp3" << std::endl;
	return 0;
}

Save this as tts.cpp. Set NARAKEET_API_KEY in your environment — create a key from the API Keys page — then compile and run as described in the section below.

For the complete project with a Makefile and build instructions, see the C++ streaming API example on GitHub.

Compiling the Example

Compile the program with any C++ compiler that supports C++11 or later. Link against libcurl:

g++ -o tts tts.cpp -lcurl

On most Linux distributions, install the development headers with apt install libcurl4-openssl-dev (Debian/Ubuntu) or dnf install libcurl-devel (Fedora/RHEL). On macOS, libcurl ships with the system. On Windows, vcpkg or the prebuilt curl binaries work with MSVC and MinGW.

After compiling, run the binary:

export NARAKEET_API_KEY=your-key-here
./tts

C++ Text to Speech Use Cases

C++ delivers predictable performance and direct hardware access, making it a strong choice for text to speech tasks in environments where other runtimes add unwanted overhead. Where C++ text to speech fits in practice:

  • Game engines that generate spoken dialogue or narration at build time without bundling a speech runtime
  • Desktop applications using Qt, wxWidgets, or native frameworks that need voice output without platform-specific TTS bindings
  • Audio processing pipelines where speech synthesis is one stage in a chain of DSP operations
  • CI/CD tooling written in C++ that produces audio assets as part of the build
  • Server-side rendering in high-throughput services where latency budgets are tight

For content longer than 1 KB or uncompressed WAV output, switch to the Long Content (Polling) API.

C++ TTS API Options

Control voice, speed, volume, and format through the endpoint URL and query parameters:

Audio format
Change the URL path — /text-to-speech/mp3 for compressed audio, /text-to-speech/m4a for better quality at similar size, /text-to-speech/wav for uncompressed PCM (requires the polling API)
Voice
Append ?voice=emma to choose from 900 voices in 100 languages — see all options at Text to Speech Voices
Speed
Add &voice-speed=1.2 for 20% faster output, or values below 1.0 to slow the voice down
Volume
Add &voice-volume=soft or &voice-volume=loud to adjust the output level

For pitch control, pauses, and multi-voice scripts, pass a script header in the request body. Full reference at Configuring Audio Tasks.

Embedded and IoT Text to Speech

C++ runs on everything from microcontrollers to mainframes, making it the natural language for embedded and IoT text to speech. Edge devices, kiosks, and industrial controllers often cannot install a full speech engine like eSpeak or SAPI, but they can make an HTTPS call. With Narakeet, a device only needs a network connection and libcurl to generate spoken audio — no local speech model, no large binary dependencies, and no GPU.

This approach works well for devices that generate voice prompts infrequently — status announcements, alert messages, or configuration confirmations — where the audio can be fetched on demand or cached locally after the first request.

C++ TTS Without a Speech Engine

Traditional C++ text to speech requires linking against platform-specific libraries: SAPI on Windows, NSSpeechSynthesizer on macOS, or speech-dispatcher on Linux. Each has its own API surface, build configuration, and voice format. Cross-platform builds need conditional compilation and separate code paths for each target.

With Narakeet, C++ text to speech is a single HTTPS POST that returns audio bytes. The same source compiles and runs identically on every platform where libcurl is available — which is virtually everywhere. There is no engine to initialise, no voice data to bundle, and no platform #ifdef blocks for speech output.