Speechall TypeScript SDK

The Speechall TypeScript SDK provides a convenient way to integrate our powerful and flexible speech-to-text API into your JavaScript and TypeScript applications. It offers type safety, ease of use, and is built on top of Axios for robust HTTP requests.

Features

• Unified Access: Access various speech-to-text (STT) providers and models through a single, consistent API.
• Type Safe: Full TypeScript support with comprehensive type definitions for all API requests and responses.
• Promise-based: Modern async/await support, built with Axios.
• File Uploads: Support for transcribing local audio files in both Node.js and browser environments.
• OpenAI Compatibility: Optional OpenAI-compatible API client for easy migration from OpenAI’s speech-to-text API.
• Custom Rules: Define and manage custom text replacement rulesets to improve transcription accuracy for specific vocabularies.

Installation

Install the SDK using npm:

npm install @speechall/sdk

Configuration

First, import the Configuration class and create an instance with your API key. You can obtain an API key from the Speechall Console.

import { Configuration } from '@speechall/sdk';

const config = new Configuration({
  apiKey: 'YOUR_API_KEY', // Replace with your actual API key
  basePath: 'https://api.speechall.com', // Default is 'https://api.speechall.com/v1'
});

You can also provide baseOptions to customize the underlying Axios client, for example, to set a custom timeout:

import { Configuration } from '@speechall/sdk';

const config = new Configuration({
  apiKey: 'YOUR_API_KEY',
  basePath: 'https://api.speechall.com',
  baseOptions: {
    timeout: 60000, // 60 seconds timeout
    headers: {
      'X-Custom-Header': 'YourValue'
    }
  }
});

Quick Start: Transcribe from URL

Here’s a simple example of how to transcribe an audio file from a URL:

import { Configuration, SpeechToTextApi } from '@speechall/sdk';

const config = new Configuration({ apiKey: 'YOUR_API_KEY' });
const speechApi = new SpeechToTextApi(config);

(async () => {
  try {
    const response = await speechApi.transcribeRemote({
      file_url: 'https://example.com/audio.mp3', // Replace with your audio URL
      model: 'openai.whisper-1', // Specify the model
      language: 'en', // Optional: specify language
    });
    console.log('Transcription:', response.data.text);
  } catch (error) {
    console.error('Transcription failed:', error.response ? error.response.data : error.message);
  }
})();

API Clients

The SDK provides several API client classes:

• SpeechToTextApi: For core transcription functionalities like remote URL transcription and direct file uploads.
• OpenAICompatibleSpeechToTextApi: Offers an interface compatible with OpenAI’s audio transcription API.
• ReplacementRulesApi: Allows programmatic management of custom text replacement rulesets.

More Examples & Advanced Usage

Transcribing a Local File

Browser Environment:

In a browser, you can easily get a File object from an <input type="file"> element to use with the transcribe method.

// Assuming 'fileInput' is an HTMLInputElement <input type="file" id="fileInput">
// const fileInput = document.getElementById('fileInput') as HTMLInputElement;
// const audioFile = fileInput.files[0];

if (audioFile) { // Ensure audioFile is defined
  const config = new Configuration({ apiKey: 'YOUR_API_KEY' });
  const speechApi = new SpeechToTextApi(config);

  speechApi.transcribe('openai.whisper-1', audioFile)
    .then(response => console.log('Transcription:', response.data.text))
    .catch(error => console.error('Browser file transcription failed:', error.response ? error.response.data : error.message));
}

Node.js Environment:

Transcribing local files in Node.js can involve handling Buffers or Streams and constructing FormData. For detailed examples and best practices for Node.js, please refer to the SDK’s GitHub README.

Advanced Transcription Options

The SDK supports various advanced transcription features like diarization, custom vocabularies, punctuation control, timestamp granularity, and more. For a full list of options and usage examples, please see the Advanced Options section in our GitHub README.

OpenAI-Compatible API

If you’re migrating from OpenAI or prefer its API structure, the SDK includes an OpenAI-compatible client. Learn more in the OpenAI-Compatible API section on GitHub.

Custom Replacement Rulesets

Create and manage text replacement rulesets programmatically to automatically correct or reformat parts of your transcriptions. Detailed examples are available in the Custom Replacement Rules section on GitHub.

Listing Available Models

You can fetch a list of all available models, their capabilities, and pricing. See the List Available Models section on GitHub for details.

Error Handling

Errors returned by the API, especially 4xx and 5xx responses, will typically be AxiosError instances. You can inspect error.response.data for specific error messages from the API. For detailed error handling strategies and examples, refer to the Error Handling section in the GitHub README.

Types

The SDK is written in TypeScript and includes comprehensive type definitions for all API requests, responses, and models, ensuring type safety and providing excellent autocompletion. For a deeper understanding of available types, please consult the SDK source code and its README on GitHub.

Next Steps

For the most detailed information, advanced use cases, and contributions:

• Visit the Official SDK GitHub Repository.
• Refer to the Main API Reference (OpenAPI) for underlying API details.

If you have any questions or encounter issues, feel free to open an issue on the GitHub repository or contact our support.