Speech (totalum-sdk/speech)

import … from 'totalum-sdk/speech' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Speech to text (transcribe) and text to speech (synthesize): transcribe a recording or a voice note, read a text aloud, store the audio as a project file. Billed in credits per minute of audio or per character.

const { text } = await totalum.speech.transcribe({ url: recording.fileUrl });

#totalumSpeech

totalumSpeech(options?: TotalumClientOptions): TotalumSpeech

Creates the speech namespace (the same object as totalum.speech, scope speech): speech to text and text to speech through Totalum. The AI gateway (ai.gatewayConfig()) also offers /audio/speech and /audio/transcriptions for OpenAI-compatible clients; these methods keep working.

Parameters

Returns TotalumSpeech — The speech namespace: the methods below.

Example

import { totalumSpeech } from 'totalum-sdk/speech';

const speech = totalumSpeech();
const { text } = await speech.transcribe({ url: 'https://example.com/voice-note.mp3' });

The namespace's type is exported as TotalumSpeech (import type { TotalumSpeech } from 'totalum-sdk/speech').

#speech.transcribe

speech.transcribe(input: TranscribeInput): Promise<TranscribeOutput>

Speech to text: transcribes a recording, a voice note or a video's audio, from a url (a public one, or a file this project stored) or from audioBase64 plus a filename with its extension. Formats: mp3, mp4, m4a, wav, webm, ogg, opus, flac, aac; at most 25 MB. Billed in credits per second of audio.

Parameters

Returns Promise<TranscribeOutput> — The text, the audio's duration and what it cost.

Errors — besides the errors every call can throw:

Example

const result = await totalum.speech.transcribe({ url: voiceNote.fileUrl, language: 'en' });

Result:

{ "text": "Hello there.", "durationSec": 10, "usage": { "credits": 0.0064 } }

#speech.synthesize

speech.synthesize(input: { text, voice?, language?, model?, format?, speed?, store }): Promise<StoredMedia>
speech.synthesize(input: SpeakInput): Promise<StoredMedia | SpeechAudio>

Reads a text aloud (text to speech): with store: true the audio is saved as a public project file and you get its key and url; otherwise you get the audio bytes to return from a route or store yourself. Billed in credits per character.

Parameters

Returns Promise<StoredMedia \| SpeechAudio> — The stored file { key, url, usage } with store: true; else the audio bytes { audio, contentType, usage }.

Errors — besides the errors every call can throw:

Examples

const audio = await totalum.speech.synthesize({ text: 'Your order has shipped.', store: true });

Result:

{
  "key": "p/acme-crm/01M4P0SZ4SKYEPG76P3DATMX1C.mp3",
  "url": "https://files.totalum-project.com/p/acme-crm/01M4P0SZ4SKYEPG76P3DATMX1C.mp3",
  "usage": { "credits": 0.01 }
}

// the bytes, returned from a route
const out = await totalum.speech.synthesize({ text: 'Hi Ana', format: 'mp3' });
if ('audio' in out) return new Response(out.audio, { headers: { 'content-type': out.contentType } });

Result:

{ audio: ArrayBuffer(15360), contentType: 'audio/mpeg', usage: { credits: 0.01 } }

#SpeakInput

The input of speech.synthesize().

#SpeechAudio

The audio bytes of synthesize without store, and what the call cost (usage.credits, the call's hold).

#StoredMedia

A generated file stored in the project's files.

#TranscribeInput

The input of speech.transcribe(): a url, or audioBase64 with a filename.

#TranscribeOutput

A transcription, from speech.transcribe().