sonilo 0.6.0 → 0.8.0

package/README.md

@@ -11,7 +11,7 @@ npm install sonilo
 
 ## Authentication
 
-Create an API key in your [Sonilo dashboard](https://platform.sonilo.com/dashboard/api-keys),
+Create an API key in your [Sonilo dashboard](https://platform.sonilo.com/dashboard/api-keys?utm_source=sonilo_js&utm_medium=readme&utm_campaign=sdk_quickstart),
 then give it to the client either as an environment variable (recommended) or
 inline:
 
@@ -107,6 +107,46 @@ if (result.ducked) {
 }
 ```
 
+### Variants (async)
+
+`variantsNum` generates several distinct music variants in one request (1-10,
+default 1) — each is its own creative direction, with its own title. It's
+available on `textToMusic`, `videoToMusic`, `videoToVideoMusic`,
+`videoToSound` and `videoToVideoSound`. Cost scales linearly with the count,
+and **values above 1 are never covered by the free trial**.
+
+On `textToMusic`/`videoToMusic`, `variantsNum` above 1 requires the async task
+API — same as `preserveSpeech` above — so it implies `mode: "async"` if you
+don't set `mode` yourself; `stream()`/`generate()` never send it, since they
+always request a plain stream. `videoToVideoMusic`, `videoToSound` and
+`videoToVideoSound` are already async-only, so no extra `mode` handling is
+needed there.
+
+```ts
+const task = await client.textToMusic.submit({
+  prompt: "warm lo-fi piano",
+  duration: 30,
+  variantsNum: 3,
+});
+const result = await client.tasks.wait<MusicTaskResult>(task.task_id);
+
+// audio has one entry per variant; each entry may carry its own `title`.
+for (const variant of result.audio ?? []) {
+  console.log(variant.title?.title, variant.url);
+}
+```
+
+`videoToVideoMusic` returns one video per variant in `videos[]`, with `video`
+kept as a permanent alias for `videos[0]`. `videoToSound`/`videoToVideoSound`
+return one entry per variant in `outputs[]`, each shaped like the top-level
+result (`output_url`, `output_type`, `output_bytes`, `music`,
+`music_processed?`, `sfx`) — the top-level fields remain permanent aliases for
+`outputs[0]`. All of these arrays are present even at the default
+`variantsNum` of 1, as a single-entry array; every other field is unchanged.
+
+`GET /v1/tasks/{id}` (`tasks.get`/`tasks.wait`) echoes the request's
+`variantsNum` back as `variants_num`, but only when it was above 1.
+
 ## Video to video
 
 Generate a soundtrack or sound effects and get back a **re-hosted video** with
@@ -175,6 +215,57 @@ Input videos may be at most 180 seconds long.
 Use `submit()` instead of `generate()` to get a `task_id` back immediately and
 poll it yourself with `client.tasks.wait<SoundResult>(taskId)`.
 
+## Dubbing
+
+`client.dubbing.submit()` / `.generate()` dub a video into one or more target
+languages in a single async call — one call, one task, one dubbed video per
+language.
+
+```ts
+import { SoniloClient } from "sonilo";
+import type { DubbingResult } from "sonilo";
+
+const client = new SoniloClient();
+
+const task = await client.dubbing.submit({
+  videoUrl: "https://example.com/clip.mp4",
+  languages: ["es", "fr"],
+});
+const result = await client.tasks.wait<DubbingResult>(task.task_id);
+for (const [language, url] of Object.entries(result.outputs ?? {})) {
+  console.log(language, url);
+}
+```
+
+`generate()` wraps submit + poll, same as the other async endpoints, and
+accepts a `{ timeout }` option to override the default 10-minute wait. The
+dubbing pipeline can take much longer than that, especially with several
+languages in one call, so pass a longer timeout for anything but the shortest
+clips. 7,200,000 ms matches the backend's own ceiling for a dubbing job and is
+what the CLI defaults to. For long jobs you can also use `submit()` plus your
+own `client.tasks.wait()`, as above:
+
+```ts
+const result = await client.dubbing.generate(
+  { videoUrl: "https://example.com/clip.mp4", languages: ["es", "fr"] },
+  { timeout: 7_200_000 }, // 2 hours, the backend's own ceiling
+);
+```
+
+Params: exactly one of `video` / `videoUrl` (`videoUrl` must be **https** —
+the dubbing pipeline fetches the source itself and rejects plain http). The
+optional `languages` array defaults to `["zh_cn", "es", "fr"]`; supported
+codes are `en, zh_cn, ja, ko, pt, es, de, fr, it, ru`.
+
+Dubbing is async-only, and the source video may be at most 180 seconds long.
+You are billed per language. Dubbing has **no free trial allowance** — unlike
+every other endpoint, every call bills from the first one (see
+[Free trial](#free-trial)).
+
+The result is a `DubbingResult`, whose `outputs` is a map of language code to
+dubbed `.mp4` URL — not the `audio`/`video`/`output_url` shape the other
+endpoints use.
+
 ## Configuration
 
 ```ts
@@ -258,15 +349,25 @@ are presigned and expire; download promptly or re-fetch via `tasks.get`.
 
 ## Free trial
 
-Accounts created through self-serve signup start with free runs on every
-endpoint — no card required:
+Accounts created through self-serve signup start with free runs on most
+endpoints — no card required:
 
 | Free runs | Endpoints |
 | --- | --- |
 | 2 each | text-to-music, text-to-sfx, audio-ducking |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
+| 0 | dubbing |
 
 Once an endpoint's free runs are used up, calls to it bill at the normal rate.
+**Dubbing has no free trial allowance at all** — it bills every call from the
+first one. This is deliberate: dubbing charges `video_duration ×
+number_of_languages`, so a single "free" run could easily cost more than the
+free allowance on every other endpoint combined.
+
+The table above is the current default. Read the live numbers from
+`account.services()` rather than hard-coding them — see
+[Account](#account) below, and [Errors](#errors) for what a spent trial
+looks like at the call site.
 
 ## Account
 
@@ -275,10 +376,27 @@ const services = await sonilo.account.services();
 const usage = await sonilo.account.usage({ days: 7 });
 ```
 
+`services.trial` reports the free-trial allowance per service, so an
+integration can degrade gracefully *before* a call fails:
+
+```ts
+const { trial } = await sonilo.account.services();
+const quota = trial?.text_to_music;
+if (quota && quota.remaining === 0) {
+  // Prompt for a payment method instead of firing a call that will 402.
+  console.log(`Free trial spent (${quota.used}/${quota.granted}).`);
+}
+```
+
+`trial` is present only for self-serve accounts, so always treat it as
+optional; a service missing from the map has no trial allowance rather than
+an unlimited one.
+
 ## Errors
 
 All errors extend `SoniloError`: `AuthenticationError` (401),
-`PaymentRequiredError` (402), `RateLimitError` (429, `.retryAfter`),
+`PaymentRequiredError` (402), `TrialExhaustedError` (402, a subclass of
+`PaymentRequiredError`), `RateLimitError` (429, `.retryAfter`),
 `BadRequestError` (400/413/422, `.detail`), `APIError` (anything else),
 `GenerationError` for failures mid-stream, `TaskFailedError` (`.code`,
 `.taskId`, `.refunded`) for a failed SFX task, `TaskTimeoutError`
@@ -292,3 +410,29 @@ Every `APIError` also carries `.status`, `.body` (the parsed response),
 `.code` (the API's error code, e.g. `"rate_limit_exceeded"`), and `.errors`
 (the validation detail array on a 422), in addition to any subclass-specific
 properties above.
+
+### The three 402s
+
+A `402` is not one condition. Branch on the class (or equivalently on
+`.code`), never on the message text:
+
+```ts
+try {
+  await sonilo.textToMusic.generate({ prompt: "lofi", duration: 30 });
+} catch (err) {
+  if (err instanceof TrialExhaustedError) {
+    // code: "trial_exhausted" — the free trial for this service is spent and
+    // the account has never been funded. Prompt for a payment method; a retry
+    // can never succeed.
+  } else if (err instanceof PaymentRequiredError) {
+    // code: "insufficient_balance" — a funded wallet ran dry. Add balance and
+    // retry the same request.
+    // code: "payment_required" — anything else, e.g. a suspended account.
+  }
+}
+```
+
+`TrialExhaustedError` extends `PaymentRequiredError`, so an existing
+`catch (err) { if (err instanceof PaymentRequiredError) ... }` keeps
+catching every 402 — order the checks most-specific-first if you want to
+tell them apart.

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   SoniloError: () => SoniloError,
   TaskFailedError: () => TaskFailedError,
   TaskTimeoutError: () => TaskTimeoutError,
+  TrialExhaustedError: () => TrialExhaustedError,
   VERSION: () => VERSION,
   download: () => download,
   isAudioChunkEvent: () => isAudioChunkEvent,
@@ -60,6 +61,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;
@@ -129,8 +132,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;
@@ -339,7 +347,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";
@@ -356,6 +365,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
@@ -436,19 +448,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();
@@ -475,6 +488,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
@@ -561,6 +577,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
@@ -626,6 +645,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;
 }
 
@@ -665,8 +687,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";
@@ -697,6 +759,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.
@@ -769,6 +832,7 @@ function isErrorEvent(event) {
   SoniloError,
   TaskFailedError,
   TaskTimeoutError,
+  TrialExhaustedError,
   VERSION,
   download,
   isAudioChunkEvent,