Text to Voice with Go

Generate spoken audio from Go using the Narakeet REST API. The example below uses only the standard library — net/http for the request and io for streaming the response to a file — so there is nothing to go get. It compiles to a single binary that runs anywhere Go runs.

For endpoint details, authentication, and cross-language features, see the main Text to Speech API reference.

Go Text to Speech Example

The following program sends text to the Narakeet API and saves the result as an MP3 file. The textToSpeech function takes an *http.Client as its first parameter, keeping the transport layer separate from the API logic.

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
	"time"
)

func textToSpeech(client *http.Client, apiKey string, voice string, text string, outputPath string) error {
	url := fmt.Sprintf("https://api.narakeet.com/text-to-speech/mp3?voice=%s", voice)

	req, err := http.NewRequest("POST", url, strings.NewReader(text))
	if err != nil {
		return fmt.Errorf("creating request: %w", err)
	}

	req.Header.Set("Accept", "application/octet-stream")
	req.Header.Set("Content-Type", "text/plain")
	req.Header.Set("x-api-key", apiKey)

	resp, err := client.Do(req)
	if err != nil {
		return fmt.Errorf("sending request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("API error %d: %s", resp.StatusCode, string(body))
	}

	file, err := os.Create(outputPath)
	if err != nil {
		return fmt.Errorf("creating file: %w", err)
	}
	defer file.Close()

	_, err = io.Copy(file, resp.Body)
	if err != nil {
		return fmt.Errorf("writing file: %w", err)
	}

	return nil
}

func main() {
	apiKey := os.Getenv("NARAKEET_API_KEY")
	if apiKey == "" {
		fmt.Println("Please set NARAKEET_API_KEY environment variable")
		os.Exit(1)
	}

	client := &http.Client{Timeout: 30 * time.Second}

	err := textToSpeech(client, apiKey, "rodney", "Hi there from Go", "output.mp3")
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("File saved at: output.mp3")
}

Save this as tts.go and run with go run tts.go. The response streams directly to disk via io.Copy, so memory stays flat regardless of audio length.

For the complete project, see the Go streaming API example on GitHub.

Go Text to Voice

Go’s compiled binaries and minimal runtime make it a natural fit for text to voice tasks that run in constrained environments. Where Go text to voice works well in practice:

  • CLI tools distributed as single binaries that generate spoken audio from config files or input streams
  • Microservices behind a gRPC or HTTP gateway returning audio on demand
  • Kubernetes jobs that batch-process text into audio files as part of a data pipeline
  • Cloud Functions on GCP that produce speech from webhook payloads without installing a language runtime
  • Build system plugins that generate audio assets during CI

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

Goroutines and Concurrent Audio Generation

Go’s goroutines make it straightforward to generate multiple audio files at the same time. Spin up one goroutine per request, share a single *http.Client (which is safe for concurrent use), and collect results through a channel or sync.WaitGroup. The API handles requests independently, so parallelism scales with your network bandwidth rather than CPU.

This is useful when converting a batch of short strings — UI labels, notification messages, or localisation keys — into individual audio files. Instead of processing them one at a time, fire all requests concurrently and let Go’s scheduler manage the I/O wait.

Controlling Voice and Audio Settings

The endpoint URL and query parameters control the output:

  1. Audio format — change the path in the URL: /text-to-speech/mp3 for compressed audio, /text-to-speech/m4a for higher quality at similar size, or /text-to-speech/wav for uncompressed PCM (requires the polling API)
  2. Voice — append ?voice=rodney to select from 900 voices across 100 languages; browse all options at Text to Speech Voices
  3. Speed — add &voice-speed=1.2 to read 20% faster, or &voice-speed=0.85 to slow it down
  4. Volume — add &voice-volume=soft or &voice-volume=loud to shift the output level

For pitch adjustments, sentence pauses, and multi-voice scripts, use the script header format in the request body. Full details at Configuring Audio Tasks.

Go TTS with Standard Library

A common question is whether a dedicated Go TTS package exists on pkg.go.dev. With Narakeet, the standard library covers the entire integration — net/http for the POST request, io.Copy to stream the response to a file, and os for environment variables. There is no CGo dependency, no system library to link, and no external module to version. The textToSpeech function in the example above works as-is in any Go project from version 1.13 onward.