feat(restate): add Soniox STT provider support (#2186)

* feat(restate): add Soniox STT provider support

- Add SONIOX_API_KEY to env schema
- Create soniox.ts with webhook-based transcription
- Update SttFileInput to include optional provider param (defaults to deepgram)
- Update run handler to branch on provider
- Update onTranscript to handle both Deepgram and Soniox callbacks

Co-Authored-By: yujonglee <[email protected]>

* refactor(restate): use ctx.request().extraArgs for Soniox API key instead of workflow state

Co-Authored-By: yujonglee <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: yujonglee <[email protected]>

Author: devin-ai-integration[bot]

apps/restate/src/env.ts

@@ -4,6 +4,7 @@ export const envSchema = z.object({
   RESTATE_IDENTITY_KEY: z.string().optional(),
   RESTATE_INGRESS_URL: z.url(),
   DEEPGRAM_API_KEY: z.string().min(1),
+  SONIOX_API_KEY: z.string().min(1),
   OPENROUTER_API_KEY: z.string().min(1),
   SUPABASE_URL: z.url(),
   SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),

apps/restate/src/services/stt-file.ts

@@ -6,15 +6,26 @@ import {
   DeepgramCallback,
   DeepgramCallbackType,
   extractTranscript,
-  transcribeWithCallback,
+  transcribeWithCallback as transcribeWithDeepgram,
 } from "../deepgram";
 import { type Env } from "../env";
+import {
+  fetchTranscript as fetchSonioxTranscript,
+  SonioxCallback,
+  SonioxCallbackType,
+  transcribeWithCallback as transcribeWithSoniox,
+} from "../soniox";
 import { createSignedUrl, deleteFile } from "../supabase";
 import { limiter } from "./rate-limit";
 
+const SttProvider = z.enum(["deepgram", "soniox"]);
+
+export type SttProviderType = z.infer<typeof SttProvider>;
+
 const SttFileInput = z.object({
   userId: z.string(),
   fileId: z.string(),
+  provider: SttProvider.optional().default("deepgram"),
 });
 
 export type SttFileInputType = z.infer<typeof SttFileInput>;
@@ -31,6 +42,7 @@ export const sttFile = restate.workflow({
       async (ctx: restate.WorkflowContext, input: SttFileInputType) => {
         ctx.set("status", "QUEUED" as SttStatusType);
         ctx.set("fileId", input.fileId);
+        ctx.set("provider", input.provider);
 
         const env = ctx.request().extraArgs[0] as Env;
 
@@ -48,10 +60,21 @@ export const sttFile = restate.workflow({
 
           const callbackUrl = `${env.RESTATE_INGRESS_URL.replace(/\/+$/, "")}/SttFile/${encodeURIComponent(ctx.key)}/onTranscript`;
 
-          const requestId = await ctx.run("transcribe", () =>
-            transcribeWithCallback(audioUrl, callbackUrl, env.DEEPGRAM_API_KEY),
-          );
-          ctx.set("deepgramRequestId", requestId);
+          if (input.provider === "soniox") {
+            const requestId = await ctx.run("transcribe", () =>
+              transcribeWithSoniox(audioUrl, callbackUrl, env.SONIOX_API_KEY),
+            );
+            ctx.set("providerRequestId", requestId);
+          } else {
+            const requestId = await ctx.run("transcribe", () =>
+              transcribeWithDeepgram(
+                audioUrl,
+                callbackUrl,
+                env.DEEPGRAM_API_KEY,
+              ),
+            );
+            ctx.set("providerRequestId", requestId);
+          }
 
           const transcript = await ctx.promise<string>("transcript");
           ctx.set("transcript", transcript);
@@ -72,15 +95,35 @@ export const sttFile = restate.workflow({
     ),
 
     onTranscript: restate.handlers.workflow.shared(
-      { input: serde.zod(DeepgramCallback) },
+      { input: serde.zod(z.union([DeepgramCallback, SonioxCallback])) },
       async (
         ctx: restate.WorkflowSharedContext,
-        payload: DeepgramCallbackType,
+        payload: DeepgramCallbackType | SonioxCallbackType,
       ): Promise<void> => {
         const existing = await ctx.get<string>("transcript");
         if (existing !== undefined) return;
 
-        ctx.promise<string>("transcript").resolve(extractTranscript(payload));
+        const provider = await ctx.get<SttProviderType>("provider");
+
+        if (provider === "soniox" && "id" in payload && "status" in payload) {
+          const sonioxPayload = payload as SonioxCallbackType;
+          if (sonioxPayload.status === "error") {
+            ctx
+              .promise<string>("transcript")
+              .reject("Soniox transcription failed");
+            return;
+          }
+          const env = ctx.request().extraArgs[0] as Env;
+          const transcript = await fetchSonioxTranscript(
+            sonioxPayload.id,
+            env.SONIOX_API_KEY,
+          );
+          ctx.promise<string>("transcript").resolve(transcript);
+        } else {
+          ctx
+            .promise<string>("transcript")
+            .resolve(extractTranscript(payload as DeepgramCallbackType));
+        }
       },
     ),
 

apps/restate/src/soniox.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+const SONIOX_API_HOST = "https://api.soniox.com";
+
+export const SonioxCallback = z.object({
+  id: z.string(),
+  status: z.enum(["completed", "error"]),
+});
+
+export type SonioxCallbackType = z.infer<typeof SonioxCallback>;
+
+type SonioxToken = {
+  text: string;
+  start_ms?: number;
+  end_ms?: number;
+  confidence?: number;
+  speaker?: number | string;
+};
+
+type SonioxTranscriptResponse = {
+  text: string;
+  tokens: SonioxToken[];
+};
+
+export async function transcribeWithCallback(
+  audioUrl: string,
+  callbackUrl: string,
+  apiKey: string,
+): Promise<string> {
+  const response = await fetch(`${SONIOX_API_HOST}/v1/transcriptions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model: "stt-async-v3",
+      audio_url: audioUrl,
+      webhook_url: callbackUrl,
+      enable_speaker_diarization: true,
+      enable_language_identification: true,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Soniox: ${response.status} - ${errorText}`);
+  }
+
+  const result = (await response.json()) as { id: string };
+  if (!result.id) {
+    throw new Error("Soniox: missing transcription id");
+  }
+
+  return result.id;
+}
+
+export async function fetchTranscript(
+  transcriptionId: string,
+  apiKey: string,
+): Promise<string> {
+  const response = await fetch(
+    `${SONIOX_API_HOST}/v1/transcriptions/${transcriptionId}/transcript`,
+    {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Soniox fetch transcript: ${response.status} - ${errorText}`,
+    );
+  }
+
+  const result = (await response.json()) as SonioxTranscriptResponse;
+  return result.text || renderTokens(result.tokens);
+}
+
+function renderTokens(tokens: SonioxToken[]): string {
+  return tokens.map((token) => token.text).join("");
+}