@cartesia/cartesia-js 2.2.9 → 3.0.0-b11

package/src/resources/infill.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { type Uploadable } from '../core/uploads';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { multipartFormRequestOptions } from '../internal/uploads';
+
+export class Infill extends APIResource {
+  /**
+   * Generate audio that smoothly connects two existing audio segments. This is
+   * useful for inserting new speech between existing speech segments while
+   * maintaining natural transitions.
+   *
+   * **The cost is 1 credit per character of the infill text plus a fixed cost of 300
+   * credits.**
+   *
+   * At least one of `left_audio` or `right_audio` must be provided.
+   *
+   * As with all generative models, there's some inherent variability, but here's
+   * some tips we recommend to get the best results from infill:
+   *
+   * - Use longer infill transcripts
+   *   - This gives the model more flexibility to adapt to the rest of the audio
+   * - Target natural pauses in the audio when deciding where to clip
+   *   - This means you don't need word-level timestamps to be as precise
+   * - Clip right up to the start and end of the audio segment you want infilled,
+   *   keeping as much silence in the left/right audio segments as possible
+   *   - This helps the model generate more natural transitions
+   */
+  create(body: InfillCreateParams, options?: RequestOptions): APIPromise<Response> {
+    return this._client.post(
+      '/infill/bytes',
+      multipartFormRequestOptions(
+        {
+          body,
+          ...options,
+          headers: buildHeaders([{ Accept: 'audio/wav' }, options?.headers]),
+          __binaryResponse: true,
+        },
+        this._client,
+      ),
+    );
+  }
+}
+
+export type OutputFormatContainer = 'raw' | 'wav' | 'mp3';
+
+export type RawEncoding = 'pcm_f32le' | 'pcm_s16le' | 'pcm_mulaw' | 'pcm_alaw';
+
+export interface InfillCreateParams {
+  /**
+   * The language of the transcript
+   */
+  language?: string;
+
+  left_audio?: Uploadable;
+
+  /**
+   * The ID of the model to use for generating audio. Any model other than the first
+   * `"sonic"` model is supported.
+   */
+  model_id?: string;
+
+  /**
+   * Required for `mp3` containers.
+   */
+  'output_format[bit_rate]'?: number | null;
+
+  /**
+   * The format of the output audio
+   */
+  'output_format[container]'?: OutputFormatContainer;
+
+  /**
+   * Required for `raw` and `wav` containers.
+   */
+  'output_format[encoding]'?: RawEncoding | null;
+
+  /**
+   * The sample rate of the output audio
+   */
+  'output_format[sample_rate]'?: 8000 | 16000 | 22050 | 24000 | 44100 | 48000;
+
+  right_audio?: Uploadable;
+
+  /**
+   * The infill text to generate
+   */
+  transcript?: string;
+
+  /**
+   * The ID of the voice to use for generating audio
+   */
+  voice_id?: string;
+}
+
+export declare namespace Infill {
+  export {
+    type OutputFormatContainer as OutputFormatContainer,
+    type RawEncoding as RawEncoding,
+    type InfillCreateParams as InfillCreateParams,
+  };
+}

package/src/resources/pronunciation-dicts.ts

@@ -0,0 +1,152 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class PronunciationDicts extends APIResource {
+  /**
+   * Create a new pronunciation dictionary
+   */
+  create(body: PronunciationDictCreateParams, options?: RequestOptions): APIPromise<PronunciationDict> {
+    return this._client.post('/pronunciation-dicts/', { body, ...options });
+  }
+
+  /**
+   * Retrieve a specific pronunciation dictionary by ID
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<PronunciationDict> {
+    return this._client.get(path`/pronunciation-dicts/${id}`, options);
+  }
+
+  /**
+   * Update a pronunciation dictionary
+   */
+  update(
+    id: string,
+    body: PronunciationDictUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<PronunciationDict> {
+    return this._client.patch(path`/pronunciation-dicts/${id}`, { body, ...options });
+  }
+
+  /**
+   * List all pronunciation dictionaries for the authenticated user
+   */
+  list(
+    query: PronunciationDictListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PronunciationDictsCursorIDPage, PronunciationDict> {
+    return this._client.getAPIList('/pronunciation-dicts/', CursorIDPage<PronunciationDict>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Delete a pronunciation dictionary
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/pronunciation-dicts/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type PronunciationDictsCursorIDPage = CursorIDPage<PronunciationDict>;
+
+/**
+ * A dictionary of text-to-alias mappings
+ */
+export interface PronunciationDict {
+  /**
+   * Unique identifier for the pronunciation dictionary
+   */
+  id: string;
+
+  /**
+   * ISO 8601 timestamp of when the dictionary was created
+   */
+  created_at: string;
+
+  /**
+   * List of text-to-pronunciation mappings
+   */
+  items: Array<PronunciationDictItem>;
+
+  /**
+   * Name of the pronunciation dictionary
+   */
+  name: string;
+
+  /**
+   * ID of the user who owns this dictionary
+   */
+  owner_id: string;
+
+  /**
+   * Whether this dictionary is pinned for the user
+   */
+  pinned: boolean;
+}
+
+/**
+ * A pronunciation dictionary item mapping text to a custom pronunciation
+ */
+export interface PronunciationDictItem {
+  /**
+   * A phonetic representation or text to be said in place of the original text
+   */
+  alias: string;
+
+  /**
+   * The original text to be replaced
+   */
+  text: string;
+}
+
+export interface PronunciationDictCreateParams {
+  /**
+   * Name for the new pronunciation dictionary
+   */
+  name: string;
+
+  /**
+   * Optional initial list of pronunciation mappings
+   */
+  items?: Array<PronunciationDictItem> | null;
+}
+
+export interface PronunciationDictUpdateParams {
+  /**
+   * Updated list of pronunciation mappings
+   */
+  items?: Array<PronunciationDictItem> | null;
+
+  /**
+   * New name for the pronunciation dictionary
+   */
+  name?: string | null;
+}
+
+export interface PronunciationDictListParams extends CursorIDPageParams {
+  /**
+   * The number of dictionaries to return per page, ranging between 1 and 100.
+   */
+  limit?: number | null;
+}
+
+export declare namespace PronunciationDicts {
+  export {
+    type PronunciationDict as PronunciationDict,
+    type PronunciationDictItem as PronunciationDictItem,
+    type PronunciationDictsCursorIDPage as PronunciationDictsCursorIDPage,
+    type PronunciationDictCreateParams as PronunciationDictCreateParams,
+    type PronunciationDictUpdateParams as PronunciationDictUpdateParams,
+    type PronunciationDictListParams as PronunciationDictListParams,
+  };
+}

package/src/resources/stt.ts

@@ -0,0 +1,232 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { type Uploadable } from '../core/uploads';
+import { RequestOptions } from '../internal/request-options';
+import { multipartFormRequestOptions } from '../internal/uploads';
+
+export class Stt extends APIResource {
+  /**
+   * Transcribes audio files into text using Cartesia's Speech-to-Text API.
+   *
+   * Upload an audio file and receive a complete transcription response. Supports
+   * arbitrarily long audio files with automatic intelligent chunking for longer
+   * audio.
+   *
+   * **Supported audio formats:** flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav,
+   * webm
+   *
+   * **Response format:** Returns JSON with transcribed text, duration, and language.
+   * Include `timestamp_granularities: ["word"]` to get word-level timestamps.
+   * **Pricing:** Batch transcription is priced at **1 credit per 2 seconds** of
+   * audio processed.
+   *
+   * <Note>
+   * For migrating from the OpenAI SDK, see our [OpenAI Whisper to Cartesia Ink Migration Guide](/api-reference/stt/migrate-from-open-ai).
+   * </Note>
+   */
+  transcribe(params: SttTranscribeParams, options?: RequestOptions): APIPromise<SttTranscribeResponse> {
+    const { encoding, sample_rate, ...body } = params;
+    return this._client.post(
+      '/stt',
+      multipartFormRequestOptions({ query: { encoding, sample_rate }, body, ...options }, this._client),
+    );
+  }
+}
+
+export interface SttTranscribeResponse {
+  /**
+   * The transcribed text.
+   */
+  text: string;
+
+  /**
+   * The duration of the input audio in seconds.
+   */
+  duration?: number | null;
+
+  /**
+   * The specified language of the input audio.
+   */
+  language?: string | null;
+
+  /**
+   * Word-level timestamps showing the start and end time of each word. Only included
+   * when `[word]` is passed into `timestamp_granularities[]`.
+   */
+  words?: Array<SttTranscribeResponse.Word> | null;
+}
+
+export namespace SttTranscribeResponse {
+  export interface Word {
+    /**
+     * End time of the word in seconds.
+     */
+    end: number;
+
+    /**
+     * Start time of the word in seconds.
+     */
+    start: number;
+
+    /**
+     * The transcribed word.
+     */
+    word: string;
+  }
+}
+
+export interface SttTranscribeParams {
+  /**
+   * Query param: The encoding format to process the audio as. If not specified, the
+   * audio file will be decoded automatically.
+   *
+   * **Supported formats:**
+   *
+   * - `pcm_s16le` - 16-bit signed integer PCM, little-endian (recommended for best
+   *   performance)
+   * - `pcm_s32le` - 32-bit signed integer PCM, little-endian
+   * - `pcm_f16le` - 16-bit floating point PCM, little-endian
+   * - `pcm_f32le` - 32-bit floating point PCM, little-endian
+   * - `pcm_mulaw` - 8-bit μ-law encoded PCM
+   * - `pcm_alaw` - 8-bit A-law encoded PCM
+   */
+  encoding?: 'pcm_s16le' | 'pcm_s32le' | 'pcm_f16le' | 'pcm_f32le' | 'pcm_mulaw' | 'pcm_alaw' | null;
+
+  /**
+   * Query param: The sample rate of the audio in Hz.
+   */
+  sample_rate?: number | null;
+
+  /**
+   * Body param
+   */
+  file?: Uploadable;
+
+  /**
+   * Body param: The language of the input audio in ISO-639-1 format. Defaults to
+   * `en`.
+   */
+  language?:
+    | 'en'
+    | 'zh'
+    | 'de'
+    | 'es'
+    | 'ru'
+    | 'ko'
+    | 'fr'
+    | 'ja'
+    | 'pt'
+    | 'tr'
+    | 'pl'
+    | 'ca'
+    | 'nl'
+    | 'ar'
+    | 'sv'
+    | 'it'
+    | 'id'
+    | 'hi'
+    | 'fi'
+    | 'vi'
+    | 'he'
+    | 'uk'
+    | 'el'
+    | 'ms'
+    | 'cs'
+    | 'ro'
+    | 'da'
+    | 'hu'
+    | 'ta'
+    | 'no'
+    | 'th'
+    | 'ur'
+    | 'hr'
+    | 'bg'
+    | 'lt'
+    | 'la'
+    | 'mi'
+    | 'ml'
+    | 'cy'
+    | 'sk'
+    | 'te'
+    | 'fa'
+    | 'lv'
+    | 'bn'
+    | 'sr'
+    | 'az'
+    | 'sl'
+    | 'kn'
+    | 'et'
+    | 'mk'
+    | 'br'
+    | 'eu'
+    | 'is'
+    | 'hy'
+    | 'ne'
+    | 'mn'
+    | 'bs'
+    | 'kk'
+    | 'sq'
+    | 'sw'
+    | 'gl'
+    | 'mr'
+    | 'pa'
+    | 'si'
+    | 'km'
+    | 'sn'
+    | 'yo'
+    | 'so'
+    | 'af'
+    | 'oc'
+    | 'ka'
+    | 'be'
+    | 'tg'
+    | 'sd'
+    | 'gu'
+    | 'am'
+    | 'yi'
+    | 'lo'
+    | 'uz'
+    | 'fo'
+    | 'ht'
+    | 'ps'
+    | 'tk'
+    | 'nn'
+    | 'mt'
+    | 'sa'
+    | 'lb'
+    | 'my'
+    | 'bo'
+    | 'tl'
+    | 'mg'
+    | 'as'
+    | 'tt'
+    | 'haw'
+    | 'ln'
+    | 'ha'
+    | 'ba'
+    | 'jw'
+    | 'su'
+    | 'yue'
+    | null;
+
+  /**
+   * Body param: ID of the model to use for transcription. Use `ink-whisper` for the
+   * latest Cartesia Whisper model.
+   */
+  model?: string;
+
+  /**
+   * Body param: The timestamp granularities to populate for this transcription.
+   * Currently only `word` level timestamps are supported.
+   */
+  timestamp_granularities?: Array<'word'> | null;
+}
+
+export declare namespace Stt {
+  export {
+    type SttTranscribeResponse as SttTranscribeResponse,
+    type SttTranscribeParams as SttTranscribeParams,
+  };
+}

package/src/resources/top-level.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export interface GetStatusResponse {
+  ok: boolean;
+
+  version: string;
+}
+
+export declare namespace TopLevel {
+  export { type GetStatusResponse as GetStatusResponse };
+}

package/src/resources/tts/index.ts

@@ -0,0 +1,14 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  TTS,
+  type GenerationConfig,
+  type GenerationRequest,
+  type ModelSpeed,
+  type RawOutputFormat,
+  type VoiceSpecifier,
+  type WebsocketClientEvent,
+  type WebsocketResponse,
+  type TTSGenerateParams,
+  type TTSGenerateSseParams,
+} from './tts';

package/src/resources/tts/internal-base.ts

@@ -0,0 +1,89 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as TTSAPI from './tts';
+import { Cartesia } from '../../client';
+
+import { EventEmitter } from '../../core/EventEmitter';
+import { CartesiaError } from '../../core/error';
+
+export class WebSocketError extends CartesiaError {
+  /**
+   * The error data that the API sent back in an error event.
+   */
+  error?: TTSAPI.WebsocketResponse.Error | undefined;
+
+  constructor(message: string, event: TTSAPI.WebsocketResponse.Error | null) {
+    super(message);
+
+    this.error = event ?? undefined;
+  }
+}
+
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+type WebsocketEvents = Simplify<
+  {
+    event: (event: TTSAPI.WebsocketResponse) => void;
+    error: (error: WebSocketError) => void;
+  } & {
+    [EventType in Exclude<NonNullable<TTSAPI.WebsocketResponse['type']>, 'error'>]: (
+      event: Extract<TTSAPI.WebsocketResponse, { type?: EventType }>,
+    ) => unknown;
+  }
+>;
+
+export abstract class TTSEmitter extends EventEmitter<WebsocketEvents> {
+  /**
+   * Send an event to the API.
+   */
+  abstract send(event: TTSAPI.WebsocketClientEvent): void;
+
+  /**
+   * Close the websocket connection.
+   */
+  abstract close(props?: { code: number; reason: string }): void;
+
+  protected _onError(event: null, message: string, cause: any): void;
+  protected _onError(event: TTSAPI.WebsocketResponse.Error, message?: string | undefined): void;
+  protected _onError(
+    event: TTSAPI.WebsocketResponse.Error | null,
+    message?: string | undefined,
+    cause?: any,
+  ): void {
+    message = message ?? safeJSONStringify(event) ?? 'unknown error';
+
+    if (!this._hasListener('error')) {
+      const error = new WebSocketError(
+        message +
+          `\n\nTo resolve these unhandled rejection errors you should bind an \`error\` callback, e.g. \`ws.on('error', (error) => ...)\` `,
+        event,
+      );
+      // @ts-ignore
+      error.cause = cause;
+      Promise.reject(error);
+      return;
+    }
+
+    const error = new WebSocketError(message, event);
+    // @ts-ignore
+    error.cause = cause;
+
+    this._emit('error', error);
+  }
+}
+
+export function buildURL(client: Cartesia): URL {
+  const path = '/tts/websocket';
+  const baseURL = client.baseURL;
+  const url = new URL(baseURL + (baseURL.endsWith('/') ? path.slice(1) : path));
+  url.protocol = 'wss';
+  return url;
+}
+
+function safeJSONStringify(value: unknown): string | null {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+}