@breeze.blue/sdk 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.21.0
+
+- Support request-scoped speaker boost across HTTP and realtime TTS, with performance instructions taking priority when guidance exceeds 1.
+- Serialize documented request controls only.
+- Honor the clone reference-denoising switch (disabled by default).
+- Read the account's plan, billing period, monthly credits, saved voice and project limits and generation concurrency with `client.account.entitlements()`, typed as `Entitlements`.
+- Breaking: remove `voices.getSettings(...)`, `voices.editSettings(...)`, the `VoiceSettings` type and `Voice.settings`; the voice settings endpoints are removed.
+- TTS guidance no longer inherits saved voice settings; omitted `voiceSettings.guidanceScale` uses the default 1.
+- Breaking: remove `voices.favorite(...)` and `voices.unfavorite(...)`; the favorite endpoints are removed. `isFavorited` and the `favoritesOnly` filter remain.
+
 ## 0.20.1
 
 - Studio list methods type their filters: `StudioProjectListParams`, `StudioChapterListParams`, `StudioClipListParams` and `StudioFileListParams`.

package/README.md

@@ -7,6 +7,8 @@ models, and account usage.
 The root entrypoint is safe to import in Node, browser, and edge runtimes. Local
 audio playback helpers live in the Node-only `@breeze.blue/sdk/node` subpath.
 
+Guidance accepts 1–10; when omitted, the default 1 is used. HTTP speed and volume are per request and default to 1. Use `voiceSettings: { useSpeakerBoost: true }` for closer similarity to the reference voice (default false): it is ignored with non-empty instructions and guidance above 1, and otherwise instructions are not used. Realtime fixes boost at session creation; create a new session to change instructions while boost applies. Pass `removeBackgroundNoise: true` to denoise a clone sample (default false).
+
 ## Install
 
 ```sh
@@ -421,7 +423,6 @@ const taggedFavorites = await client.voices.search({
 const firstVoiceId = voices.voices[0].voiceId;
 
 const voice = await client.voices.get(firstVoiceId);
-const settings = await client.voices.getSettings(firstVoiceId);
 
 const randomVoice = await client.voices.random();
 console.log(randomVoice.voiceId, randomVoice.name);
@@ -563,7 +564,7 @@ const saved = await client.voices.savePreview({
 });
 ```
 
-Edit, tune settings, or delete a saved voice:
+Edit or delete a saved voice:
 
 ```ts
 await client.voices.edit(saved.voiceId, {
@@ -573,11 +574,8 @@ await client.voices.edit(saved.voiceId, {
 });
 // null clears nullable metadata; [] clears tone. Omitted fields remain unchanged.
 await client.voices.edit(saved.voiceId, { accent: null, tone: [] });
-await client.voices.editSettings(saved.voiceId, { guidanceScale: 1.2 });
-await client.voices.favorite(firstVoiceId);
 await client.voices.updateTags(firstVoiceId, ["narration", "novel=三体"]);
 await client.voices.updateTags(firstVoiceId, []); // Resume owner tag inheritance.
-await client.voices.unfavorite(firstVoiceId);
 await client.voices.delete(saved.voiceId);
 ```
 
@@ -592,6 +590,8 @@ language-to-accent cascade at runtime.
 ```ts
 const models = await client.models.list();
 const balance = await client.account.balance();
+const entitlements = await client.account.entitlements();
+console.log(entitlements.planCode, entitlements.maxConcurrentGenerations);
 const currentKey = (await client.account.currentApiKey()).apiKey;
 console.log(currentKey.status, currentKey.creditRemaining);
 const usage = await client.account.usage({ days: 7 });
@@ -640,9 +640,9 @@ Clone previews automatically generate a short script in the detected reference a
 
 ### HTTP TTS speed
 
-Pass `voiceSettings: { speed: 1.25 }` to control speech speed without changing pitch, from 0.5 to 2.0. Omission always means 1.0; saved voice speed is not inherited. Sync, async and HTTP streaming support this parameter; Realtime does not.
+Pass `voiceSettings: { speed: 1.25 }` to control speech speed without changing pitch, from 0.5 to 2.0. Omission always means 1.0. Sync, async and HTTP streaming support this parameter; Realtime does not.
 
-Pass `voiceSettings: { volume: 1.5 }` to apply a request-level linear amplitude multiplier. Values range from 0.01 to 2.0; omission means 1.0. Values above 1.0 may clip peaks. Sync, async and HTTP streaming support this parameter; it does not change saved voice settings or apply to Realtime.
+Pass `voiceSettings: { volume: 1.5 }` to apply a request-level linear amplitude multiplier. Values range from 0.01 to 2.0; omission means 1.0. Values above 1.0 may clip peaks. Sync, async and HTTP streaming support this parameter; Realtime does not.
 
 ## Word timing
 

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { StudioResource } from "./studio.js";
 import { SpeechTimingStream, type SpeechWithTimestamps } from "./timestamps.js";
 import { AudioResponse } from "./audio.js";
-import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, CurrentApiKeyResponse, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, RealtimeTextToSpeechConnectOptions, RealtimeTextToSpeechEvent, RealtimeTextToSpeechManagedConnectOptions, RealtimeTextToSpeechMessage, RealtimeTextToSpeechSession, RealtimeTextToSpeechSessionRequest, SavedVoice, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceDesignStreamRequest, VoiceEditRequest, VoiceList, VoiceLocalizeJob, VoiceLocalizePreviewRequest, VoiceLocalizePreviewStatus, VoiceRemixPreviewRequest, VoiceRemixPrepareRequest, VoiceRemixPresets, VoiceRemixPreparation, VoiceRemixJob, VoiceRemixPreviewStatus, VoiceMetadataOptions, VoiceRandomParams, VoiceSearchParams, VoiceSettings } from "./types.js";
+import type { AudioRequestOptions, BreezeBlueWebSocket, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, CurrentApiKeyResponse, Entitlements, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, RealtimeTextToSpeechConnectOptions, RealtimeTextToSpeechEvent, RealtimeTextToSpeechManagedConnectOptions, RealtimeTextToSpeechMessage, RealtimeTextToSpeechSession, RealtimeTextToSpeechSessionRequest, SavedVoice, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsEnhanceRequest, TtsEnhanceResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceDesignStreamRequest, VoiceEditRequest, VoiceList, VoiceLocalizeJob, VoiceLocalizePreviewRequest, VoiceLocalizePreviewStatus, VoiceRemixPreviewRequest, VoiceRemixPrepareRequest, VoiceRemixPresets, VoiceRemixPreparation, VoiceRemixJob, VoiceRemixPreviewStatus, VoiceMetadataOptions, VoiceRandomParams, VoiceSearchParams } from "./types.js";
 export declare class BreezeBlueClient {
     readonly apiKey: string | undefined;
     readonly baseUrl: string;
@@ -232,11 +232,7 @@ declare class VoicesResource {
     metadataOptions(options?: RequestOptions): Promise<VoiceMetadataOptions>;
     edit(voiceId: string, request: VoiceEditRequest, options?: RequestOptions): Promise<GenericStatus>;
     updateTags(voiceId: string, tags: string[], options?: RequestOptions): Promise<Voice>;
-    favorite(voiceId: string, options?: RequestOptions): Promise<Voice>;
-    unfavorite(voiceId: string, options?: RequestOptions): Promise<Voice>;
     delete(voiceId: string, options?: RequestOptions): Promise<GenericStatus>;
-    getSettings(voiceId: string, options?: RequestOptions): Promise<Required<VoiceSettings>>;
-    editSettings(voiceId: string, settings: VoiceSettings, options?: RequestOptions): Promise<Required<VoiceSettings>>;
     /**
      * Generate a clone preview from a single audio sample. Returns a
      * `generatedVoiceId`; call {@link savePreview} after the user accepts
@@ -298,6 +294,8 @@ declare class AccountResource {
     private readonly client;
     constructor(client: BreezeBlueClient);
     balance(options?: RequestOptions): Promise<Balance>;
+    /** Return the account's plan, billing period and generation limits. */
+    entitlements(options?: RequestOptions): Promise<Entitlements>;
     /** Return the authenticating API key and its current Key Budget counters. */
     currentApiKey(options?: RequestOptions): Promise<CurrentApiKeyResponse>;
     usage(params?: UsageParams, options?: RequestOptions): Promise<Usage>;

package/dist/client.js

@@ -105,6 +105,18 @@ export class BreezeBlueClient {
         return headers;
     }
 }
+function ttsRequest(request) {
+    const { text, modelId, languageCode, instructions, voiceSettings } = request;
+    return {
+        text, modelId, languageCode, instructions,
+        voiceSettings: voiceSettings == null ? voiceSettings : {
+            guidanceScale: voiceSettings.guidanceScale,
+            useSpeakerBoost: voiceSettings.useSpeakerBoost,
+            speed: voiceSettings.speed,
+            volume: voiceSettings.volume,
+        },
+    };
+}
 class TextToSpeechResource {
     client;
     realtime;
@@ -113,26 +125,25 @@ class TextToSpeechResource {
         this.realtime = new RealtimeTextToSpeechResource(client);
     }
     convert(voiceId, request, options = {}) {
-        return this.client.requestAudio("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat }, request, options);
+        return this.client.requestAudio("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat }, ttsRequest(request), options);
     }
     createJob(voiceId, request, options = {}) {
-        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat, delivery: "async" }, request, options);
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}`, { outputFormat: options.outputFormat, delivery: "async" }, ttsRequest(request), options);
     }
     createJobWithTimestamps(voiceId, request, options = {}) {
-        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat, delivery: "async" }, request, options);
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat, delivery: "async" }, ttsRequest(request), options);
     }
     stream(voiceId, request, options = {}) {
         return this.client.requestAudio("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream`, {
             outputFormat: options.outputFormat,
-            optimizeStreamingLatency: options.optimizeStreamingLatency,
             enableLogging: options.enableLogging,
-        }, request, options);
+        }, ttsRequest(request), options);
     }
     convertWithTimestamps(voiceId, request, options = {}) {
-        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat }, request, options);
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/with-timestamps`, { outputFormat: options.outputFormat }, ttsRequest(request), options);
     }
     async streamWithTimestamps(voiceId, request, options = {}) {
-        const response = await this.client.request("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream/with-timestamps`, { outputFormat: options.outputFormat, optimizeStreamingLatency: options.optimizeStreamingLatency, enableLogging: options.enableLogging }, request, options);
+        const response = await this.client.request("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream/with-timestamps`, { outputFormat: options.outputFormat, enableLogging: options.enableLogging }, { ...ttsRequest(request), timestampMode: request.timestampMode }, options);
         return new SpeechTimingStream(response);
     }
     enhance(request, options) {
@@ -145,7 +156,14 @@ class RealtimeTextToSpeechResource {
         this.client = client;
     }
     createSession(voiceId, request = {}, options) {
-        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/realtime-sessions`, undefined, request, options);
+        return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/realtime-sessions`, undefined, {
+            modelId: request.modelId,
+            languageCode: request.languageCode,
+            instructions: request.instructions,
+            voiceSettings: request.voiceSettings == null ? request.voiceSettings : { guidanceScale: request.voiceSettings.guidanceScale, useSpeakerBoost: request.voiceSettings.useSpeakerBoost },
+            inactivityTimeoutSeconds: request.inactivityTimeoutSeconds,
+            enableLogging: request.enableLogging,
+        }, options);
     }
     async connect(voiceId, options = {}) {
         if ((options.clientSecret !== undefined ||
@@ -1543,24 +1561,9 @@ class VoicesResource {
         const result = await this.client.requestJson("PUT", `/v1/voices/${encodeURIComponent(voiceId)}/tags`, undefined, { tags }, options);
         return stripHiddenVoiceFields(result);
     }
-    async favorite(voiceId, options) {
-        const result = await this.client.requestJson("PUT", `/v1/voices/${encodeURIComponent(voiceId)}/favorite`, undefined, undefined, options);
-        return stripHiddenVoiceFields(result);
-    }
-    async unfavorite(voiceId, options) {
-        const result = await this.client.requestJson("DELETE", `/v1/voices/${encodeURIComponent(voiceId)}/favorite`, undefined, undefined, options);
-        return stripHiddenVoiceFields(result);
-    }
     delete(voiceId, options) {
         return this.client.requestJson("DELETE", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
     }
-    // -- voice settings ---------------------------------------------------
-    getSettings(voiceId, options) {
-        return this.client.requestJson("GET", `/v1/voices/${encodeURIComponent(voiceId)}/settings`, undefined, undefined, options);
-    }
-    editSettings(voiceId, settings, options) {
-        return this.client.requestJson("PATCH", `/v1/voices/${encodeURIComponent(voiceId)}/settings`, undefined, settings, options);
-    }
     // -- two-step preview → save flow -------------------------------------
     /**
      * Generate a clone preview from a single audio sample. Returns a
@@ -1576,14 +1579,16 @@ class VoicesResource {
      * {@link savePreview}.
      */
     createDesignPreview(request, options = {}) {
-        return this.client.requestJson("POST", "/v1/voice-previews/design", { outputFormat: options.outputFormat }, request, options);
+        const { voiceDescription, text, modelId, languageCode, guidanceScale, previewCount } = request;
+        return this.client.requestJson("POST", "/v1/voice-previews/design", { outputFormat: options.outputFormat }, { voiceDescription, text, modelId, languageCode, guidanceScale, previewCount }, options);
     }
     /**
      * Generate exactly one voice design preview as live 24 kHz mono PCM.
      * A clean end means `generatedVoiceId` is ready for {@link savePreview}.
      */
     streamDesignPreview(request, options) {
-        return this.client.requestAudio("POST", "/v1/voice-previews/design/stream", undefined, request, options);
+        return this.client.requestAudio("POST", "/v1/voice-previews/design/stream", undefined, { voiceDescription: request.voiceDescription, text: request.text, modelId: request.modelId,
+            languageCode: request.languageCode, guidanceScale: request.guidanceScale }, options);
     }
     /** List curated voice changes and their sample recordings. */
     listRemixPresets(options) {
@@ -1631,7 +1636,6 @@ class VoicesResource {
             tags: request.tags,
             primaryCategoryCode: request.primaryCategoryCode,
             visibility: request.visibility,
-            playedNotSelectedVoiceIds: request.playedNotSelectedVoiceIds,
             languageCode: request.languageCode,
             gender: request.gender,
             age: request.age,
@@ -1676,6 +1680,10 @@ class AccountResource {
     balance(options) {
         return this.client.requestJson("GET", "/v1/balance", undefined, undefined, options);
     }
+    /** Return the account's plan, billing period and generation limits. */
+    entitlements(options) {
+        return this.client.requestJson("GET", "/v1/entitlements", undefined, undefined, options);
+    }
     /** Return the authenticating API key and its current Key Budget counters. */
     currentApiKey(options) {
         return this.client.requestJson("GET", "/v1/api-keys/current", undefined, undefined, options);
@@ -1778,17 +1786,10 @@ function clonePreviewForm(request) {
     if (request.name != null && typeof request.name !== "string") {
         throw new BreezeBlueConfigurationError("Clone name must be a string or null.");
     }
-    if (request.removeBackgroundNoise) {
-        throw new BreezeBlueConfigurationError("removeBackgroundNoise is not supported by the Breeze Developer API.");
-    }
-    for (const field of ["text", "instructions", "languageCode", "previewLanguageCode"]) {
-        if (field in request) {
-            throw new BreezeBlueConfigurationError(`Clone previews do not accept ${field}; the script and language are generated automatically.`);
-        }
-    }
     const form = new FormData();
     appendOptional(form, "name", request.name ?? undefined);
     appendOptional(form, "description", request.description);
+    appendOptional(form, "remove_background_noise", request.removeBackgroundNoise ?? false);
     for (const file of normalizeFiles(request.file, request.files, { required: true })) {
         appendFile(form, "files", file);
     }

package/dist/types.d.ts

@@ -23,7 +23,6 @@ export interface AudioRequestOptions extends RequestOptions {
     outputFormat?: string;
 }
 export interface StreamTextToSpeechOptions extends AudioRequestOptions {
-    optimizeStreamingLatency?: number;
     enableLogging?: boolean;
 }
 export type BreezeBlueWebSocketConstructor = new (url: string, protocols?: string | string[]) => BreezeBlueWebSocket;
@@ -42,9 +41,7 @@ export interface RealtimeTextToSpeechSessionRequest {
     modelId?: string;
     languageCode?: string;
     instructions?: string;
-    voiceSettings?: {
-        guidanceScale?: number | null;
-    };
+    voiceSettings?: Pick<TtsVoiceSettings, "guidanceScale" | "useSpeakerBoost">;
     inactivityTimeoutSeconds?: number;
     enableLogging?: boolean;
 }
@@ -226,18 +223,15 @@ export interface RealtimeTextToSpeechAudioMessage {
     audio: Uint8Array;
 }
 export type RealtimeTextToSpeechMessage = RealtimeTextToSpeechEvent | RealtimeTextToSpeechAudioMessage;
-export interface VoiceSettings {
-    stability?: number;
-    similarityBoost?: number;
-    style?: number;
+/** Per-request controls. */
+export interface TtsVoiceSettings {
+    /** Generation guidance strength (1–10). Omitted or null uses the default 1. */
+    guidanceScale?: number | null;
+    /** Default false. Ignored with non-empty instructions and guidanceScale > 1; otherwise instructions are not used. */
     useSpeakerBoost?: boolean;
-    /** Request-only, pitch-preserving HTTP TTS speed (0.5–2.0). Omitted means 1.0. */
+    /** Pitch-preserving speed (0.5–2.0). */
     speed?: number;
-    guidanceScale?: number | null;
-}
-/** Request-only HTTP TTS settings. Volume is a linear amplitude multiplier. */
-export interface TtsVoiceSettings extends VoiceSettings {
-    /** Linear amplitude multiplier (0.01–2.0); omitted means 1.0. */
+    /** Linear amplitude multiplier (0.01–2.0). */
     volume?: number;
 }
 export interface PronunciationDictionaryLocator {
@@ -250,14 +244,6 @@ export interface TextToSpeechRequest {
     languageCode?: string;
     instructions?: string;
     voiceSettings?: TtsVoiceSettings;
-    seed?: number;
-    pronunciationDictionaryLocators?: PronunciationDictionaryLocator[];
-    previousText?: string;
-    nextText?: string;
-    previousRequestIds?: string[];
-    nextRequestIds?: string[];
-    applyTextNormalization?: string;
-    applyLanguageTextNormalization?: boolean;
 }
 export interface TtsEnhanceRequest {
     instruction: string;
@@ -315,7 +301,6 @@ export interface Voice {
     tags: string[];
     isFavorited: boolean;
     previewUrl?: string | null;
-    settings: Required<VoiceSettings>;
     description?: string | null;
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
@@ -430,10 +415,6 @@ export interface VoiceDesignRequest {
     text?: string;
     modelId?: string;
     languageCode?: VoiceLanguageCode;
-    autoGenerateText?: boolean;
-    loudness?: number;
-    quality?: number;
-    seed?: number;
     guidanceScale?: number | null;
     previewCount?: number;
 }
@@ -528,7 +509,6 @@ export interface SaveVoiceRequest {
     tags?: string[];
     primaryCategoryCode?: string;
     visibility?: "private" | "public" | string;
-    playedNotSelectedVoiceIds?: string[];
     languageCode: VoiceLanguageCode;
     gender?: VoiceGender | null;
     age?: VoiceAge | null;
@@ -588,6 +568,20 @@ export interface Balance {
     topups: BalanceTopup[];
     [key: string]: unknown;
 }
+export interface Entitlements {
+    planCode: string;
+    status: string;
+    billingInterval: string | null;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    monthlyCreativeCredits: number;
+    savedVoiceLimit: number;
+    savedProjectLimit: number;
+    maxConcurrentGenerations: number;
+    studioLongFormAccess: boolean;
+    commercialUseAllowed: boolean;
+}
 export interface CurrentApiKey {
     id: string;
     name: string;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.20.1";
+export declare const SDK_VERSION = "0.21.0";
 export declare const SDK_NAME = "@breeze.blue/sdk";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.20.1";
+export const SDK_VERSION = "0.21.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breezeblue.ai>",