io.Reader streams for audio output.
Installation
go.mod. Newer Go releases work with the module; use the version your team standardizes on for builds and CI.
Authentication
Get your API key from Camb.ai Studio and pass it withoption.WithAPIKey. Reading CAMB_API_KEY from the environment keeps secrets out of source control.
Imports
The root module ispackage cambai, so the default import name is cambai when you import github.com/camb-ai/cambai-go-sdk. You may also use an explicit alias (import cambai "github.com/camb-ai/cambai-go-sdk") for clarity in larger codebases. The snippets below assume the default name cambai.
Quick Start
TextToSpeech.Tts returns an io.Reader streaming audio. Copy it to a file (or another writer) with io.Copy.
c and ctx are initialized as shown above.
Models
Camb.ai offers MARS models tuned for different quality and latency needs. SetSpeechModel on CreateStreamTtsRequestPayload using the generated constants (for example CreateStreamTtsRequestPayloadSpeechModelMarsFlash). If you omit it, the API applies its default model.
| Model | Sample Rate | Best For |
|---|---|---|
mars-8.1-flash-beta | 48 kHz | Faster MARS 8.1 generation; same quality improvements as mars-8.1-pro-beta |
mars-8.1-pro-beta | 48 kHz | Improved pronunciation, expressiveness, and prosody over mars-pro |
mars-flash | 22.05 kHz | Low-latency real-time applications and conversational AI |
mars-pro | 48 kHz | High-fidelity audio production and long-form content |
mars-instruct | 22.05 kHz | Fine-grained tone and style control via text instructions |
- MARS Flash
- MARS Pro
- MARS Instruct
ctx and c variables in the model tabs match the authenticated client pattern from the Quick Start and Authentication sections.
TTS Options
c.TextToSpeech.Tts(...) accepts CreateStreamTtsRequestPayload with the core request fields plus optional controls for model behavior and output format.
| Field | Type | Description |
|---|---|---|
Text | string | Text to synthesize. For MARS Instruct, you can include inline emotion or pacing tags in the text. |
Language | enum | Locale such as cambai.CreateStreamTtsRequestPayloadLanguageEnUs. |
VoiceID | integer | Voice profile ID from VoiceCloning.ListVoices. |
SpeechModel | pointer enum/string | Model to use, such as MarsFlash, MarsPro, or MarsInstruct. |
UserInstructions | string pointer | Adds style, tone, pronunciation, or delivery guidance for the request. Available only when SpeechModel is MARS Instruct. |
OutputConfiguration | *cambai.StreamTtsOutputConfiguration | Output settings such as audio format. |
VoiceSettings | object | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation. |
InferenceOptions | object | Advanced generation controls for supported models. |
EnhanceNamedEntitiesPronunciation | boolean pointer | Improves pronunciation for names and other named entities when supported. |
Voices
VoiceCloning.ListVoices returns the voices available to your account.
VoiceCloning.CreateCustomVoice accepts BodyCreateCustomVoiceCreateCustomVoicePost (voice name, Gender, optional description, and other metadata). Map Gender to the integer values described in the Create custom voice reference. The generated request type in this module does not include a sample audio field; if your workflow requires uploading a clip, use the REST multipart contract or confirm the latest SDK types match your needs.
Language support
TTS requests use typed language constants onCreateStreamTtsRequestPayload (for example CreateStreamTtsRequestPayloadLanguageEnUs). See Language Support for the full per-model locale list. Dubbing, translation, transcription, and related payloads use the shared cambai.Languages type (for example cambai.LanguagesEnUs).
Languages.GetSourceLanguages and Languages.GetTargetLanguages return the language lists exposed by the API for products that distinguish source and target sets.
Dubbing
Dubbing takes a public video URL, translates the audio into your target language, and synthesizes speech. The flow is asynchronous: submit withDub.EndToEndDubbing, poll with Dub.GetEndToEndDubbingStatus, then read the output with Dub.GetDubbedRunInfo. Go uses EndToEndDubbing (same naming as the TypeScript SDK, unlike Python create_dub).
Dub.GetEndToEndDubbingStatus with that task id until Status is cambai.TaskStatusSuccess or cambai.TaskStatusError, then call Dub.GetDubbedRunInfo with the RunID from the status object. See examples/dubbing in the cambai-go-sdk repository for a full loop.
For multiple targets in one job, set TargetLanguages instead of TargetLanguage.
Transcript
After a successful run,Dub.GetDubbedRunTranscript returns transcript data for a target language.
Translation
Submit strings withTranslation.CreateTranslation, poll GetTranslationTaskStatus, then fetch strings with GetTranslationResult. CreateTranslation is typed as interface{} in this client; round-trip through JSON is a reliable way to read task_id into OrchestratorPipelineCallResult.
Transcription
Pass a remote URL withMediaURL on BodyCreateTranscriptionTranscribePost. Poll GetTranscriptionTaskStatus, then call GetTranscriptionResult with optional word-level timestamps.
MediaURL (and deprecated AudioURL). If you need to upload a local file from Go, confirm the latest SDK supports the multipart fields your server expects, or use the REST API directly.
Audio separation
The client exposesAudioSeparation.CreateAudioSeparation, GetAudioSeparationStatus, GetAudioSeparationRunInfo, and batch helpers. The generated BodyCreateAudioSeparationAudioSeparationPost type in this repository currently carries metadata fields only. For production uploads, validate the request type against Audio separation in your SDK version or call the REST endpoints until the generator includes the media parts you rely on.
Text-to-voice
Text-to-voice creates candidate voices from a description. Submit withTextToVoice.CreateTextToVoice, poll GetTextToVoiceStatus, then read previews from GetTextToVoiceResult.
GetTextToVoiceResultOut value includes Previews (URLs) you can audition before choosing a voice_id for TTS.
Text-to-audio
Text-to-audio generates sound from a prompt. The pattern matches other async jobs:CreateTextToAudio, GetTextToAudioStatus, then GetTextToAudioResult as an io.Reader.
Stories
Story.CreateStory returns *CreateStoryStoryPostResponse, a discriminated union over OrchestratorPipelineCallResult (async task_id) and GetSetupStoryResultResponse (immediate setup payload). Use Accept with CreateStoryStoryPostResponseVisitor to read whichever branch the API returned, then poll GetStoryStatus when you received a task id.
The generated BodyCreateStoryStoryPost struct lists the fields this client sends. If you rely on uploading a source document, compare that struct to the REST story endpoint for your SDK revision.
Translated TTS
TranslatedTts.CreateTranslatedTts returns CreateTranslatedTtsOut with a string TaskID. Poll with GetTranslatedTtsTaskStatus until Status is success or error.
Dictionaries
Dictionaries.GetDictionaries lists dictionaries. AddTermToDictionary accepts TermTranslationInput entries (Translation string plus Language). IDs are integers.
DeleteDictionaryTerm and DeleteDictionary take integer IDs and optional RunID query parameters on their request structs. The CreateDictionaryFromFile helper in this module builds multipart metadata only; for CSV-based creation, prefer the REST contract in the API reference until the client matches it.
Folders
Folders.ListFolders and Folders.CreateFolder organize runs in Studio-compatible projects. Pass the generated request structs from the cambai package for optional filters.
Error handling
API failures surface aserror values. Validation responses decode to *cambai.UnprocessableEntityError, which embeds *core.APIError. Use errors.As to inspect status codes and optional Body details.
github.com/camb-ai/cambai-go-sdk/option, for example option.WithMaxAttempts(3).
Custom provider (Baseten)
The Go SDK does not mirror the TypeScriptttsProvider constructor flag on the main client. Instead, implement provider.TtsProvider from github.com/camb-ai/cambai-go-sdk/provider and call Tts yourself (or inject the implementation into your own stack). See the baseten-provider example in the Go SDK repository for a complete BasetenProvider struct, HTTP wiring, and streaming output to disk.
Next steps
Voice Agents
Build real-time voice agents with Pipecat
LiveKit Integration
Create voice agents with LiveKit
API Reference
Explore the full TTS API
Voice Library
Browse available voices