elevenlabs-go

README

elevenlabs-go

elevenlabs-go is a Go client library for accessing the ElevenLabs API.

This module currently supports speech-to-text, text-to-speech, music, shared voices, IVC voice cloning, PVC voices and samples, Speech Engine resources, Speech Engine upstream WebSockets, model metadata, and authenticated user metadata.

elevenlabs-go requires Go 1.22 or newer.

Installation

elevenlabs-go is compatible with Go modules, with Go installed:

go get github.com/emiliopalmerini/elevenlabs-go/elevenlabs

Alternatively the same can be achieved if you use import in a package:

import "github.com/emiliopalmerini/elevenlabs-go/elevenlabs"

and run go get without parameters.

Usage

import "github.com/emiliopalmerini/elevenlabs-go/elevenlabs"

Construct a new ElevenLabs client, then use the services on the client to access different parts of the ElevenLabs API. For example:

client, err := elevenlabs.NewClient(elevenlabs.WithAuthToken(os.Getenv("ELEVENLABS_API_KEY")))
if err != nil {
	// Handle error.
}

transcript, _, err := client.STT.CreateTranscript(context.Background(), elevenlabs.CreateTranscriptRequest{
	ModelID:   "scribe_v1",
	SourceURL: "https://example.com/audio.mp3",
})
if err != nil {
	// Handle error.
}

fmt.Println(transcript.Text)

Some API methods have optional parameters that can be passed. For example:

client, err := elevenlabs.NewClient(elevenlabs.WithAuthToken(os.Getenv("ELEVENLABS_API_KEY")))
if err != nil {
	// Handle error.
}

voices, _, err := client.Voices.ListShared(context.Background(), elevenlabs.ListSharedVoicesRequest{
	Search:   "narration",
	PageSize: elevenlabs.Ptr(10),
})

The services of a client divide the API into logical chunks:

• client.STT
• client.TTS
• client.Music
• client.Voices
• client.SpeechEngine
• client.Models
• client.User

Using the context package, one can pass cancellation signals and deadlines to service methods. In case there is no context available, context.Background() can be used as a starting point.

Authentication

Use the elevenlabs.WithAuthToken option to configure your client to authenticate using an ElevenLabs API key:

client, err := elevenlabs.NewClient(elevenlabs.WithAuthToken("... your API key ..."))
if err != nil {
	// Handle error.
}

To support more advanced use cases, you can use elevenlabs.WithHTTPClient to provide a custom http.Client.

Note that when using an authenticated client, all calls made by the client will include the specified API key. Authenticated clients should almost never be shared between different users.

Speech To Text

file, err := os.Open("audio.mp3")
if err != nil {
	// Handle error.
}
defer file.Close()

transcript, resp, err := client.STT.CreateTranscript(ctx, elevenlabs.CreateTranscriptRequest{
	ModelID: "scribe_v1",
	File: &elevenlabs.File{
		Name:   "audio.mp3",
		Reader: file,
	},
})
if err != nil {
	// Handle error.
}

fmt.Println(resp.StatusCode)
fmt.Println(transcript.Text)

Webhook transcript jobs use the same request type:

job, _, err := client.STT.SubmitTranscriptWebhook(ctx, elevenlabs.CreateTranscriptRequest{
	ModelID:   "scribe_v1",
	SourceURL: "https://example.com/audio.mp3",
	WebhookID: "your-webhook-id",
	WebhookMetadata: map[string]any{
		"job_id": "123",
	},
})

Realtime transcription uses a WebSocket session:

session, err := client.STT.ConnectRealtimeTranscript(ctx, elevenlabs.RealtimeTranscriptRequest{
	ModelID:     "scribe_v1",
	AudioFormat: "pcm_16000",
})
if err != nil {
	// Handle error.
}
defer session.Close()

Text To Speech

audio, _, err := client.TTS.CreateSpeech(ctx, elevenlabs.CreateSpeechRequest{
	VoiceID:      "JBFqnCBsd6RMkjVDRZzb",
	Text:         "The first move is what sets everything in motion.",
	ModelID:      "eleven_multilingual_v2",
	OutputFormat: elevenlabs.OutputFormatMP3_44100_128,
})
if err != nil {
	// Handle error.
}

_ = os.WriteFile("speech.mp3", audio, 0o644)

HTTP streaming methods return closeable streams:

stream, _, err := client.TTS.StreamSpeech(ctx, elevenlabs.CreateSpeechRequest{
	VoiceID: "JBFqnCBsd6RMkjVDRZzb",
	Text:    "Stream this text.",
})
if err != nil {
	// Handle error.
}
defer stream.Close()

_, err = io.Copy(output, stream)

Input streaming uses explicit WebSocket session messages:

session, err := client.TTS.ConnectStreamInput(ctx, elevenlabs.TTSStreamInputRequest{
	VoiceID:      "JBFqnCBsd6RMkjVDRZzb",
	ModelID:      "eleven_flash_v2_5",
	OutputFormat: elevenlabs.OutputFormatMP3_44100_128,
})
if err != nil {
	// Handle error.
}
defer session.Close()

Music

composition, _, err := client.Music.Compose(ctx, elevenlabs.ComposeMusicRequest{
	Prompt:       "A cinematic synth pop track",
	ModelID:      elevenlabs.MusicModelV2,
	OutputFormat: elevenlabs.OutputFormatMP3_44100_192,
})
if err != nil {
	// Handle error.
}

fmt.Println(composition.SongID)

Music endpoints that upload files use elevenlabs.File:

composition, _, err := client.Music.VideoToMusic(ctx, elevenlabs.VideoToMusicRequest{
	Videos: []elevenlabs.File{
		{Name: "clip.mp4", Reader: video},
	},
	Description: "cinematic background music",
})

Voices

voices, _, err := client.Voices.ListShared(ctx, elevenlabs.ListSharedVoicesRequest{
	Search: "narration",
})
if err != nil {
	// Handle error.
}

added, _, err := client.Voices.AddShared(ctx, voices.Voices[0].PublicOwnerID, voices.Voices[0].VoiceID, elevenlabs.AddSharedVoiceRequest{
	NewName: "Narrator",
})

ivc, _, err := client.Voices.CreateIVC(ctx, elevenlabs.CreateIVCRequest{
	Name: "Narrator",
	Files: []elevenlabs.File{
		{Name: "sample.mp3", Reader: sample},
	},
})

PVC voice metadata, samples, and verification are grouped under client.Voices:

pvc, _, err := client.Voices.CreatePVC(ctx, elevenlabs.CreatePVCRequest{
	Name:     "Narrator",
	Language: "en",
})
if err != nil {
	// Handle error.
}

samples, _, err := client.Voices.AddPVCSamples(ctx, pvc.VoiceID, elevenlabs.AddPVCSamplesRequest{
	Files: []elevenlabs.File{
		{Name: "sample.mp3", Reader: sample},
	},
})

Speech Engine

Create or update Speech Engine resources with the configured upstream WebSocket URL, then host that URL with SpeechEngineUpstreamServer.

engine, _, err := client.SpeechEngine.Create(ctx, elevenlabs.SpeechEngineCreateRequest{
	Name: "Support",
	SpeechEngine: elevenlabs.SpeechEngineConfig{
		WSURL: "wss://example.com/speech-engine/upstream",
	},
	TTS: &elevenlabs.SpeechEngineTTSConfig{
		ModelID: "eleven_flash_v2_5",
		VoiceID: "voice_123",
	},
})

Speech Engine upstream is server-side: ElevenLabs connects to your public WebSocket URL.

server := elevenlabs.SpeechEngineUpstreamServer{
	APIKey: os.Getenv("ELEVENLABS_API_KEY"),
	Handler: elevenlabs.NewManagedSpeechEngineUpstreamHandler(elevenlabs.SpeechEngineUpstreamHandlers{
		OnTranscript: func(ctx context.Context, response *elevenlabs.SpeechEngineTranscriptResponse) error {
			return response.SendFinal(ctx)
		},
	}),
}

http.Handle("/speech-engine/upstream", server)
log.Fatal(http.ListenAndServe(":8080", nil))

Creating and Updating Resources

Request structs use pointer values where the ElevenLabs API needs to distinguish between unset fields and zero values. Use elevenlabs.Ptr to create these pointers:

audio, _, err := client.TTS.CreateSpeech(ctx, elevenlabs.CreateSpeechRequest{
	VoiceID:                  "JBFqnCBsd6RMkjVDRZzb",
	Text:                     "Hello.",
	OptimizeStreamingLatency: elevenlabs.Ptr(2),
})

Response Metadata

Most REST service methods return (*elevenlabs.Response, error) after the decoded value:

transcript, resp, err := client.STT.GetTranscript(ctx, "transcript-id")
if err != nil {
	// Handle error.
}

fmt.Println(resp.StatusCode)
fmt.Println(resp.Header.Get("request-id"))
fmt.Println(resp.Request.URL.String())
fmt.Println(transcript.Text)

Delete-style methods return only response metadata and an error:

resp, err := client.STT.DeleteTranscript(ctx, "transcript-id")
if err != nil {
	// Handle error.
}

fmt.Println(resp.StatusCode)

Errors

Non-2xx API responses return *elevenlabs.APIError when the response can be read:

transcript, _, err := client.STT.GetTranscript(ctx, "transcript-id")
if err != nil {
	var apiErr *elevenlabs.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode)
		fmt.Println(apiErr.Message)
		fmt.Println(apiErr.RequestID)
		fmt.Println(apiErr.Response.StatusCode)
	}
	return err
}

fmt.Println(transcript.Text)

APIError keeps provider error fields, validation details, retry headers, and the raw response metadata.

Retries

Idempotent, replayable requests retry transient status codes by default:

• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Customize or disable retries with client options:

client, err := elevenlabs.NewClient(
	elevenlabs.WithAuthToken(os.Getenv("ELEVENLABS_API_KEY")),
	elevenlabs.WithRetryConfig(elevenlabs.RetryConfig{
		MaxAttempts: 5,
	}),
)
if err != nil {
	// Handle error.
}

noRetryClient, err := elevenlabs.NewClient(
	elevenlabs.WithAuthToken(os.Getenv("ELEVENLABS_API_KEY")),
	elevenlabs.WithoutRetries(),
)

POST requests, including file uploads, are not retried automatically because the provider may have accepted them before returning a transient error. Retry these operations explicitly only when duplicate creation is safe for the endpoint and application.

Client Options

client, err := elevenlabs.NewClient(
	elevenlabs.WithAuthToken(os.Getenv("ELEVENLABS_API_KEY")),
	elevenlabs.WithHTTPClient(customHTTPClient),
	elevenlabs.WithBaseURL("https://api.elevenlabs.io"),
)

WithBaseURL is mainly useful for tests or custom API routing.

Testing code that uses elevenlabs-go

Use httptest.Server and elevenlabs.WithBaseURL to test code that calls the client:

server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	_, _ = w.Write([]byte(`{"user_id":"user_123"}`))
}))
defer server.Close()

client, err := elevenlabs.NewClient(
	elevenlabs.WithAuthToken("test-key"),
	elevenlabs.WithBaseURL(server.URL),
	elevenlabs.WithHTTPClient(server.Client()),
)

Development

Run the package checks with:

go test ./...
go vet ./...

Versioning

Tagged releases are standard Go module versions:

git tag v0.3.0
git push origin v0.3.0

Consumers can then depend on the package with:

go get github.com/emiliopalmerini/elevenlabs-go/elevenlabs@v0.3.0

License

This library is distributed under the license found in the LICENSE file.