Supertone Public API: Supertone API is a RESTful API for using our state-of-the-art AI voice models.
The SDK can be installed with either npm, pnpm, bun or yarn package managers.
npm add @supertone/supertonepnpm add @supertone/supertonebun add @supertone/supertoneyarn add @supertone/supertone zod
# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.Note
This package is published with CommonJS and ES Modules (ESM) support.
For supported JavaScript runtimes, please consult RUNTIMES.md.
import { Supertone } from "@supertone/supertone";
const supertone = new Supertone({
apiKey: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await supertone.textToSpeech.createSpeech({
voiceId: "<id>",
apiConvertTextToSpeechUsingCharacterRequest: {
text: "<value>",
language: "ja",
},
});
console.log(result);
}
run();This SDK supports the following security scheme globally:
| Name | Type | Scheme |
|---|---|---|
apiKey |
apiKey | API key |
To authenticate with the API the apiKey parameter must be set when initializing the SDK client instance. For example:
import { Supertone } from "@supertone/supertone";
const supertone = new Supertone({
apiKey: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await supertone.textToSpeech.createSpeech({
voiceId: "<id>",
apiConvertTextToSpeechUsingCharacterRequest: {
text: "<value>",
language: "ja",
},
});
console.log(result);
}
run();Supertone’s Text-to-Speech API provides multiple TTS models, each with different supported languages, available voice settings, and streaming capabilities.
| Model Name | Identifier | Streaming Support (stream_speech) |
Voice Settings Support |
|---|---|---|---|
| SONA Speech 1 | sona_speech_1 |
✅ Supported | Supports all Voice Settings |
| Supertonic API 1 | supertonic_api_1 |
❌ Not supported | Supports only the speed setting (others are ignored) |
| SONA Speech 2 | sona_speech_2 |
❌ Not supported | Supports all Voice Settings except subharmonic_amplitude_control |
| SONA Speech 2 Flash | sona_speech_2_flash |
❌ Not supported | Supports all Voice Settings except similarity, text_guidance,subharmonic_amplitude_control |
Note
Streaming Support
Streaming TTS using the stream_speech endpoint is only available for the sona_speech_1 model.
Normalized Text Support
The normalized_text parameter is supported only with the sona_speech_2 and sona_speech_2_flash models.
It is ignored when used with other models.
Note
The set of supported input languages varies depending on the TTS model.
-
sona_speech_1
en,ko,ja
-
supertonic_api_1
en,ko,ja,es,pt
-
sona_speech_2
en,ko,ja,bg,cs,da,el,es,et,fi,hu,it,nl,pl,pt,ro,
ar,de,fr,hi,id,ru,vi
-
sona_speech_2_flash
en,ko,ja,bg,cs,da,el,es,et,fi,hu,it,nl,pl,pt,ro,
ar,de,fr,hi,id,ru,vi
Some TTS models support optional voice settings that allow fine control over output speech characteristics (e.g., speed, pitch, pitch variance).
Note
The available Voice Settings vary depending on the TTS model.
-
sona_speech_1
- Supports all available Voice Settings.
-
supertonic_api_1
- Supports only the
speedsetting.
All other settings will be ignored.
- Supports only the
-
sona_speech_2
- Supports all Voice Settings except
subharmonic_amplitude_control.
- Supports all Voice Settings except
-
sona_speech_2_flash
- Supports all Voice Settings except
similarity,text_guidance,subharmonic_amplitude_control.
- Supports all Voice Settings except
All Voice Settings are optional. When omitted, each model’s default values will be applied.
SupertoneError is the base class for all HTTP error responses. It has the following properties:
| Property | Type | Description |
|---|---|---|
error.message |
string |
Error message |
error.statusCode |
number |
HTTP response status code eg 404 |
error.headers |
Headers |
HTTP response headers |
error.body |
string |
HTTP body. Can be empty string if no body is returned. |
error.rawResponse |
Response |
Raw HTTP response |
error.data$ |
Optional. Some errors may contain structured data. See Error Classes. |
import { Supertone } from "@supertone/supertone";
import * as errors from "@supertone/supertone/models/errors";
const supertone = new Supertone({
apiKey: "<YOUR_API_KEY_HERE>",
});
async function run() {
try {
const result = await supertone.textToSpeech.createSpeech({
voiceId: "<id>",
apiConvertTextToSpeechUsingCharacterRequest: {
text: "<value>",
language: "ja",
},
});
console.log(result);
} catch (error) {
// The base class for HTTP error responses
if (error instanceof errors.SupertoneError) {
console.log(error.message);
console.log(error.statusCode);
console.log(error.body);
console.log(error.headers);
// Depending on the method different errors may be thrown
if (error instanceof errors.BadRequestErrorResponse) {
console.log(error.data$.status); // string
console.log(error.data$.message); // string
}
}
}
}
run();Primary error:
SupertoneError: The base class for HTTP error responses.
Less common errors (16)
Network errors:
ConnectionError: HTTP client was unable to make a request to a server.RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.RequestAbortedError: HTTP request was aborted by the client.InvalidRequestError: Any input used to create a request is invalid.UnexpectedClientError: Unrecognised or unexpected error.
Inherit from SupertoneError:
UnauthorizedErrorResponse: Unauthorized: Invalid API key. Status code401. Applicable to 10 of 15 methods.*InternalServerErrorResponse: Status code500. Applicable to 10 of 15 methods.*NotFoundErrorResponse: Status code404. Applicable to 9 of 15 methods.*BadRequestErrorResponse: Status code400. Applicable to 5 of 15 methods.*ForbiddenErrorResponse: Status code403. Applicable to 4 of 15 methods.*RequestTimeoutErrorResponse: Status code408. Applicable to 4 of 15 methods.*TooManyRequestsErrorResponse: Status code429. Applicable to 4 of 15 methods.*PaymentRequiredErrorResponse: Status code402. Applicable to 3 of 15 methods.*PayloadTooLargeErrorResponse: Payload Too Large: File size exceeds 3MB limit. Status code413. Applicable to 1 of 15 methods.*UnsupportedMediaTypeErrorResponse: Unsupported Media Type: Invalid audio file format. Status code415. Applicable to 1 of 15 methods.*ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. Seeerror.rawValuefor the raw value anderror.pretty()for a nicely formatted multi-line string.
* Check the method documentation to see if the error is applicable.
Additional example code can be found in the examples directory.