@transcribe-api/sdk 0.1.5 → 0.1.7

package/README.md

@@ -52,7 +52,8 @@ console.log(result);
 The SDK automatically chooses the right API flow:
 
 - One small local file is sent through the direct synchronous upload path.
-- Remote URLs, webhook jobs, multiple files, files larger than 30 MB, and files estimated over 10 minutes are sent through the async job flow.
+- One remote URL is sent through the direct `/v1/transcribe` endpoint and the API decides whether it can finish immediately or should continue as an async job.
+- Multiple files, files larger than 30 MB, and files estimated over 10 minutes are sent through the async job flow.
 - Large local async uploads use signed R2 upload URLs returned by the API.
 - Multipart upload is used automatically when the backend returns multipart upload instructions.
 - If `polling` is configured, async calls wait until the job reaches a terminal status.
@@ -131,7 +132,7 @@ const job = await client.transcribe({
 });
 ```
 
-Remote URL jobs are async because the API fetches the audio from the URL.
+For one remote URL, the SDK submits the request to the direct `/v1/transcribe` endpoint and lets the API decide the final route. Small remote files may complete immediately, while larger or longer remote files automatically fall back to the async job flow.
 
 ## Batch and mixed input transcription
 
@@ -184,6 +185,8 @@ You can also pass a comma-separated string:
 exclude: "metadata,billing"
 ```
 
+For single-file outputs, if `exclude` leaves only one transcript field and removes metadata, billing, and detected language, the API returns that remaining value directly instead of a JSON object. Text-only responses return a plain string, VTT-only responses return a plain string, and segments-only responses return an array. Multi-file outputs still return JSON so each result stays associated with its `reference_id`.
+
 ## Webhooks
 
 ```js
@@ -195,7 +198,7 @@ const job = await client.transcribe({
 });
 ```
 
-Any request with `webhookUrl` uses the async job flow.
+For a single file or URL, `webhookUrl` is sent through the direct `/v1/transcribe` endpoint and the API decides whether it can finish immediately or should continue as a job. Multi-file requests still use the async batch flow.
 
 ## Progress and logs
 

package/index.js

@@ -1364,8 +1364,6 @@ export class TranscribeAPI {
         : (normalizedItem.durationEstimateSec || await estimateDurationFromFile(normalizedSingleFile));
       const effectiveLanguage = normalizedItem.hasLanguage ? normalizedItem.language : normalizeLanguageCode(language);
       const isAsync = files.length > 1
-        || Boolean(normalizedItem.url)
-        || Boolean(webhookUrl)
         || (
           normalizedSingleFile
           && (
@@ -1387,6 +1385,18 @@ export class TranscribeAPI {
         });
       }
 
+      if (normalizedItem.url) {
+        return this.transcribeUrlDirect({
+          url: normalizedItem.url,
+          referenceId: normalizedItem.referenceId,
+          language: effectiveLanguage,
+          exclude,
+          webhookUrl,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
+        });
+      }
+
       return this.transcribeDirect({
         file: normalizedSingleFile,
         referenceId: normalizedItem.referenceId,
@@ -1485,6 +1495,44 @@ export class TranscribeAPI {
     return result;
   }
 
+  async transcribeUrlDirect({
+    url,
+    referenceId,
+    language,
+    exclude,
+    webhookUrl,
+    showLogs = false,
+    logger = console,
+  } = {}) {
+    const form = new FormData();
+    form.set("url", String(url || "").trim());
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    if (language) form.set("language", language);
+    if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+    if (webhookUrl) form.set("webhook_url", webhookUrl);
+
+    const response = await fetch(`${this.baseUrl}/transcribe`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    const result = await parseApiResponse(response);
+    if (this.polling && result && typeof result === "object" && result.job_status && !TERMINAL_JOB_STATUSES.has(String(result.job_status))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs,
+        logger,
+        initialJob: result,
+      });
+    }
+    if (showLogs && typeof logger?.log === "function") {
+      logger.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    }
+    return result;
+  }
+
   async transcribeMany({
     files,
     webhookUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transcribe-api/sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Official JavaScript SDK for Transcribe API.",
   "type": "module",
   "main": "index.js",
@@ -25,4 +25,4 @@
   ],
   "author": "Transcribe API",
   "license": "MIT"
-}
+}

package/worker.js

@@ -1364,8 +1364,6 @@ export class TranscribeAPI {
         : (normalizedItem.durationEstimateSec || await estimateDurationFromFile(normalizedSingleFile));
       const effectiveLanguage = normalizedItem.hasLanguage ? normalizedItem.language : normalizeLanguageCode(language);
       const isAsync = files.length > 1
-        || Boolean(normalizedItem.url)
-        || Boolean(webhookUrl)
         || (
           normalizedSingleFile
           && (
@@ -1387,6 +1385,18 @@ export class TranscribeAPI {
         });
       }
 
+      if (normalizedItem.url) {
+        return this.transcribeUrlDirect({
+          url: normalizedItem.url,
+          referenceId: normalizedItem.referenceId,
+          language: effectiveLanguage,
+          exclude,
+          webhookUrl,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
+        });
+      }
+
       return this.transcribeDirect({
         file: normalizedSingleFile,
         referenceId: normalizedItem.referenceId,
@@ -1485,6 +1495,44 @@ export class TranscribeAPI {
     return result;
   }
 
+  async transcribeUrlDirect({
+    url,
+    referenceId,
+    language,
+    exclude,
+    webhookUrl,
+    showLogs = false,
+    logger = console,
+  } = {}) {
+    const form = new FormData();
+    form.set("url", String(url || "").trim());
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    if (language) form.set("language", language);
+    if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+    if (webhookUrl) form.set("webhook_url", webhookUrl);
+
+    const response = await fetch(`${this.baseUrl}/transcribe`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    const result = await parseApiResponse(response);
+    if (this.polling && result && typeof result === "object" && result.job_status && !TERMINAL_JOB_STATUSES.has(String(result.job_status))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs,
+        logger,
+        initialJob: result,
+      });
+    }
+    if (showLogs && typeof logger?.log === "function") {
+      logger.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    }
+    return result;
+  }
+
   async transcribeMany({
     files,
     webhookUrl,