sonilo 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -55,6 +55,12 @@ interface TextToMusicParams {
     mode?: "stream" | "async";
     /** Container for the async result. `wav` requires `mode: "async"`. Defaults to m4a server-side. */
     outputFormat?: "m4a" | "wav";
+    /** How many distinct music variants to generate in one request (1-10,
+     * default 1). Cost scales linearly, and values above 1 are never covered
+     * by the free trial. Values above 1 require `mode: "async"` — only
+     * meaningful via `submit()`; `stream()`/`generate()` never send it, since
+     * they always request a plain stream. */
+    variantsNum?: number;
     /** Bounds the stream: aborting this cancels the in-flight generation.
      * Passed straight through to `fetch` — it is never rewrapped as
      * RequestTimeoutError, since the client's own absolute timeout does not
@@ -93,7 +99,15 @@ interface VideoToMusicParams {
      * Default-ON server-side in async mode: leave unset to keep it on, pass
      * `false` to opt out. Free, best-effort; only valid on `submit()`. */
     ducking?: boolean;
-}
+    /** How many distinct music variants to generate in one request (1-10,
+     * default 1). Cost scales linearly, and values above 1 are never covered
+     * by the free trial. Values above 1 require `mode: "async"` (auto-selected
+     * by `submit()`) — only meaningful via `submit()`; `stream()`/`generate()`
+     * never send it, since they always request a plain stream. */
+    variantsNum?: number;
+}
+/** One service's free-trial allowance. `remaining` is already floored at 0,
+ * so it is safe to compare directly. */
 interface TrialQuota {
     granted: number;
     used: number;
@@ -105,8 +119,10 @@ interface AccountServices {
     concurrency_limit: number;
     discount_factor: number | string;
     max_upload_size_mb: number | null;
-    /** Free-trial allowance keyed by service. Returned only for self-serve
-     * accounts; absent entirely for invoiced accounts. */
+    /** Free-trial allowance keyed by service (`granted` / `used` /
+     * `remaining`). Present only for self-serve accounts — always treat it as
+     * possibly absent, and treat a service missing from the map as "no trial
+     * allowance", not as an error. */
     trial?: Record<string, TrialQuota>;
 }
 interface UsageSummary {
@@ -167,6 +183,11 @@ interface BaseTaskResult {
     cost?: number;
     error?: SfxError;
     refunded?: boolean;
+    /** Echoes the request's `variantsNum`. Present regardless of task status
+     * (so a `processing`/`failed` poll explains the charge too), but only
+     * when it was above 1 — a default (single-variant) request sees the same
+     * shape it always has. */
+    variants_num?: number;
     [key: string]: unknown;
 }
 /** State of an SFX task (`tasks.get`) or its final result (`wait`/`generate`). */
@@ -194,6 +215,11 @@ interface MusicMediaEntry extends SfxMedia {
     stream_index: number;
     sample_rate?: number;
     channels?: number;
+    /** This entry's own title, present when `variantsNum` was above 1 (and
+     * titles are visible on the account). Each variant is a distinct creative
+     * direction, so it can carry its own title rather than sharing the
+     * top-level `MusicTaskResult.title`, which always names variant 0. */
+    title?: MusicTitle;
 }
 /** One muxed audio+video-aligned output, present only when `isolateVocals`
  * is set. */
@@ -209,13 +235,20 @@ interface MusicTitle {
  * (`tasks.wait<MusicTaskResult>()`). Only reachable via `videoToMusic.submit()`
  * with `mode: "async"`. */
 interface MusicTaskResult extends BaseTaskResult {
+    /** One entry per stream, or one entry per variant when `variantsNum` was
+     * greater than 1 — each variant entry may carry its own `title`. */
     audio?: MusicMediaEntry[];
     /** Vocals-only stem; present only when `isolateVocals` was requested. */
     vocals?: SfxMedia;
-    /** Muxed output per stream; present only when `isolateVocals` was requested. */
+    /** Muxed output per stream (or per variant); present only when
+     * `isolateVocals` was requested. */
     mux?: MusicMuxEntry[];
-    /** Music ducked under the source voice; present only when `ducking` ran. */
+    /** Music ducked under the source voice (per variant when `variantsNum` is
+     * above 1); present only when `ducking` ran. */
     ducked?: MusicMediaEntry[];
+    /** Variant 0's title — the top-level field always names the first variant,
+     * even when `variantsNum` produced others with their own titles on
+     * `audio[]`. */
     title?: MusicTitle;
     duration_seconds?: number;
 }
@@ -228,6 +261,11 @@ interface WaitOptions {
 /** Result of an async video-to-video task (`videoToVideoMusic`/`videoToVideoSfx`):
  * a re-hosted video with generated music or SFX muxed in. */
 interface VideoResult extends BaseTaskResult {
+    /** One re-hosted video per variant. On `videoToVideoMusic` this is
+     * populated even at the default `variantsNum` of 1 (as a single-entry
+     * array); `videoToVideoSfx` has no variants knob and always sends one. */
+    videos?: SfxMedia[];
+    /** Permanent alias for `videos[0]`. */
     video?: SfxMedia;
     duration_seconds?: number;
 }
@@ -240,6 +278,11 @@ interface VideoToVideoMusicParams {
     preserveSpeech?: boolean;
     /** @deprecated Legacy alias for `preserveSpeech`. */
     isolateVocals?: boolean;
+    /** How many distinct music variants to generate in one request (1-10,
+     * default 1). Cost scales linearly, and values above 1 are never covered
+     * by the free trial. This endpoint is always async, so no extra `mode`
+     * gating applies. The result's `videos[]` gets one entry per variant. */
+    variantsNum?: number;
 }
 interface VideoToVideoSfxParams {
     video?: VideoInput;
@@ -263,6 +306,24 @@ interface VideoToSoundParams {
     /** Duck the generated music under the source speech. Default-ON
      * server-side: leave unset to keep it on, pass `false` to opt out. */
     ducking?: boolean;
+    /** How many distinct variants to generate in one request (1-10, default
+     * 1). Cost scales linearly, and values above 1 are never covered by the
+     * free trial. Both `videoToSound` and `videoToVideoSound` are always
+     * async, so no extra `mode` gating applies. The result's `outputs[]` gets
+     * one entry per variant. */
+    variantsNum?: number;
+}
+/** One variant's outputs on a `videoToSound` / `videoToVideoSound` result.
+ * Present even at the default `variantsNum` of 1, as a single-entry array. */
+interface SoundOutputEntry {
+    variant_index: number;
+    output_url: string;
+    output_type: "audio" | "video";
+    output_bytes: number;
+    music?: SfxMedia;
+    /** Present only when `preserveSpeech`/`ducking` altered this variant's music bed. */
+    music_processed?: SfxMedia;
+    sfx?: SfxMedia;
 }
 /** Result of a `videoToSound` / `videoToVideoSound` task (`tasks.get`) or its
  * final state (`generate`).
@@ -271,7 +332,11 @@ interface VideoToSoundParams {
  * than a media object, since these endpoints render one artifact whose kind is
  * announced by `output_type` ("audio" for video-to-sound, "video" for
  * video-to-video-sound). `music`, `music_processed` and `sfx` are the
- * individual stems; pass any of them, or `output_url` itself, to `download()`. */
+ * individual stems; pass any of them, or `output_url` itself, to `download()`.
+ *
+ * `outputs` carries the same fields per variant when `variantsNum` was
+ * greater than 1; `output_url`/`output_type`/`output_bytes`/`music`/
+ * `music_processed`/`sfx` remain permanent aliases for `outputs[0]`. */
 interface SoundResult extends BaseTaskResult {
     output_url?: string;
     output_type?: "audio" | "video";
@@ -281,6 +346,33 @@ interface SoundResult extends BaseTaskResult {
     music_processed?: SfxMedia;
     sfx?: SfxMedia;
     duration_seconds?: number;
+    /** One entry per variant; see `SoundOutputEntry`. */
+    outputs?: SoundOutputEntry[];
+}
+/**
+ * A target language for /v1/dubbing. The union stays open (`string & {}`) so a
+ * language added server-side still type-checks against an older SDK — the
+ * backend, not this list, is the authority on what is supported.
+ */
+type DubbingLanguage = "en" | "zh_cn" | "ja" | "ko" | "pt" | "es" | "de" | "fr" | "it" | "ru" | (string & {});
+interface DubbingParams {
+    /** Exactly one of `video` / `videoUrl`. */
+    video?: VideoInput;
+    /**
+     * Exactly one of `video` / `videoUrl`. Must be an `https://` URL — the
+     * dubbing pipeline fetches the source itself and rejects plain http.
+     */
+    videoUrl?: string;
+    /** Omit to get the server default, `["zh_cn", "es", "fr"]`. */
+    languages?: DubbingLanguage[];
+}
+interface DubbingResult extends BaseTaskResult {
+    /**
+     * One dubbed video URL per requested language, keyed by language code.
+     * Unlike every other endpoint's envelope this is a map, not an `audio`/
+     * `video` slot — a dubbing task renders N artifacts, one per language.
+     */
+    outputs?: Record<string, string>;
 }
 
 declare class Account {
@@ -323,7 +415,8 @@ declare class TextToMusic {
     /**
      * Submit an async text-to-music task; poll with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `outputFormat: "wav"`. `stream()`/`generate()` remain the streaming path.
+     * `outputFormat: "wav"` and `variantsNum` above 1. `stream()`/`generate()`
+     * remain the streaming path.
      */
     submit(params: TextToMusicParams): Promise<SfxTask>;
 }
@@ -336,8 +429,9 @@ declare class VideoToMusic {
     /**
      * Submit an async video-to-music task; poll its result with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `isolateVocals` — the backend rejects vocal isolation on the plain
-     * stream, and it only ever runs in async mode.
+     * `isolateVocals`/`preserveSpeech`, `outputFormat: "wav"`, and
+     * `variantsNum` above 1 — the backend rejects all of these on the plain
+     * stream, and they only ever run in async mode.
      */
     submit(params: VideoToMusicParams): Promise<SfxTask>;
 }
@@ -393,6 +487,15 @@ declare class VideoToVideoSound {
     generate(params: VideoToSoundParams, opts?: WaitOptions): Promise<SoundResult>;
 }
 
+/** Dub a video into one or more target languages. Async only; the result
+ * carries a language → dubbed-video-URL map under `outputs`. */
+declare class Dubbing {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: DubbingParams): Promise<SfxTask>;
+    generate(params: DubbingParams, opts?: WaitOptions): Promise<DubbingResult>;
+}
+
 interface SoniloClientOptions {
     /** Defaults to the SONILO_API_KEY environment variable (Node.js only). */
     apiKey?: string;
@@ -430,6 +533,7 @@ declare class SoniloClient {
     readonly videoToVideoSfx: VideoToVideoSfx;
     readonly videoToSound: VideoToSound;
     readonly videoToVideoSound: VideoToVideoSound;
+    readonly dubbing: Dubbing;
     constructor(options?: SoniloClientOptions);
     /**
      * Perform an authenticated request; throws a typed error on non-2xx.
@@ -460,6 +564,14 @@ declare class AuthenticationError extends APIError {
 }
 declare class PaymentRequiredError extends APIError {
 }
+/** The account's free trial for this service is spent and it has never been
+ * funded — the caller should add a payment method rather than retry. A
+ * subclass of `PaymentRequiredError`, so code that already catches every 402
+ * keeps working; catch this first to tell "you haven't paid us yet" apart
+ * from a funded wallet that ran dry (`PaymentRequiredError` with
+ * `code === "insufficient_balance"`). */
+declare class TrialExhaustedError extends PaymentRequiredError {
+}
 declare class BadRequestError extends APIError {
     get detail(): string | undefined;
 }
@@ -503,6 +615,6 @@ declare class RequestTimeoutError extends SoniloError {
 declare function download(media: SfxMedia | string | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
 /** The SDK's own version. Generated by scripts/sync-versions.mjs — do not edit. */
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.8.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundResult, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundOutputEntry, type SoundResult, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.js

@@ -19,6 +19,8 @@ var AuthenticationError = class extends APIError {
 };
 var PaymentRequiredError = class extends APIError {
 };
+var TrialExhaustedError = class extends PaymentRequiredError {
+};
 var BadRequestError = class extends APIError {
   get detail() {
     const body = this.body;
@@ -88,8 +90,13 @@ async function errorFromResponse(res) {
   switch (res.status) {
     case 401:
       return new AuthenticationError(message, res.status, body);
-    case 402:
+    case 402: {
+      const code = body?.code;
+      if (code === "trial_exhausted") {
+        return new TrialExhaustedError(message, res.status, body);
+      }
       return new PaymentRequiredError(message, res.status, body);
+    }
     case 429: {
       const ra = res.headers.get("retry-after");
       const retryAfter = ra !== null && ra !== "" && !Number.isNaN(Number(ra)) ? Number(ra) : void 0;
@@ -298,7 +305,8 @@ var TextToMusic = class {
   /**
    * Submit an async text-to-music task; poll with
    * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-   * `outputFormat: "wav"`. `stream()`/`generate()` remain the streaming path.
+   * `outputFormat: "wav"` and `variantsNum` above 1. `stream()`/`generate()`
+   * remain the streaming path.
    */
   async submit(params) {
     const mode = params.mode ?? "async";
@@ -315,6 +323,9 @@ var TextToMusic = class {
     if (params.outputFormat !== void 0) {
       form.set("output_format", params.outputFormat);
     }
+    if (params.variantsNum !== void 0) {
+      form.set("variants_num", String(params.variantsNum));
+    }
     const res = await this.client.request("/v1/text-to-music", {
       method: "POST",
       body: form
@@ -395,19 +406,20 @@ var VideoToMusic = class {
   /**
    * Submit an async video-to-music task; poll its result with
    * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-   * `isolateVocals` — the backend rejects vocal isolation on the plain
-   * stream, and it only ever runs in async mode.
+   * `isolateVocals`/`preserveSpeech`, `outputFormat: "wav"`, and
+   * `variantsNum` above 1 — the backend rejects all of these on the plain
+   * stream, and they only ever run in async mode.
    */
   async submit(params) {
     if (params.video === void 0 === (params.videoUrl === void 0)) {
       throw new SoniloError("Provide exactly one of video or videoUrl");
     }
     let mode = params.mode;
-    const needsAsync = params.isolateVocals || params.preserveSpeech || params.ducking !== void 0 || params.outputFormat === "wav";
+    const needsAsync = params.isolateVocals || params.preserveSpeech || params.ducking !== void 0 || params.outputFormat === "wav" || params.variantsNum !== void 0 && params.variantsNum > 1;
     if (mode === void 0) mode = "async";
     if (needsAsync && mode !== "async") {
       throw new SoniloError(
-        'isolateVocals/preserveSpeech/ducking/outputFormat "wav" require mode: "async"'
+        'isolateVocals/preserveSpeech/ducking/outputFormat "wav"/variantsNum > 1 require mode: "async"'
       );
     }
     const form = new FormData();
@@ -434,6 +446,9 @@ var VideoToMusic = class {
     if (params.ducking !== void 0) {
       form.set("ducking", String(params.ducking));
     }
+    if (params.variantsNum !== void 0) {
+      form.set("variants_num", String(params.variantsNum));
+    }
     const res = await this.client.request("/v1/video-to-music", {
       method: "POST",
       body: form
@@ -520,6 +535,9 @@ var VideoToVideoMusic = class {
     if (params.isolateVocals !== void 0) {
       form.set("isolate_vocals", String(params.isolateVocals));
     }
+    if (params.variantsNum !== void 0) {
+      form.set("variants_num", String(params.variantsNum));
+    }
     const res = await this.client.request("/v1/video-to-video-music", {
       method: "POST",
       body: form
@@ -585,6 +603,9 @@ async function buildSoundForm(params) {
     form.set("preserve_speech", String(params.preserveSpeech));
   }
   if (params.ducking !== void 0) form.set("ducking", String(params.ducking));
+  if (params.variantsNum !== void 0) {
+    form.set("variants_num", String(params.variantsNum));
+  }
   return form;
 }
 
@@ -624,8 +645,48 @@ var VideoToVideoSound = class {
   }
 };
 
+// src/resources/dubbing.ts
+async function buildDubbingForm(params) {
+  if (params.video === void 0 === (params.videoUrl === void 0)) {
+    throw new SoniloError("Provide exactly one of video or videoUrl");
+  }
+  const form = new FormData();
+  if (params.video !== void 0) {
+    const { blob, filename } = await toUploadBlob(params.video);
+    form.set("video", blob, filename);
+  } else {
+    const url = params.videoUrl;
+    if (!url.toLowerCase().startsWith("https://")) {
+      throw new SoniloError(
+        "videoUrl must use https \u2014 the dubbing pipeline requires an https URL"
+      );
+    }
+    form.set("video_url", url);
+  }
+  if (params.languages !== void 0) {
+    form.set("languages", JSON.stringify(params.languages));
+  }
+  return form;
+}
+var Dubbing = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async submit(params) {
+    const res = await this.client.request("/v1/dubbing", {
+      method: "POST",
+      body: await buildDubbingForm(params)
+    });
+    return await res.json();
+  }
+  async generate(params, opts) {
+    const task = await this.submit(params);
+    return this.client.tasks.wait(task.task_id, opts);
+  }
+};
+
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "0.8.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";
@@ -656,6 +717,7 @@ var SoniloClient = class {
     this.videoToVideoSfx = new VideoToVideoSfx(this);
     this.videoToSound = new VideoToSound(this);
     this.videoToVideoSound = new VideoToVideoSound(this);
+    this.dubbing = new Dubbing(this);
   }
   /**
    * Perform an authenticated request; throws a typed error on non-2xx.
@@ -727,6 +789,7 @@ export {
   SoniloError,
   TaskFailedError,
   TaskTimeoutError,
+  TrialExhaustedError,
   VERSION,
   download,
   isAudioChunkEvent,