Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: add an Audio API card to Settings and open it from Audio pages (#12821)

Etherld9214aee896c
diff --git a/studio/frontend/src/features/audio/audio-page.tsx b/studio/frontend/src/features/audio/audio-page.tsx
index 7171369b375..bad79941c4b 100644
--- a/studio/frontend/src/features/audio/audio-page.tsx
+++ b/studio/frontend/src/features/audio/audio-page.tsx
@@ -70,6 +70,7 @@ import {
import type { ClipSendHandlers } from "./components/clip-card";
import { sendClipToMusic } from "./components/music-send-to";
import { SaveVoiceDialog } from "./components/save-voice-dialog";
+import { UseViaApiButton } from "./components/use-via-api-button";
import { WorkflowTitleMenu } from "./components/workflow-title-menu";
import { galleryCache, useAudioGallery, useWorkflowHistory } from "./hooks/use-audio-gallery";
import { useAudioHandoff } from "./hooks/use-audio-handoff";
@@ -1805,6 +1806,10 @@ export function AudioPage({
</div>
<div className="pointer-events-none col-start-3 flex min-w-0 items-start justify-end pr-2 pt-[var(--studio-chat-header-padding-top,11px)]">
<div className="pointer-events-auto flex min-w-0 items-center gap-2">
+ <UseViaApiButton
+ workflow={pageWorkflow}
+ model={selectorValue ?? null}
+ />
<LibraryPageLink
tab="audio"
labelClassName="hidden @[50rem]:inline"
diff --git a/studio/frontend/src/features/audio/components/use-via-api-button.tsx b/studio/frontend/src/features/audio/components/use-via-api-button.tsx
new file mode 100644
index 00000000000..5405a08156e
--- /dev/null
+++ b/studio/frontend/src/features/audio/components/use-via-api-button.tsx
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { ApiIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { publicModelId } from "@/features/hub";
+import { useSettingsDialogStore } from "@/features/settings";
+import { useT } from "@/i18n";
+import { isAudioCppFolderId } from "../audio-cpp-catalog";
+import type { AudioWorkflowId } from "../workflows";
+
+export function UseViaApiButton({
+ workflow,
+ model,
+}: {
+ workflow: AudioWorkflowId;
+ model: string | null;
+}) {
+ const t = useT();
+ const label = t("settings.apiKeys.audioApi.useViaApi");
+ return (
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ aria-label={label}
+ onClick={() =>
+ useSettingsDialogStore.getState().openAudioApi({
+ workflow,
+ // /v1 names a model by its public id; an audio.cpp folder id already is one.
+ model: model
+ ? isAudioCppFolderId(model)
+ ? model
+ : publicModelId(model)
+ : null,
+ })
+ }
+ className="flex h-[calc(34px*var(--ui-space-scale,1))] shrink-0 items-center gap-1.5 rounded-full px-2.5 text-ui-13 font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <HugeiconsIcon icon={ApiIcon} className="size-4 shrink-0" />
+ <span className="hidden whitespace-nowrap @[84rem]:inline">
+ {label}
+ </span>
+ </button>
+ </TooltipTrigger>
+ <TooltipContent side="bottom" sideOffset={6} className="tooltip-compact">
+ {label}
+ </TooltipContent>
+ </Tooltip>
+ );
+}
diff --git a/studio/frontend/src/features/settings/api/openai-auto-switch.ts b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
index 3d19498705a..ab38e9a771e 100644
--- a/studio/frontend/src/features/settings/api/openai-auto-switch.ts
+++ b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
@@ -88,9 +88,25 @@ async function fetchOpenAIAutoSwitchSettings(): Promise<OpenAIAutoSwitchSettings
// must not refill it, or the pre-toggle value would be served indefinitely.
let cacheGeneration = 0;
+const settingsListeners = new Set<
+ (settings: OpenAIAutoSwitchSettings) => void
+>();
+
+export function subscribeOpenAIAutoSwitchSettings(
+ listener: (settings: OpenAIAutoSwitchSettings) => void,
+): () => void {
+ settingsListeners.add(listener);
+ return () => {
+ settingsListeners.delete(listener);
+ };
+}
+
function cacheSettings(settings: OpenAIAutoSwitchSettings, generation: number) {
if (generation === cacheGeneration) {
cachedSettings = settings;
+ for (const listener of settingsListeners) {
+ listener(settings);
+ }
}
return settings;
}
diff --git a/studio/frontend/src/features/settings/api/openai-model-catalog.ts b/studio/frontend/src/features/settings/api/openai-model-catalog.ts
index 95cd2234963..a9a70af4622 100644
--- a/studio/frontend/src/features/settings/api/openai-model-catalog.ts
+++ b/studio/frontend/src/features/settings/api/openai-model-catalog.ts
@@ -10,11 +10,36 @@ export type OpenAIModel = {
};
type ApiOpenAIModelList = {
- data?: { id?: unknown; loaded?: unknown; quant?: unknown; task?: unknown }[];
+ data?: {
+ id?: unknown;
+ loaded?: unknown;
+ quant?: unknown;
+ task?: unknown;
+ audio_workflows?: unknown;
+ }[];
};
const CHAT_TASKS = new Set(["text-generation"]);
+export type AudioApiTask =
+ | "text-to-speech"
+ | "automatic-speech-recognition"
+ | "audio-to-audio";
+
+export type AudioApiModel = {
+ id: string;
+ loaded: boolean;
+ // text-to-speech also covers music models, which /v1/audio/speech serves too.
+ task: AudioApiTask;
+ workflows?: string[];
+};
+
+const AUDIO_TASKS = new Set<string>([
+ "text-to-speech",
+ "automatic-speech-recognition",
+ "audio-to-audio",
+]);
+
export function chatModelsFromCatalog(body: unknown): OpenAIModel[] {
const data = (body as ApiOpenAIModelList | null)?.data;
if (!Array.isArray(data)) {
@@ -34,3 +59,65 @@ export function chatModelsFromCatalog(body: unknown): OpenAIModel[] {
: [],
);
}
+
+export function audioModelsFromCatalog(body: unknown): AudioApiModel[] {
+ const data = (body as ApiOpenAIModelList | null)?.data;
+ if (!Array.isArray(data)) {
+ return [];
+ }
+ return data.flatMap((entry) =>
+ typeof entry?.id === "string" &&
+ entry.id &&
+ typeof entry.task === "string" &&
+ AUDIO_TASKS.has(entry.task)
+ ? [
+ {
+ id: entry.id,
+ loaded: entry.loaded === true,
+ task: entry.task as AudioApiTask,
+ ...(Array.isArray(entry.audio_workflows)
+ ? {
+ workflows: entry.audio_workflows.filter(
+ (item): item is string => typeof item === "string",
+ ),
+ }
+ : {}),
+ },
+ ]
+ : [],
+ );
+}
+
+const AUDIO_CATALOG_RETRY_MS = 15000;
+const AUDIO_CATALOG_IDLE_MS = 60000;
+
+// Polls because downloads, loads and idle unloads move no store state; slower once one is resident.
+export function watchAudioModels(
+ list: () => Promise<AudioApiModel[]>,
+ onModels: (models: AudioApiModel[]) => void,
+): () => void {
+ let stopped = false;
+ let timer: ReturnType<typeof setTimeout> | null = null;
+ const update = () => {
+ list()
+ .then(
+ (models) => {
+ if (!stopped) onModels(models);
+ return models.some((m) => m.loaded);
+ },
+ () => false,
+ )
+ .then((resident) => {
+ if (stopped) return;
+ timer = setTimeout(
+ update,
+ resident ? AUDIO_CATALOG_IDLE_MS : AUDIO_CATALOG_RETRY_MS,
+ );
+ });
+ };
+ update();
+ return () => {
+ stopped = true;
+ if (timer !== null) clearTimeout(timer);
+ };
+}
diff --git a/studio/frontend/src/features/settings/api/openai-models.ts b/studio/frontend/src/features/settings/api/openai-models.ts
index 2e6fe6cee3e..320b0419205 100644
--- a/studio/frontend/src/features/settings/api/openai-models.ts
+++ b/studio/frontend/src/features/settings/api/openai-models.ts
@@ -3,9 +3,14 @@
import { authFetch } from "@/features/auth";
-import { chatModelsFromCatalog, type OpenAIModel } from "./openai-model-catalog";
+import {
+ type AudioApiModel,
+ type OpenAIModel,
+ audioModelsFromCatalog,
+ chatModelsFromCatalog,
+} from "./openai-model-catalog";
-export type { OpenAIModel };
+export type { AudioApiModel, OpenAIModel };
/**
* The chat-capable models this server can serve: `/v1/models` also lists image,
@@ -18,3 +23,12 @@ export async function listOpenAIModels(): Promise<OpenAIModel[]> {
}
return chatModelsFromCatalog(await res.json());
}
+
+/** The downloaded speech and transcription models, for the Audio API examples. */
+export async function listOpenAIAudioModels(): Promise<AudioApiModel[]> {
+ const res = await authFetch("/v1/models");
+ if (!res.ok) {
+ throw new Error(`Failed to list models (${res.status})`);
+ }
+ return audioModelsFromCatalog(await res.json());
+}
diff --git a/studio/frontend/src/features/settings/components/audio-api-examples.tsx b/studio/frontend/src/features/settings/components/audio-api-examples.tsx
new file mode 100644
index 00000000000..0e67f407e41
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/audio-api-examples.tsx
@@ -0,0 +1,353 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { usePlatformStore } from "@/config/env";
+import { useT } from "@/i18n";
+import type { TranslationKey } from "@/i18n";
+import { copyToClipboard } from "@/lib/copy-to-clipboard";
+import { Tick02Icon } from "@/lib/tick-icon";
+import { cn } from "@/lib/utils";
+import { Copy01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import type {
+ KeylessApiAccessExposure,
+ KeylessApiAccessScope,
+} from "../api/keyless-api-access";
+import {
+ loadOpenAIAutoSwitchSettings,
+ subscribeOpenAIAutoSwitchSettings,
+} from "../api/openai-auto-switch";
+import { watchAudioModels } from "../api/openai-model-catalog";
+import {
+ type AudioApiModel,
+ listOpenAIAudioModels,
+} from "../api/openai-models";
+import { useSettingsDialogStore } from "../stores/settings-dialog-store";
+import { useSettingsPanelPrefsStore } from "../stores/settings-panel-prefs-store";
+import {
+ AUDIO_API_PLACEHOLDER_MODELS,
+ AUDIO_API_TABS,
+ AUDIO_RUN_WORKFLOWS,
+ type AudioApiExample,
+ type AudioApiLang,
+ type AudioApiOs,
+ type AudioApiTab,
+ type AudioRunWorkflow,
+ audioApiExampleFor,
+ audioApiKey,
+ audioApiModelFits,
+ audioLangToStore,
+ buildAudioApiSnippet,
+ langFromStored,
+ pickAudioApiModel,
+} from "./audio-api-snippets";
+import { HighlightedCode } from "./usage-examples";
+
+const LANGS: { id: AudioApiLang; label: string }[] = [
+ { id: "curl", label: "curl" },
+ { id: "python", label: "Python" },
+ { id: "javascript", label: "JavaScript" },
+];
+
+const TAB_LABEL: Record<AudioApiTab, TranslationKey> = {
+ speak: "settings.apiKeys.audioApi.speak",
+ clone: "settings.apiKeys.audioApi.clone",
+ transcribe: "settings.apiKeys.audioApi.transcribe",
+ workflows: "settings.apiKeys.audioApi.workflows",
+};
+
+const RUN_LABEL: Record<AudioRunWorkflow, TranslationKey> = {
+ separate: "settings.apiKeys.audioApi.separate",
+ convert: "settings.apiKeys.audioApi.convert",
+ music: "settings.apiKeys.audioApi.music",
+ edit: "settings.apiKeys.audioApi.edit",
+};
+
+function Pill({
+ active,
+ onClick,
+ children,
+}: {
+ active: boolean;
+ onClick: () => void;
+ children: ReactNode;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ aria-pressed={active}
+ className={cn(
+ "rounded-full px-2.5 py-1 text-ui-11 font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+ active
+ ? "hub-tab-toggle-pill text-foreground"
+ : "text-muted-foreground hover:text-foreground",
+ )}
+ >
+ {children}
+ </button>
+ );
+}
+
+export function AudioApiExamples({
+ apiKey,
+ useTunnel,
+ keylessScope = "off",
+ keylessExposure = null,
+}: {
+ apiKey?: string | null;
+ useTunnel: boolean;
+ keylessScope?: KeylessApiAccessScope;
+ keylessExposure?: KeylessApiAccessExposure | null;
+}) {
+ const t = useT();
+ const deviceType = usePlatformStore((s) => s.deviceType);
+ const cloudflareUrl = usePlatformStore((s) => s.cloudflareUrl);
+ const serverUrl = usePlatformStore((s) => s.serverUrl);
+ const setStoredTab = useSettingsPanelPrefsStore((s) => s.setApiAudioExample);
+ const setStoredLang = useSettingsPanelPrefsStore((s) => s.setApiExampleLang);
+ const setStoredOs = useSettingsPanelPrefsStore((s) => s.setApiExampleOs);
+ const [storedPrefs] = useState(() => useSettingsPanelPrefsStore.getState());
+ const [tab, setTab] = useState<AudioApiTab>(
+ AUDIO_API_TABS.find((id) => id === storedPrefs.apiAudioExample) ?? "speak",
+ );
+ const [run, setRun] = useState<AudioRunWorkflow>("separate");
+ const [lang, setLang] = useState<AudioApiLang>(
+ langFromStored(storedPrefs.apiExampleLang),
+ );
+ const [os, setOs] = useState<AudioApiOs>(
+ storedPrefs.apiExampleOs ?? (deviceType === "windows" ? "windows" : "unix"),
+ );
+ // null until /v1/models answers, so a slow or failed listing never claims nothing is downloaded.
+ const [models, setModels] = useState<AudioApiModel[] | null>(null);
+ const [autoSwitch, setAutoSwitch] = useState<boolean | null>(null);
+ const [copied, setCopied] = useState(false);
+ const [pageModel, setPageModel] = useState<{
+ example: AudioApiExample;
+ model: string;
+ } | null>(null);
+ const sectionRef = useRef<HTMLElement | null>(null);
+ const audioApiRequested = useSettingsDialogStore((s) => s.audioApiRequested);
+ const scrollTarget = useSettingsDialogStore((s) => s.scrollTarget);
+
+ useEffect(() => {
+ if (!audioApiRequested) return;
+ const next = audioApiExampleFor(audioApiRequested.workflow);
+ setTab(next.tab);
+ if (next.run) setRun(next.run);
+ setPageModel(
+ audioApiRequested.model
+ ? {
+ example:
+ next.tab === "workflows" ? (next.run ?? "separate") : next.tab,
+ model: audioApiRequested.model,
+ }
+ : null,
+ );
+ useSettingsDialogStore.getState().consumeAudioApiRequest();
+ }, [audioApiRequested]);
+
+ useEffect(() => {
+ if (scrollTarget !== "api-keys-audio-api") return;
+ const section = sectionRef.current;
+ if (!section) return;
+ // Consumed only after the user scrolls: clearing it re-runs this effect, whose cleanup stops the pinning.
+ const pin = () => section.scrollIntoView({ block: "start" });
+ const observer = new ResizeObserver(pin);
+ observer.observe(section.parentElement ?? section);
+ const release = () => {
+ observer.disconnect();
+ useSettingsDialogStore
+ .getState()
+ .consumeScrollTarget("api-keys-audio-api");
+ };
+ const timer = window.setTimeout(release, 1500);
+ const events = ["wheel", "touchmove", "keydown"] as const;
+ for (const name of events) {
+ window.addEventListener(name, release, { passive: true });
+ }
+ return () => {
+ observer.disconnect();
+ window.clearTimeout(timer);
+ for (const name of events) window.removeEventListener(name, release);
+ };
+ }, [scrollTarget]);
+
+ useEffect(() => watchAudioModels(listOpenAIAudioModels, setModels), []);
+
+ useEffect(() => {
+ let cancelled = false;
+ loadOpenAIAutoSwitchSettings().then(
+ (settings) => !cancelled && setAutoSwitch(settings.enabled),
+ () => undefined,
+ );
+ // The Model auto-switch switch sits in this same tab.
+ const unsubscribe = subscribeOpenAIAutoSwitchSettings((settings) =>
+ setAutoSwitch(settings.enabled),
+ );
+ return () => {
+ cancelled = true;
+ unsubscribe();
+ };
+ }, []);
+
+ const origin = typeof window !== "undefined" ? window.location.origin : "";
+ const base =
+ useTunnel && cloudflareUrl ? cloudflareUrl : (serverUrl ?? origin);
+ const key = audioApiKey(apiKey, {
+ base,
+ tunnel: useTunnel && !!cloudflareUrl,
+ scope: keylessScope,
+ exposure: keylessExposure,
+ });
+ const example: AudioApiExample = tab === "workflows" ? run : tab;
+ const picked =
+ pageModel?.example === example &&
+ audioApiModelFits(models, pageModel.model, example)
+ ? pageModel.model
+ : models
+ ? pickAudioApiModel(models, example)
+ : null;
+ const model = picked ?? AUDIO_API_PLACEHOLDER_MODELS[example];
+ const snippet = useMemo(
+ () =>
+ buildAudioApiSnippet(example, {
+ base,
+ apiKey: key,
+ model,
+ lang,
+ os,
+ }),
+ [base, example, key, lang, model, os],
+ );
+ const placeholder = models !== null && !picked;
+ const needsLoad =
+ !placeholder &&
+ // Transcriptions load their model on request whatever auto-switch says.
+ example !== "transcribe" &&
+ autoSwitch === false &&
+ models !== null &&
+ !models.some((m) => m.id === model && m.loaded);
+ const shikiLang =
+ lang === "curl" ? (os === "windows" ? "powershell" : "bash") : lang;
+
+ const handleCopy = async () => {
+ if (await copyToClipboard(snippet)) {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1800);
+ }
+ };
+
+ return (
+ <section
+ ref={sectionRef}
+ data-settings-label={t("settings.apiKeys.audioApi.title")}
+ className="flex min-w-0 max-w-full scroll-mt-6 flex-col"
+ >
+ <h2 className="settings-heading mb-1 text-sm font-semibold">
+ {t("settings.apiKeys.audioApi.title")}
+ </h2>
+ <p className="mb-2 text-xs leading-relaxed text-muted-foreground">
+ {t("settings.apiKeys.audioApi.description")}
+ </p>
+ <div className="min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-muted/20">
+ <div className="flex min-w-0 flex-wrap items-center justify-between gap-x-2 gap-y-1 border-b border-border px-2 py-1.5">
+ <div className="flex min-w-0 flex-wrap items-center gap-0.5">
+ {AUDIO_API_TABS.map((id) => (
+ <Pill
+ key={id}
+ active={tab === id}
+ onClick={() => {
+ setTab(id);
+ setStoredTab(id);
+ }}
+ >
+ {t(TAB_LABEL[id])}
+ </Pill>
+ ))}
+ </div>
+ <div className="flex min-w-0 flex-wrap items-center gap-0.5">
+ {LANGS.map((item) => (
+ <Pill
+ key={item.id}
+ active={lang === item.id}
+ onClick={() => {
+ setLang(item.id);
+ const stored = audioLangToStore(
+ useSettingsPanelPrefsStore.getState().apiExampleLang,
+ item.id,
+ );
+ if (stored) setStoredLang(stored);
+ }}
+ >
+ {item.label}
+ </Pill>
+ ))}
+ </div>
+ </div>
+ {tab === "workflows" ? (
+ <div className="flex min-w-0 flex-wrap items-center gap-0.5 border-b border-border px-2 py-1.5">
+ {AUDIO_RUN_WORKFLOWS.map((id) => (
+ <Pill key={id} active={run === id} onClick={() => setRun(id)}>
+ {t(RUN_LABEL[id])}
+ </Pill>
+ ))}
+ </div>
+ ) : null}
+ {lang === "curl" ? (
+ <div className="flex min-w-0 items-center gap-0.5 border-b border-border px-2 py-1.5">
+ <Pill
+ active={os === "unix"}
+ onClick={() => {
+ setOs("unix");
+ setStoredOs("unix");
+ }}
+ >
+ {t("settings.apiKeys.osUnix")}
+ </Pill>
+ <Pill
+ active={os === "windows"}
+ onClick={() => {
+ setOs("windows");
+ setStoredOs("windows");
+ }}
+ >
+ {t("settings.apiKeys.osWindows")}
+ </Pill>
+ </div>
+ ) : null}
+ <div className="relative min-w-0">
+ <button
+ type="button"
+ onClick={handleCopy}
+ className="absolute right-2 top-2 z-10 flex items-center gap-1 rounded border border-border bg-background/80 px-1.5 py-1 text-ui-11 text-muted-foreground backdrop-blur transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ aria-label={t("settings.apiKeys.copySnippet")}
+ >
+ <HugeiconsIcon
+ icon={copied ? Tick02Icon : Copy01Icon}
+ className={cn("size-3.5", copied && "text-emerald-600")}
+ />
+ {copied ? t("settings.apiKeys.copied") : t("settings.apiKeys.copy")}
+ </button>
+ <HighlightedCode
+ key={snippet}
+ code={snippet}
+ language={shikiLang}
+ redactFromReload={Boolean(apiKey)}
+ />
+ </div>
+ {placeholder || needsLoad ? (
+ <div className="flex min-w-0 flex-col gap-1 border-t border-border px-3 py-2.5 text-ui-11 leading-snug text-muted-foreground">
+ {placeholder ? (
+ <span>{t("settings.apiKeys.audioApi.placeholderModel")}</span>
+ ) : null}
+ {needsLoad ? (
+ <span>{t("settings.apiKeys.audioApi.autoSwitchOff")}</span>
+ ) : null}
+ </div>
+ ) : null}
+ </div>
+ </section>
+ );
+}
diff --git a/studio/frontend/src/features/settings/components/audio-api-snippets.ts b/studio/frontend/src/features/settings/components/audio-api-snippets.ts
new file mode 100644
index 00000000000..d6c4af4c95a
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/audio-api-snippets.ts
@@ -0,0 +1,775 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+ AUDIO_CPP_MODELS,
+ AUDIO_CPP_REPO,
+ type AudioCppWorkflow,
+ audioCppModelFor,
+ audioCppWorkflowsFor,
+ isAudioCppFolderId,
+ isCloneAndConvertFamilyId,
+ isCloneOnlyFamilyId,
+ isConvertOnlyFamilyId,
+ isSpeakAndCloneFamilyId,
+} from "../../audio/audio-cpp-catalog";
+import { EDIT_ADAPTERS } from "../../audio/edit-adapters";
+import type {
+ KeylessApiAccessExposure,
+ KeylessApiAccessScope,
+} from "../api/keyless-api-access";
+import type { AudioApiModel } from "../api/openai-model-catalog";
+import { psSingle, shSingle } from "./agent-command";
+import { keylessBaseEligible } from "./keyless-example-eligibility";
+
+export type AudioApiTab = "speak" | "clone" | "transcribe" | "workflows";
+export type AudioRunWorkflow = "separate" | "convert" | "music" | "edit";
+export type AudioApiLang = "curl" | "python" | "javascript";
+export type AudioApiOs = "unix" | "windows";
+export type AudioApiExample =
+ | Exclude<AudioApiTab, "workflows">
+ | AudioRunWorkflow;
+
+export const AUDIO_API_TABS: readonly AudioApiTab[] = [
+ "speak",
+ "clone",
+ "transcribe",
+ "workflows",
+];
+export const AUDIO_RUN_WORKFLOWS: readonly AudioRunWorkflow[] = [
+ "separate",
+ "convert",
+ "music",
+ "edit",
+];
+
+const KEY_PLACEHOLDER = "sk-unsloth-YOUR_KEY";
+const KEYLESS_KEY_PLACEHOLDER = "not-needed";
+
+export function audioApiKey(
+ apiKey: string | null | undefined,
+ server: {
+ base: string;
+ tunnel: boolean;
+ scope: KeylessApiAccessScope;
+ exposure: KeylessApiAccessExposure | null;
+ },
+): string {
+ if (apiKey) return apiKey;
+ // Keyless access admits the audio routes only at its "everything else" scope.
+ const keyless =
+ !server.tunnel &&
+ server.scope === "full" &&
+ keylessBaseEligible(server.base, server.scope, server.exposure);
+ return keyless ? KEYLESS_KEY_PLACEHOLDER : KEY_PLACEHOLDER;
+}
+
+// The chat examples store a variant ("pythonTools"); its language carries over.
+export function langFromStored(stored: string | null): AudioApiLang {
+ if (stored?.startsWith("python")) return "python";
+ if (stored?.startsWith("javascript")) return "javascript";
+ return "curl";
+}
+
+// null: the chat card's stored variant already carries this language.
+export function audioLangToStore(
+ stored: string | null,
+ lang: AudioApiLang,
+): string | null {
+ return stored && langFromStored(stored) === lang ? null : lang;
+}
+
+export function audioApiExampleFor(workflow: AudioCppWorkflow): {
+ tab: AudioApiTab;
+ run: AudioRunWorkflow | null;
+} {
+ return workflow === "speak" ||
+ workflow === "clone" ||
+ workflow === "transcribe"
+ ? { tab: workflow, run: null }
+ : { tab: "workflows", run: workflow };
+}
+
+const folder = (name: string) => `${AUDIO_CPP_REPO}/${name}`;
+
+export const AUDIO_API_PLACEHOLDER_MODELS: Record<AudioApiExample, string> = {
+ speak: folder("Kokoro-82M-GGUF"),
+ clone: folder("VoxCPM2-GGUF"),
+ transcribe: folder("Parakeet-TDT-0.6B-v3-GGUF"),
+ separate: folder("HTDemucs-GGUF"),
+ convert: folder("Chatterbox-GGUF"),
+ music: folder("ACE-Step1.5-GGUF"),
+ edit: folder("DotTTS-Edit-GGUF"),
+};
+
+// The page can hand over any resident model (a chat one too), so /v1/models must list it once it answers.
+export function audioApiModelFits(
+ models: readonly AudioApiModel[] | null,
+ id: string,
+ example: AudioApiExample,
+): boolean {
+ if (models === null) {
+ const known = audioCppModelFor(id);
+ return !!known && audioCppWorkflowsFor(known).includes(example);
+ }
+ const listed = models.find((model) => model.id === id);
+ return !!listed && canRun(listed, example);
+}
+
+// The row's advertised workflows decide; else the audio.cpp catalog, then family hints for unknown repos.
+function canRun(model: AudioApiModel, example: AudioApiExample): boolean {
+ if (model.workflows?.length) return model.workflows.includes(example);
+ if (example === "transcribe") {
+ return model.task === "automatic-speech-recognition";
+ }
+ if (model.task !== "text-to-speech") return false;
+ const known = audioCppModelFor(model.id);
+ if (known) return audioCppWorkflowsFor(known).includes(example);
+ switch (example) {
+ case "speak":
+ return !isCloneOnlyFamilyId(model.id) && !isConvertOnlyFamilyId(model.id);
+ case "clone":
+ return isCloneOnlyFamilyId(model.id) || isSpeakAndCloneFamilyId(model.id);
+ case "convert":
+ return (
+ isCloneAndConvertFamilyId(model.id) || isConvertOnlyFamilyId(model.id)
+ );
+ default:
+ return false;
+ }
+}
+
+const CATALOG_ORDER = new Map(
+ AUDIO_CPP_MODELS.map((model, index) => [model.id.toLowerCase(), index]),
+);
+
+export function pickAudioApiModel(
+ models: readonly AudioApiModel[],
+ example: AudioApiExample,
+): string | null {
+ const rank = (model: AudioApiModel) => [
+ model.loaded ? 0 : 1,
+ example === "transcribe" && !transcribeWithTimestamps(model.id) ? 1 : 0,
+ CATALOG_ORDER.get(model.id.toLowerCase()) ?? AUDIO_CPP_MODELS.length,
+ ];
+ const fits = models
+ .filter((model) => canRun(model, example))
+ .map((model) => ({ id: model.id, rank: rank(model) }));
+ fits.sort(
+ (a, b) =>
+ a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1] || a.rank[2] - b.rank[2],
+ );
+ return fits[0]?.id ?? null;
+}
+
+// Mirrors ALWAYS_TIMESTAMPED in studio/backend/core/inference/stt_details.py; other engines 400 on timestamps.
+const TIMESTAMPED_FAMILY_HINT =
+ /parakeet[-_]?tdt|moss[-_]?transcribe[-_]?diarize|vibevoice[-_]?asr|kroko/i;
+
+export function transcribeWithTimestamps(model: string): boolean {
+ return isAudioCppFolderId(model) && TIMESTAMPED_FAMILY_HINT.test(model);
+}
+
+export interface AudioApiSnippetInput {
+ base: string;
+ apiKey: string;
+ model: string;
+ lang: AudioApiLang;
+ os: AudioApiOs;
+}
+
+const SPEAK_TEXT = "Hello from Unsloth.";
+const CLONE_TEXT = "This is my voice, speaking text I never recorded.";
+const CLONE_TRANSCRIPT = "The words spoken in me.wav.";
+const EDIT_FROM = "The quick brown fox jumps over the lazy dog.";
+const EDIT_TO = "The quick red fox jumps over the lazy dog.";
+
+type Ref = { upload: string };
+type Json = string | number | boolean | Ref | Json[] | { [key: string]: Json };
+
+function isRef(value: Json): value is Ref {
+ return typeof value === "object" && value !== null && "upload" in value;
+}
+
+type Style = "json" | "python" | "jq" | "powershell";
+
+function refExpr(name: string, style: Style): string {
+ switch (style) {
+ case "python":
+ return `${name}["id"]`;
+ case "jq":
+ return `$${name}`;
+ case "powershell":
+ return `"$($${name}.id)"`;
+ default:
+ return `${name}.id`;
+ }
+}
+
+function scalar(value: string | number | boolean, style: Style): string {
+ if (typeof value === "boolean" && style === "python") {
+ return value ? "True" : "False";
+ }
+ const text = JSON.stringify(value);
+ // An expandable here-string reads ` and $ as escapes.
+ return style === "powershell" ? text.replace(/[`$]/g, "`$&") : text;
+}
+
+function render(value: Json, style: Style, indent = ""): string {
+ if (isRef(value)) return refExpr(value.upload, style);
+ if (typeof value !== "object") return scalar(value, style);
+ const inner = `${indent}${style === "python" ? " " : " "}`;
+ const entries = Array.isArray(value)
+ ? value.map((item) => `${inner}${render(item, style, inner)}`)
+ : Object.entries(value).map(
+ ([key, item]) =>
+ `${inner}${JSON.stringify(key)}: ${render(item, style, inner)}`,
+ );
+ const [open, close] = Array.isArray(value) ? ["[", "]"] : ["{", "}"];
+ return entries.length
+ ? `${open}\n${entries.join(",\n")}\n${indent}${close}`
+ : `${open}${close}`;
+}
+
+const j = (value: string) => JSON.stringify(value);
+
+// Mirrors the rvc family in audio_cpp_models.py: built-in voices only, a target recording is refused.
+const BUILTIN_VOICE_CONVERTER = /(^|[-_ /.])rvc([-_ /.]|$)/i;
+// Mirrors the music specs there: Stable Audio's SFX build and ControlFoley make no songs.
+const SFX_ONLY_MUSIC = /(^|[-_ /.])sfx([-_ /.]|$)|controlfoley/i;
+
+function editFamily(model: string): string {
+ if (/firered/i.test(model)) return "firered_audio";
+ if (/vevo[-_]?2/i.test(model)) return "vevo2";
+ return "dots_tts";
+}
+
+interface RunPlan {
+ uploads: { name: string; file: string }[];
+ body: { [key: string]: Json };
+}
+
+function runPlan(workflow: AudioRunWorkflow, model: string): RunPlan {
+ switch (workflow) {
+ case "separate":
+ return {
+ uploads: [{ name: "source", file: "song.wav" }],
+ body: {
+ workflow,
+ model,
+ inputs: { source: { input_id: { upload: "source" } } },
+ },
+ };
+ case "convert":
+ if (BUILTIN_VOICE_CONVERTER.test(model)) {
+ return {
+ uploads: [{ name: "source", file: "speech.wav" }],
+ body: {
+ workflow,
+ model,
+ inputs: { source: { input_id: { upload: "source" } } },
+ convert: { voice: "default" },
+ },
+ };
+ }
+ return {
+ uploads: [
+ { name: "source", file: "speech.wav" },
+ { name: "target", file: "voice.wav" },
+ ],
+ body: {
+ workflow,
+ model,
+ inputs: {
+ source: { input_id: { upload: "source" } },
+ target: { input_id: { upload: "target" } },
+ },
+ },
+ };
+ case "music":
+ if (SFX_ONLY_MUSIC.test(model)) {
+ return {
+ uploads: [],
+ body: {
+ workflow,
+ model,
+ mode: "sfx",
+ text: "Rain on a tin roof with distant thunder",
+ },
+ };
+ }
+ return {
+ uploads: [],
+ body: {
+ workflow,
+ model,
+ mode: "song",
+ text: "Upbeat synth pop with a catchy chorus",
+ lyrics:
+ "[verse]\nCity lights are calling me\n[chorus]\nWe dance until the morning",
+ },
+ };
+ default: {
+ const edit = Object.fromEntries(
+ Object.entries(
+ EDIT_ADAPTERS[editFamily(model)].buildEdit({
+ transcript: EDIT_FROM,
+ edited: EDIT_TO,
+ mode: "words",
+ }),
+ ),
+ );
+ return {
+ uploads: [{ name: "source", file: "speech.wav" }],
+ body: {
+ workflow,
+ model,
+ text: EDIT_TO,
+ inputs: {
+ source: { input_id: { upload: "source" } },
+ reference_text: EDIT_FROM,
+ },
+ edit,
+ },
+ };
+ }
+ }
+}
+
+function bashPreamble(base: string, apiKey: string): string {
+ return `BASE='${shSingle(base)}'\nKEY='${shSingle(apiKey)}'\n`;
+}
+
+function powershellPreamble(base: string, apiKey: string): string {
+ return `$base = '${psSingle(base)}'\n$key = '${psSingle(apiKey)}'\n`;
+}
+
+function bashUpload(name: string, file: string): string {
+ return `${name.toUpperCase()}=$(curl -sSf "$BASE/v1/audio/inputs?name=${file}" \\
+ -H "Authorization: Bearer $KEY" \\
+ --data-binary @${file} | jq -r .id)`;
+}
+
+function powershellUpload(name: string, file: string): string {
+ return `$${name} = curl.exe -sSf "$base/v1/audio/inputs?name=${file}" \`
+ -H "Authorization: Bearer $key" \`
+ --data-binary "@${file}" | ConvertFrom-Json`;
+}
+
+function bashBody(body: { [key: string]: Json }, refs: string[]): string {
+ if (refs.length === 0) return `'${shSingle(render(body, "json", " "))}'`;
+ const args = refs
+ .map((ref) => `--arg ${ref} "$${ref.toUpperCase()}"`)
+ .join(" ");
+ return `"$(jq -n ${args} '${shSingle(render(body, "jq", " "))}')"`;
+}
+
+function powershellBody(body: { [key: string]: Json }): string {
+ return `$body = @"\n${render(body, "powershell")}\n"@
+Set-Content -Path body.json -Value $body -Encoding ascii`;
+}
+
+interface ClientNeeds {
+ sdk: boolean;
+ studio: boolean;
+ upload: boolean;
+ longRuns: boolean;
+ toFile?: boolean;
+}
+
+const SDK_ONLY: ClientNeeds = {
+ sdk: true,
+ studio: false,
+ upload: false,
+ longRuns: false,
+};
+const SDK_AND_UPLOADS: ClientNeeds = {
+ sdk: true,
+ studio: true,
+ upload: true,
+ longRuns: false,
+};
+
+function pythonClient(
+ base: string,
+ apiKey: string,
+ { sdk, studio, upload }: ClientNeeds,
+): string {
+ const imports = [
+ ...(studio ? ["import httpx"] : []),
+ ...(sdk ? ["from openai import OpenAI"] : []),
+ ];
+ let out = `${imports.join("\n")}
+
+BASE = ${j(base)}
+KEY = ${j(apiKey)}
+`;
+ if (sdk) {
+ out += `
+client = OpenAI(base_url=f"{BASE}/v1", api_key=KEY)`;
+ }
+ if (studio) {
+ out += `${sdk ? "\n" : ""}
+# Uploads, saved voices and workflow runs are Studio routes the OpenAI SDK has no method for.
+studio = httpx.Client(base_url=BASE, headers={"Authorization": f"Bearer {KEY}"}, timeout=None)
+
+
+def post(path, **kwargs):
+ response = studio.post(path, **kwargs)
+ response.raise_for_status()
+ return response.json()`;
+ }
+ if (upload) {
+ out += `
+
+
+def upload(file):
+ with open(file, "rb") as audio:
+ return post("/v1/audio/inputs", params={"name": file}, content=audio.read())`;
+ }
+ return out;
+}
+
+function javascriptClient(
+ base: string,
+ apiKey: string,
+ { sdk, studio, upload, longRuns, toFile }: ClientNeeds,
+): string {
+ let out = `import fs from "node:fs";
+${sdk ? `import OpenAI${toFile ? ", { toFile }" : ""} from "openai";\n` : ""}${longRuns ? 'import { Agent, setGlobalDispatcher } from "undici";\n' : ""}
+const BASE = ${j(base)};
+const KEY = ${j(apiKey)};`;
+ if (longRuns) {
+ out += `
+
+// fetch stops waiting for a response after 5 minutes; a long run takes longer than that.
+setGlobalDispatcher(new Agent({ headersTimeout: 0, bodyTimeout: 0 }));`;
+ }
+ if (sdk) {
+ out += `
+
+const client = new OpenAI({ baseURL: BASE + "/v1", apiKey: KEY });`;
+ }
+ if (studio) {
+ out += `
+
+// Uploads, saved voices and workflow runs are Studio routes the OpenAI SDK has no method for.
+async function studio(path, init = {}) {
+ const response = await fetch(BASE + path, {
+ ...init,
+ headers: { Authorization: "Bearer " + KEY, ...init.headers },
+ });
+ if (!response.ok) throw new Error(await response.text());
+ return response;
+}`;
+ }
+ if (upload) {
+ out += `
+
+async function upload(file) {
+ const response = await studio("/v1/audio/inputs?name=" + file, {
+ method: "POST",
+ body: fs.readFileSync(file),
+ });
+ return response.json();
+}`;
+ }
+ return out;
+}
+
+function speakSnippet({
+ base,
+ apiKey,
+ model,
+ lang,
+ os,
+}: AudioApiSnippetInput): string {
+ const body = {
+ model,
+ input: SPEAK_TEXT,
+ voice: "alloy",
+ response_format: "mp3",
+ };
+ const voiceNote =
+ "voice: a saved voice id or one of the model's own speakers. Other names, like alloy, keep its default voice.";
+ if (lang === "python") {
+ return `${pythonClient(base, apiKey, SDK_ONLY)}
+
+# ${voiceNote}
+with client.audio.speech.with_streaming_response.create(
+ model=${j(model)},
+ voice="alloy",
+ input=${j(SPEAK_TEXT)},
+ response_format="mp3",
+) as speech:
+ speech.stream_to_file("speech.mp3")`;
+ }
+ if (lang === "javascript") {
+ return `${javascriptClient(base, apiKey, SDK_ONLY)}
+
+// ${voiceNote}
+const speech = await client.audio.speech.create({
+ model: ${j(model)},
+ voice: "alloy",
+ input: ${j(SPEAK_TEXT)},
+ response_format: "mp3",
+});
+fs.writeFileSync("speech.mp3", Buffer.from(await speech.arrayBuffer()));`;
+ }
+ if (os === "windows") {
+ return `${powershellPreamble(base, apiKey)}# ${voiceNote}
+${powershellBody(body)}
+curl.exe -f "$base/v1/audio/speech" \`
+ -H "Authorization: Bearer $key" \`
+ -H "Content-Type: application/json" \`
+ -d "@body.json" -o speech.mp3`;
+ }
+ return `${bashPreamble(base, apiKey)}# ${voiceNote}
+curl -f "$BASE/v1/audio/speech" \\
+ -H "Authorization: Bearer $KEY" \\
+ -H "Content-Type: application/json" \\
+ -d ${bashBody(body, [])} \\
+ -o speech.mp3`;
+}
+
+function cloneSnippet({
+ base,
+ apiKey,
+ model,
+ lang,
+ os,
+}: AudioApiSnippetInput): string {
+ const voice: { [key: string]: Json } = {
+ name: "Me",
+ source: { input_id: { upload: "recording" } },
+ transcript: CLONE_TRANSCRIPT,
+ };
+ const speech: { [key: string]: Json } = {
+ model,
+ input: CLONE_TEXT,
+ voice: { upload: "voice" },
+ response_format: "mp3",
+ };
+ const steps =
+ "Upload a short recording of the voice, save it as a voice, then speak in it.";
+ const transcriptNote =
+ "transcript: what me.wav says. Some models need it to clone.";
+ if (lang === "python") {
+ return `${pythonClient(base, apiKey, SDK_AND_UPLOADS)}
+
+
+# ${steps}
+recording = upload("me.wav")
+# ${transcriptNote}
+voice = post("/v1/audio/voices", json=${render(voice, "python")})
+
+with client.audio.speech.with_streaming_response.create(
+ model=${j(model)},
+ voice=voice["id"],
+ input=${j(CLONE_TEXT)},
+ response_format="mp3",
+) as speech:
+ speech.stream_to_file("clone.mp3")`;
+ }
+ if (lang === "javascript") {
+ return `${javascriptClient(base, apiKey, SDK_AND_UPLOADS)}
+
+// ${steps}
+const recording = await upload("me.wav");
+// ${transcriptNote}
+const saved = await studio("/v1/audio/voices", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(${render(voice, "json").replace(/\n/g, "\n ")}),
+});
+const voice = await saved.json();
+
+const speech = await client.audio.speech.create({
+ model: ${j(model)},
+ voice: voice.id,
+ input: ${j(CLONE_TEXT)},
+ response_format: "mp3",
+});
+fs.writeFileSync("clone.mp3", Buffer.from(await speech.arrayBuffer()));`;
+ }
+ if (os === "windows") {
+ return `${powershellPreamble(base, apiKey)}# ${steps}
+${powershellUpload("recording", "me.wav")}
+# ${transcriptNote}
+${powershellBody(voice)}
+$voice = curl.exe -sSf "$base/v1/audio/voices" \`
+ -H "Authorization: Bearer $key" \`
+ -H "Content-Type: application/json" \`
+ -d "@body.json" | ConvertFrom-Json
+${powershellBody(speech)}
+curl.exe -f "$base/v1/audio/speech" \`
+ -H "Authorization: Bearer $key" \`
+ -H "Content-Type: application/json" \`
+ -d "@body.json" -o clone.mp3`;
+ }
+ return `${bashPreamble(base, apiKey)}# ${steps}
+${bashUpload("recording", "me.wav")}
+# ${transcriptNote}
+VOICE=$(curl -sSf "$BASE/v1/audio/voices" \\
+ -H "Authorization: Bearer $KEY" \\
+ -H "Content-Type: application/json" \\
+ -d ${bashBody(voice, ["recording"])} | jq -r .id)
+curl -f "$BASE/v1/audio/speech" \\
+ -H "Authorization: Bearer $KEY" \\
+ -H "Content-Type: application/json" \\
+ -d ${bashBody(speech, ["voice"])} \\
+ -o clone.mp3`;
+}
+
+function transcribeSnippet({
+ base,
+ apiKey,
+ model,
+ lang,
+ os,
+}: AudioApiSnippetInput): string {
+ const timed = transcribeWithTimestamps(model);
+ if (lang === "python") {
+ const options = timed
+ ? `
+ response_format="verbose_json",
+ timestamp_granularities=["segment"],
+ language="en",`
+ : "";
+ const output = timed
+ ? `for segment in transcript.segments:
+ print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text}")`
+ : "print(transcript.text)";
+ return `${pythonClient(base, apiKey, SDK_ONLY)}
+
+with open("speech.wav", "rb") as audio:
+ transcript = client.audio.transcriptions.create(
+ model=${j(model)},
+ file=audio,${options.replace(/\n {4}/g, "\n ")}
+ )
+${output}`;
+ }
+ if (lang === "javascript") {
+ const options = timed
+ ? `
+ response_format: "verbose_json",
+ timestamp_granularities: ["segment"],
+ language: "en",`
+ : "";
+ const output = timed
+ ? `for (const segment of transcript.segments ?? []) {
+ console.log(\`[\${segment.start.toFixed(1)}s - \${segment.end.toFixed(1)}s] \${segment.text}\`);
+}`
+ : "console.log(transcript.text);";
+ return `${javascriptClient(base, apiKey, { ...SDK_ONLY, toFile: true })}
+
+const transcript = await client.audio.transcriptions.create({
+ model: ${j(model)},
+ // A read stream uploads chunked, and Studio refuses uploads without a Content-Length.
+ file: await toFile(fs.readFileSync("speech.wav"), "speech.wav"),${options}
+});
+${output}`;
+ }
+ const fields = [
+ `model=${model}`,
+ ...(timed
+ ? [
+ "response_format=verbose_json",
+ "timestamp_granularities[]=segment",
+ "language=en",
+ ]
+ : []),
+ ];
+ if (os === "windows") {
+ return `${powershellPreamble(base, apiKey)}curl.exe "$base/v1/audio/transcriptions" \`
+ -H "Authorization: Bearer $key" \`
+${fields.map((field) => ` -F '${psSingle(field)}'`).join(" `\n")}`;
+ }
+ return `${bashPreamble(base, apiKey)}curl "$BASE/v1/audio/transcriptions" \\
+ -H "Authorization: Bearer $KEY" \\
+${fields.map((field) => ` -F '${shSingle(field)}'`).join(" \\\n")}`;
+}
+
+function runSnippet(
+ workflow: AudioRunWorkflow,
+ { base, apiKey, model, lang, os }: AudioApiSnippetInput,
+): string {
+ const { uploads, body } = runPlan(workflow, model);
+ const refs = uploads.map((item) => item.name);
+ const needs = {
+ sdk: false,
+ studio: true,
+ upload: uploads.length > 0,
+ longRuns: true,
+ };
+ const save =
+ workflow === "separate"
+ ? "Saves each stem as <clip id>.wav."
+ : "Saves each clip the run made as <clip id>.wav.";
+ if (lang === "python") {
+ return `${pythonClient(base, apiKey, needs)}
+
+
+${uploads.map((item) => `${item.name} = upload(${j(item.file)})`).join("\n")}${uploads.length ? "\n" : ""}result = post("/v1/audio/run", json=${render(body, "python")})
+
+# ${save}
+for clip in result["clips"]:
+ audio = studio.get(clip["url"])
+ audio.raise_for_status()
+ with open(f"{clip['id']}.wav", "wb") as out:
+ out.write(audio.content)`;
+ }
+ if (lang === "javascript") {
+ return `${javascriptClient(base, apiKey, needs)}
+
+${uploads.map((item) => `const ${item.name} = await upload(${j(item.file)});`).join("\n")}${uploads.length ? "\n" : ""}const run = await studio("/v1/audio/run", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(${render(body, "json").replace(/\n/g, "\n ")}),
+});
+const result = await run.json();
+
+// ${save}
+for (const clip of result.clips) {
+ const audio = await studio(clip.url);
+ fs.writeFileSync(clip.id + ".wav", Buffer.from(await audio.arrayBuffer()));
+}`;
+ }
+ if (os === "windows") {
+ return `${powershellPreamble(base, apiKey)}${uploads.map((item) => `${powershellUpload(item.name, item.file)}\n`).join("")}${powershellBody(body)}
+$result = curl.exe -sSf "$base/v1/audio/run" \`
+ -H "Authorization: Bearer $key" \`
+ -H "Content-Type: application/json" \`
+ -d "@body.json" | ConvertFrom-Json
+# ${save}
+foreach ($clip in $result.clips) {
+ curl.exe -sSf "$base$($clip.url)" -H "Authorization: Bearer $key" -o "$($clip.id).wav"
+}`;
+ }
+ return `${bashPreamble(base, apiKey)}${uploads.map((item) => `${bashUpload(item.name, item.file)}\n`).join("")}# ${save}
+curl -sSf "$BASE/v1/audio/run" \\
+ -H "Authorization: Bearer $KEY" \\
+ -H "Content-Type: application/json" \\
+ -d ${bashBody(body, refs)} \\
+ | jq -r '.clips[] | .id + " " + .url' \\
+ | while read -r id url; do
+ curl -sSf "$BASE$url" -H "Authorization: Bearer $KEY" -o "$id.wav"
+ done`;
+}
+
+export function buildAudioApiSnippet(
+ example: AudioApiExample,
+ input: AudioApiSnippetInput,
+): string {
+ switch (example) {
+ case "speak":
+ return speakSnippet(input);
+ case "clone":
+ return cloneSnippet(input);
+ case "transcribe":
+ return transcribeSnippet(input);
+ default:
+ return runSnippet(example, input);
+ }
+}
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index d6482ffb6ab..9bd78a0a8d1 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -32,7 +32,14 @@ import {
InformationCircleIcon,
} from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ useSyncExternalStore,
+} from "react";
import { Streamdown } from "streamdown";
import { loadCodingAgents } from "../api/coding-agents";
import type {
@@ -58,6 +65,7 @@ import {
import { keylessBaseEligible } from "./keyless-example-eligibility";
import {
readUseTunnelPref,
+ subscribeUseTunnelPref,
writeUseTunnelPref,
} from "./tunnel-preference";
@@ -396,6 +404,16 @@ const CATALOG_RETRY_MS = 15000;
// keep polling after a model appears because idle unloads do not update the store.
const CATALOG_IDLE_MS = 60000;
+/** The Secure HTTPS switch, shared by every example card on the tab. */
+export function useApiTunnelPref(): [boolean, (next: boolean) => void] {
+ const useTunnel = useSyncExternalStore(
+ subscribeUseTunnelPref,
+ readUseTunnelPref,
+ () => true,
+ );
+ return [useTunnel, writeUseTunnelPref];
+}
+
// match the backend path heuristic because /v1 never advertises on-disk checkpoints.
function looksLikePath(id: string): boolean {
return (
@@ -522,7 +540,7 @@ const SHIKI_THEMES = [unslothLightTheme, unslothDarkTheme] as [
];
const codePlugin = createCodePlugin({ themes: SHIKI_THEMES });
-function HighlightedCode({
+export function HighlightedCode({
code,
language,
redactFromReload,
@@ -554,11 +572,15 @@ function HighlightedCode({
export function UsageExamples({
apiKey,
+ useTunnel,
+ onUseTunnelChange,
keylessScope = "off",
keylessTools = false,
keylessExposure = null,
}: {
apiKey?: string | null;
+ useTunnel: boolean;
+ onUseTunnelChange: (next: boolean) => void;
/** which routes keyless api access serves, so a placeholder is only used where it works */
keylessScope?: KeylessApiAccessScope;
/** whether a keyless caller may drive the server-side tool loop */
@@ -610,7 +632,6 @@ export function UsageExamples({
// isGguf at the moment of a hand-made pick, null if there has been none this session.
// A manual pick is kept only until the model's GGUF-ness changes under it.
const clickedUnderGgufRef = useRef<boolean | null>(null);
- const [useTunnel, setUseTunnel] = useState<boolean>(readUseTunnelPref);
const origin = typeof window !== "undefined" ? window.location.origin : "";
const base =
useTunnel && cloudflareUrl ? cloudflareUrl : (serverUrl ?? origin);
@@ -843,11 +864,6 @@ export function UsageExamples({
}
};
- const handleToggleTunnel = (next: boolean) => {
- setUseTunnel(next);
- writeUseTunnelPref(next);
- };
-
const handleCopyUrl = async () => {
if (cloudflareUrl && (await copyToClipboard(cloudflareUrl))) {
setCopiedUrl(true);
@@ -875,7 +891,7 @@ export function UsageExamples({
<Switch
size="sm"
checked={useTunnel}
- onCheckedChange={handleToggleTunnel}
+ onCheckedChange={onUseTunnelChange}
aria-label={t("settings.apiKeys.secureHttps")}
/>
<span className="text-ui-11 font-medium text-foreground">
diff --git a/studio/frontend/src/features/settings/settings-search.ts b/studio/frontend/src/features/settings/settings-search.ts
index f85458f0841..2e069128c5e 100644
--- a/studio/frontend/src/features/settings/settings-search.ts
+++ b/studio/frontend/src/features/settings/settings-search.ts
@@ -223,6 +223,7 @@ export const SETTINGS_SEARCH_INDEX: Record<SettingsTab, TranslationKey[]> = {
"settings.apiKeys.title",
"settings.apiKeys.description",
"settings.apiKeys.accessTokens",
+ "settings.apiKeys.audioApi.title",
"settings.apiKeys.decisionApi.title",
"settings.apiKeys.mcp.title",
],
diff --git a/studio/frontend/src/features/settings/stores/settings-dialog-store.ts b/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
index f561b0a9be2..b9573bc49a2 100644
--- a/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
+++ b/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
@@ -32,6 +32,7 @@ export type SettingsTab = (typeof SETTINGS_TABS)[number];
export type SettingsScrollTarget =
| "about-updates"
+ | "api-keys-audio-api"
| "api-keys-decision-api"
| "appearance-sidebar-nav"
| "chat-composer"
@@ -45,6 +46,18 @@ export type SettingsScrollTarget =
| "sandbox-os"
| "sandbox-permissions";
+export interface AudioApiRequest {
+ workflow:
+ | "speak"
+ | "clone"
+ | "edit"
+ | "convert"
+ | "music"
+ | "separate"
+ | "transcribe";
+ model: string | null;
+}
+
/** Which archive the Data tab should open straight into. */
export type ArchivedShelf = "chats" | "images" | "videos" | "audio";
@@ -74,12 +87,16 @@ interface SettingsDialogState {
// Set when something asks for one connection's settings (the picker's Connected group gear).
// ConnectionsTab hands it to the form, then clears it. Same lifetime as archivedRequested.
connectionRequested: string | null;
+ // The Audio API card applies it, then clears it. Same lifetime as archivedRequested.
+ audioApiRequested: AudioApiRequest | null;
decisionTryRequested: string | null;
openDialog: (tab?: SettingsTab, options?: OpenDialogOptions) => void;
openArchivedChats: () => void;
openArchivedMedia: (shelf: Exclude<ArchivedShelf, "chats">) => void;
/** Open Connections with `providerId`'s edit form already up. */
openConnectionSettings: (providerId: string) => void;
+ openAudioApi: (request: AudioApiRequest) => void;
+ consumeAudioApiRequest: () => void;
consumeArchivedChatsRequest: () => void;
openLogs: (family?: string, sourcePath?: string | null) => void;
consumeLogFamilyRequest: () => void;
@@ -143,6 +160,7 @@ function loadInitialTab(): SettingsTab {
const SCROLL_TARGET_TAB: Record<SettingsScrollTarget, SettingsTab> = {
"chat-composer": "chat",
"about-updates": "about",
+ "api-keys-audio-api": "api-keys",
"api-keys-decision-api": "api-keys",
"appearance-sidebar-nav": "appearance",
"browser-html-network": "browser",
@@ -187,6 +205,7 @@ function requestsFor(state: SettingsDialogState, tab: SettingsTab) {
tab === "debugging" ? state.logSourcePathRequested : null,
connectionRequested:
tab === "connections" ? state.connectionRequested : null,
+ audioApiRequested: tab === "api-keys" ? state.audioApiRequested : null,
};
}
@@ -214,6 +233,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logSourcePathRequested: null,
logRequestSeq: 0,
connectionRequested: null,
+ audioApiRequested: null,
decisionTryRequested: null,
openDialog: (requestedTab, options) =>
set((state) => {
@@ -229,6 +249,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logFamilyRequested: pending.logFamilyRequested,
logSourcePathRequested: pending.logSourcePathRequested,
connectionRequested: pending.connectionRequested,
+ audioApiRequested: pending.audioApiRequested,
...focusForOpen(state, options?.focusFallback, options?.opener),
};
}),
@@ -241,6 +262,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logFamilyRequested: null,
logSourcePathRequested: null,
connectionRequested: null,
+ audioApiRequested: null,
...focusForOpen(state),
})),
openArchivedMedia: (shelf) =>
@@ -252,6 +274,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logFamilyRequested: null,
logSourcePathRequested: null,
connectionRequested: null,
+ audioApiRequested: null,
...focusForOpen(state),
})),
openConnectionSettings: (providerId) =>
@@ -263,8 +286,22 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logFamilyRequested: null,
logSourcePathRequested: null,
connectionRequested: providerId,
+ audioApiRequested: null,
+ ...focusForOpen(state),
+ })),
+ openAudioApi: (request) =>
+ set((state) => ({
+ open: true,
+ activeTab: "api-keys",
+ scrollTarget: "api-keys-audio-api",
+ archivedRequested: null,
+ logFamilyRequested: null,
+ logSourcePathRequested: null,
+ connectionRequested: null,
+ audioApiRequested: request,
...focusForOpen(state),
})),
+ consumeAudioApiRequest: () => set({ audioApiRequested: null }),
consumeArchivedChatsRequest: () => set({ archivedRequested: null }),
openLogs: (family, sourcePath) =>
set((state) => ({
@@ -276,6 +313,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logSourcePathRequested: sourcePath ?? null,
logRequestSeq: state.logRequestSeq + 1,
connectionRequested: null,
+ audioApiRequested: null,
...focusForOpen(state),
})),
consumeLogFamilyRequest: () =>
@@ -309,6 +347,7 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set) => ({
logFamilyRequested: null,
logSourcePathRequested: null,
connectionRequested: null,
+ audioApiRequested: null,
decisionTryRequested: null,
}),
setActiveTab: (tab) => {
diff --git a/studio/frontend/src/features/settings/stores/settings-panel-prefs-store.ts b/studio/frontend/src/features/settings/stores/settings-panel-prefs-store.ts
index a41484f9d83..3c4c9800f2c 100644
--- a/studio/frontend/src/features/settings/stores/settings-panel-prefs-store.ts
+++ b/studio/frontend/src/features/settings/stores/settings-panel-prefs-store.ts
@@ -32,6 +32,9 @@ export interface SettingsPanelPrefsState {
setApiExampleLang: (lang: string) => void;
setApiExampleOs: (os: ExampleOs) => void;
setApiExampleAgent: (agent: string | null) => void;
+ // the Audio API card's tab (speak, clone, transcribe, workflows).
+ apiAudioExample: string | null;
+ setApiAudioExample: (tab: string) => void;
// null mcpOs follows the detected device type.
mcpAgent: string | null;
@@ -95,6 +98,7 @@ function sanitize(
? (raw.apiExampleOs as ExampleOs)
: null,
apiExampleAgent: text(raw.apiExampleAgent),
+ apiAudioExample: text(raw.apiAudioExample),
mcpAgent: text(raw.mcpAgent),
mcpOs: EXAMPLE_OS_VALUES.find((os) => os === raw.mcpOs) ?? null,
resourcesLiveUpdates:
@@ -128,6 +132,8 @@ export const useSettingsPanelPrefsStore = create<SettingsPanelPrefsState>()(
setApiExampleLang: (apiExampleLang) => set({ apiExampleLang }),
setApiExampleOs: (apiExampleOs) => set({ apiExampleOs }),
setApiExampleAgent: (apiExampleAgent) => set({ apiExampleAgent }),
+ apiAudioExample: null,
+ setApiAudioExample: (apiAudioExample) => set({ apiAudioExample }),
mcpAgent: null,
mcpOs: null,
diff --git a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
index 48f86546f65..0f0a1fcd3e8 100644
--- a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
@@ -20,6 +20,7 @@ import type {
KeylessApiAccessScope,
} from "../api/keyless-api-access";
import { ApiKeyRow } from "../components/api-key-row";
+import { AudioApiExamples } from "../components/audio-api-examples";
import { CreateKeyForm } from "../components/create-key-form";
import { DecisionApiSection } from "../components/decision-api-section";
import { KeyRevealCard } from "../components/key-reveal-card";
@@ -29,7 +30,10 @@ import { McpAccessSection } from "../components/mcp-access-section";
import { ModelAutoSwitchSection } from "../components/model-auto-switch-section";
import { MonitorLink } from "../components/monitor-link";
import { RemoteAccessSection } from "../components/remote-access-section";
-import { UsageExamples } from "../components/usage-examples";
+import {
+ UsageExamples,
+ useApiTunnelPref,
+} from "../components/usage-examples";
export function ApiKeysTab() {
const t = useT();
@@ -40,6 +44,7 @@ export function ApiKeysTab() {
const [revokeTarget, setRevokeTarget] = useState<ApiKey | null>(null);
const [revoking, setRevoking] = useState(false);
const [revealed, setRevealed] = useState<string | null>(null);
+ const [useTunnel, setUseTunnel] = useApiTunnelPref();
const [keyless, setKeyless] = useState<{
scope: KeylessApiAccessScope;
tools: boolean;
@@ -201,11 +206,20 @@ export function ApiKeysTab() {
<UsageExamples
apiKey={revealed}
+ useTunnel={useTunnel}
+ onUseTunnelChange={setUseTunnel}
keylessScope={keyless.scope}
keylessTools={keyless.tools}
keylessExposure={keyless.exposure}
/>
+ <AudioApiExamples
+ apiKey={revealed}
+ useTunnel={useTunnel}
+ keylessScope={keyless.scope}
+ keylessExposure={keyless.exposure}
+ />
+
{isOwner ? <DecisionApiSection /> : null}
{isOwner ? <McpAccessSection apiKey={revealed} /> : null}
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 064a27353e8..b0d560427ff 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -3013,6 +3013,22 @@ export const ar = {
"ستفقد التطبيقات التي تستخدم هذا التوكن الوصول فورًا. لا يمكن التراجع عن هذا الإجراء.",
revokeAction: 'إلغاء "{name}"',
revoking: "جارٍ الإلغاء...",
+ audioApi: {
+ title: "واجهة برمجة الصوت",
+ description: "الكلام واستنساخ الصوت والتفريغ النصي وسير عمل صفحة الصوت.",
+ speak: "تحدّث",
+ clone: "استنساخ",
+ transcribe: "تفريغ نصي",
+ workflows: "سير العمل",
+ separate: "فصل",
+ convert: "تحويل",
+ music: "موسيقى",
+ edit: "تعديل",
+ placeholderModel: "لا يوجد بعد نموذج منزّل يمكنه تشغيل هذا المثال، لذا فالنموذج المعروض مجرد مثال. نزّل نموذجًا من صفحة الصوت أولًا.",
+ autoSwitchOff:
+ "يُحمَّل النموذج باسمه فقط عند تفعيل التبديل التلقائي للنموذج. فعّله، أو حمّل النموذج من صفحة الصوت الخاصة به أولًا.",
+ useViaApi: "الاستخدام عبر API",
+ },
decisionApi: {
title: "واجهة القرارات البرمجية",
docs: "التوثيق",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index c658cdfd1cb..a5ffeb66319 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -3058,6 +3058,22 @@ export const de = {
"Apps, die dieses Token verwenden, verlieren sofort den Zugriff. Dies kann nicht rückgängig gemacht werden.",
revokeAction: "„{name}“ widerrufen",
revoking: "Wird widerrufen...",
+ audioApi: {
+ title: "Audio-API",
+ description: "Sprache, Stimmklonen, Transkription und die Workflows der Audio-Seite.",
+ speak: "Sprechen",
+ clone: "Klonen",
+ transcribe: "Transkribieren",
+ workflows: "Workflows",
+ separate: "Trennen",
+ convert: "Umwandeln",
+ music: "Musik",
+ edit: "Bearbeiten",
+ placeholderModel: "Noch kann kein heruntergeladenes Modell dieses Beispiel ausführen, daher ist das gezeigte Modell nur ein Platzhalter. Lade zuerst eines auf der Audio-Seite herunter.",
+ autoSwitchOff:
+ "Das Modell wird nur per Name geladen, wenn der automatische Modellwechsel an ist. Schalte ihn ein oder lade das Modell zuerst auf seiner Audio-Seite.",
+ useViaApi: "Per API nutzen",
+ },
decisionApi: {
title: "Entscheidungs-API",
docs: "Dokumentation",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index d99e643d574..eaa00751a6c 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -3060,6 +3060,23 @@ export const en = {
"Apps using this token immediately lose access. This cannot be undone.",
revokeAction: 'Revoke "{name}"',
revoking: "Revoking...",
+ audioApi: {
+ title: "Audio API",
+ description: "Speech, voice cloning, transcription and the Audio page workflows.",
+ speak: "Speak",
+ clone: "Clone",
+ transcribe: "Transcribe",
+ workflows: "Workflows",
+ separate: "Separate",
+ convert: "Convert",
+ music: "Music",
+ edit: "Edit",
+ placeholderModel:
+ "No downloaded model can run this example yet, so the model shown is a stand-in. Download one on the Audio page first.",
+ autoSwitchOff:
+ "The model loads by name only while Model auto-switch is on. Turn it on, or load the model on its Audio page first.",
+ useViaApi: "Use via API",
+ },
decisionApi: {
title: "Decision API",
docs: "Docs",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index c0937b4ad6c..224cc08762f 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -3051,6 +3051,22 @@ export const es = {
"Las apps que usan este token pierden el acceso de inmediato. Esto no se puede deshacer.",
revokeAction: 'Revocar "{name}"',
revoking: "Revocando...",
+ audioApi: {
+ title: "API de audio",
+ description: "Voz, clonación de voz, transcripción y los flujos de la página Audio.",
+ speak: "Hablar",
+ clone: "Clonar",
+ transcribe: "Transcribir",
+ workflows: "Flujos",
+ separate: "Separar",
+ convert: "Convertir",
+ music: "Música",
+ edit: "Editar",
+ placeholderModel: "Aún no hay ningún modelo descargado que pueda ejecutar este ejemplo, así que el modelo que aparece es provisional. Descarga uno primero en la página Audio.",
+ autoSwitchOff:
+ "El modelo solo se carga por su nombre con el cambio automático de modelo activado. Actívalo o carga antes el modelo en su página de Audio.",
+ useViaApi: "Usar por API",
+ },
decisionApi: {
title: "API de decisiones",
docs: "Documentación",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index e3a9faa2886..a50af87479c 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -3059,6 +3059,22 @@ export const fr = {
"Les applications utilisant ce jeton perdent immédiatement l’accès. Cette action est irréversible.",
revokeAction: 'Révoquer "{name}"',
revoking: "Révocation...",
+ audioApi: {
+ title: "API audio",
+ description: "Synthèse vocale, clonage de voix, transcription et les flux de la page Audio.",
+ speak: "Parler",
+ clone: "Cloner",
+ transcribe: "Transcrire",
+ workflows: "Flux",
+ separate: "Séparer",
+ convert: "Convertir",
+ music: "Musique",
+ edit: "Modifier",
+ placeholderModel: "Aucun modèle téléchargé ne peut encore exécuter cet exemple : le modèle affiché n'est qu'un exemple. Téléchargez-en un d'abord sur la page Audio.",
+ autoSwitchOff:
+ "Le modèle ne se charge par son nom que si le changement automatique de modèle est activé. Activez-le, ou chargez d'abord le modèle sur sa page Audio.",
+ useViaApi: "Utiliser via l'API",
+ },
decisionApi: {
title: "API de décision",
docs: "Documentation",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index a53a5585e00..ef39a5c135a 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -3130,6 +3130,23 @@ export const he = {
"יישומים המשתמשים בטוקן זה יאבדו גישה באופן מיידי. לא ניתן לבטל פעולה זו.",
revokeAction: 'בטל את "{name}"',
revoking: "מבטל...",
+ audioApi: {
+ title: "API שמע",
+ description: "דיבור, שיבוט קול, תמלול ותהליכי העבודה של דף השמע.",
+ speak: "דיבור",
+ clone: "שיבוט",
+ transcribe: "תמלול",
+ workflows: "תהליכי עבודה",
+ separate: "הפרדה",
+ convert: "המרה",
+ music: "מוזיקה",
+ edit: "עריכה",
+ placeholderModel:
+ "אף מודל שהורד עדיין לא יכול להריץ את הדוגמה הזו, ולכן המודל המוצג הוא ממלא מקום. הורד קודם מודל בדף השמע.",
+ autoSwitchOff:
+ "המודל נטען לפי שם רק כשהחלפת מודל אוטומטית פועלת. הפעל אותה, או טען קודם את המודל בדף השמע שלו.",
+ useViaApi: "שימוש דרך API",
+ },
decisionApi: {
title: "ממשק API להחלטות",
docs: "תיעוד",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index d31037bc003..e5d93d6a595 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -3020,6 +3020,22 @@ export const hi = {
"इस टोकन का उपयोग करने वाले ऐप तुरंत एक्सेस खो देंगे। इसे पूर्ववत नहीं किया जा सकता।",
revokeAction: '"{name}" रद्द करें',
revoking: "रद्द किया जा रहा है...",
+ audioApi: {
+ title: "ऑडियो API",
+ description: "स्पीच, वॉइस क्लोनिंग, ट्रांसक्रिप्शन और ऑडियो पेज के वर्कफ़्लो।",
+ speak: "बोलें",
+ clone: "क्लोन",
+ transcribe: "ट्रांसक्राइब",
+ workflows: "वर्कफ़्लो",
+ separate: "अलग करें",
+ convert: "बदलें",
+ music: "संगीत",
+ edit: "संपादित करें",
+ placeholderModel: "अभी कोई डाउनलोड किया गया मॉडल यह उदाहरण नहीं चला सकता, इसलिए दिखाया गया मॉडल सिर्फ़ उदाहरण के लिए है। पहले ऑडियो पेज पर एक मॉडल डाउनलोड करें।",
+ autoSwitchOff:
+ "मॉडल नाम से तभी लोड होता है जब मॉडल ऑटो-स्विच चालू हो। इसे चालू करें, या पहले मॉडल को उसके ऑडियो पेज पर लोड करें।",
+ useViaApi: "API से इस्तेमाल करें",
+ },
decisionApi: {
title: "निर्णय API",
docs: "दस्तावेज़",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index e844544714c..6f228e08d01 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -2964,6 +2964,22 @@ export const it = {
"Le app che usano questo token perdono immediatamente l'accesso. L'operazione è irreversibile.",
revokeAction: "Revoca «{name}»",
revoking: "Revoca in corso...",
+ audioApi: {
+ title: "API audio",
+ description: "Sintesi vocale, clonazione della voce, trascrizione e i flussi della pagina Audio.",
+ speak: "Parla",
+ clone: "Clona",
+ transcribe: "Trascrivi",
+ workflows: "Flussi",
+ separate: "Separa",
+ convert: "Converti",
+ music: "Musica",
+ edit: "Modifica",
+ placeholderModel: "Nessun modello scaricato può ancora eseguire questo esempio, quindi il modello mostrato è solo indicativo. Scaricane prima uno dalla pagina Audio.",
+ autoSwitchOff:
+ "Il modello si carica per nome solo con il cambio automatico del modello attivo. Attivalo, oppure carica prima il modello dalla sua pagina Audio.",
+ useViaApi: "Usa via API",
+ },
decisionApi: {
title: "API decisionale",
docs: "Documentazione",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 9f28f106b4c..d843e1a1f27 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -2983,6 +2983,22 @@ export const ja = {
revokeDescription: "このトークンを使用しているアプリはすぐにアクセスできなくなります。この操作は取り消せません。",
revokeAction: '"{name}" を失効',
revoking: "失効中...",
+ audioApi: {
+ title: "オーディオ API",
+ description: "音声合成、ボイスクローン、文字起こし、オーディオページのワークフロー。",
+ speak: "読み上げ",
+ clone: "クローン",
+ transcribe: "文字起こし",
+ workflows: "ワークフロー",
+ separate: "分離",
+ convert: "変換",
+ music: "音楽",
+ edit: "編集",
+ placeholderModel: "この例を実行できるダウンロード済みモデルがまだないため、表示中のモデルは仮のものです。先にオーディオページでモデルをダウンロードしてください。",
+ autoSwitchOff:
+ "モデルの自動切り替えがオンのときだけ、名前でモデルが読み込まれます。オンにするか、先にそのモデルをオーディオページで読み込んでください。",
+ useViaApi: "API で使う",
+ },
decisionApi: {
title: "判定 API",
docs: "ドキュメント",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index feaba8629bf..bb409076aab 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -3003,6 +3003,22 @@ export const ko = {
"이 토큰을 사용하는 앱은 즉시 접근 권한을 잃습니다. 이 작업은 되돌릴 수 없습니다.",
revokeAction: '"{name}" 폐기',
revoking: "폐기 중...",
+ audioApi: {
+ title: "오디오 API",
+ description: "음성 합성, 음성 복제, 받아쓰기, 오디오 페이지 워크플로.",
+ speak: "말하기",
+ clone: "복제",
+ transcribe: "받아쓰기",
+ workflows: "워크플로",
+ separate: "분리",
+ convert: "변환",
+ music: "음악",
+ edit: "편집",
+ placeholderModel: "아직 이 예제를 실행할 수 있는 다운로드한 모델이 없어 표시된 모델은 임시 예시입니다. 먼저 오디오 페이지에서 모델을 다운로드하세요.",
+ autoSwitchOff:
+ "모델 자동 전환이 켜져 있을 때만 이름으로 모델을 불러옵니다. 자동 전환을 켜거나 먼저 오디오 페이지에서 모델을 불러오세요.",
+ useViaApi: "API로 사용",
+ },
decisionApi: {
title: "판단 API",
docs: "문서",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 5857cf9f021..9821cd442f4 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -3030,6 +3030,22 @@ export const ptBR = {
"Aplicativos que usam este token perderão o acesso imediatamente. Esta ação não pode ser desfeita.",
revokeAction: 'Revogar "{name}"',
revoking: "Revogando...",
+ audioApi: {
+ title: "API de áudio",
+ description: "Fala, clonagem de voz, transcrição e os fluxos da página Áudio.",
+ speak: "Falar",
+ clone: "Clonar",
+ transcribe: "Transcrever",
+ workflows: "Fluxos",
+ separate: "Separar",
+ convert: "Converter",
+ music: "Música",
+ edit: "Editar",
+ placeholderModel: "Nenhum modelo baixado consegue rodar este exemplo ainda, então o modelo mostrado é só ilustrativo. Baixe um antes na página Áudio.",
+ autoSwitchOff:
+ "O modelo só é carregado pelo nome com a troca automática de modelo ativada. Ative-a ou carregue antes o modelo na página de Áudio dele.",
+ useViaApi: "Usar via API",
+ },
decisionApi: {
title: "API de decisões",
docs: "Documentação",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index d5b061da224..2073b40f9a7 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -3025,6 +3025,22 @@ export const ru = {
"Приложения, использующие этот токен, немедленно потеряют доступ. Это действие нельзя отменить.",
revokeAction: 'Отозвать «{name}»',
revoking: "Отзыв...",
+ audioApi: {
+ title: "Audio API",
+ description: "Синтез речи, клонирование голоса, транскрипция и сценарии страницы «Аудио».",
+ speak: "Озвучить",
+ clone: "Клонировать",
+ transcribe: "Транскрибировать",
+ workflows: "Сценарии",
+ separate: "Разделить",
+ convert: "Преобразовать",
+ music: "Музыка",
+ edit: "Изменить",
+ placeholderModel: "Пока ни одна загруженная модель не может выполнить этот пример, поэтому указанная модель — лишь заглушка. Сначала скачайте модель на странице «Аудио».",
+ autoSwitchOff:
+ "Модель загружается по имени, только когда включено автопереключение моделей. Включите его или сначала загрузите модель на её странице «Аудио».",
+ useViaApi: "Через API",
+ },
decisionApi: {
title: "API решений",
docs: "Документация",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index cba80063396..6779fb343a8 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -3230,6 +3230,23 @@ export const sv = {
"Appar som använder denna token förlorar åtkomsten omedelbart. Det går inte att ångra.",
revokeAction: "Återkalla ”{name}”",
revoking: "Återkallar ...",
+ audioApi: {
+ title: "Ljud-API",
+ description: "Tal, röstkloning, transkribering och ljudsidans arbetsflöden.",
+ speak: "Tala",
+ clone: "Klona",
+ transcribe: "Transkribera",
+ workflows: "Arbetsflöden",
+ separate: "Separera",
+ convert: "Konvertera",
+ music: "Musik",
+ edit: "Redigera",
+ placeholderModel:
+ "Ingen nedladdad modell kan köra det här exemplet än, så modellen som visas är en platshållare. Ladda ned en på ljudsidan först.",
+ autoSwitchOff:
+ "Modellen läses in via namn bara när automatiskt modellbyte är på. Slå på det, eller läs in modellen på dess ljudsida först.",
+ useViaApi: "Använd via API",
+ },
decisionApi: {
title: "Decision API",
docs: "Dokumentation",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index ea0448abc72..c3648f1ac38 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -2962,6 +2962,22 @@ export const zhCN = {
"使用此 token 的应用会立即失去访问权限。此操作无法撤销。",
revokeAction: "撤销“{name}”",
revoking: "撤销中...",
+ audioApi: {
+ title: "音频 API",
+ description: "语音合成、声音克隆、转写以及音频页面的工作流。",
+ speak: "朗读",
+ clone: "克隆",
+ transcribe: "转写",
+ workflows: "工作流",
+ separate: "分离",
+ convert: "转换",
+ music: "音乐",
+ edit: "编辑",
+ placeholderModel: "还没有能运行此示例的已下载模型,因此显示的模型只是示意。请先在音频页面下载一个模型。",
+ autoSwitchOff:
+ "只有开启模型自动切换时,才会按名称加载模型。请开启它,或先在该模型的音频页面加载模型。",
+ useViaApi: "通过 API 使用",
+ },
decisionApi: {
title: "决策 API",
docs: "文档",
diff --git a/studio/frontend/tests/audio-api-request.test.ts b/studio/frontend/tests/audio-api-request.test.ts
new file mode 100644
index 00000000000..e6b3f806946
--- /dev/null
+++ b/studio/frontend/tests/audio-api-request.test.ts
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { useSettingsDialogStore } from "../src/features/settings/stores/settings-dialog-store.ts";
+
+const store = useSettingsDialogStore;
+const REQUEST = {
+ workflow: "separate",
+ model: "audio-cpp/audio.cpp-gguf/HTDemucs-GGUF",
+} as const;
+
+function reset() {
+ store.setState({
+ open: false,
+ activeTab: "general",
+ scrollTarget: null,
+ audioApiRequested: null,
+ });
+}
+
+test("Use via API opens API keys at the Audio API card", () => {
+ reset();
+ store.getState().openAudioApi(REQUEST);
+ const s = store.getState();
+ assert.equal(s.open, true);
+ assert.equal(s.activeTab, "api-keys");
+ assert.equal(s.scrollTarget, "api-keys-audio-api");
+ assert.deepEqual(s.audioApiRequested, REQUEST);
+ s.consumeAudioApiRequest();
+ assert.equal(store.getState().audioApiRequested, null);
+});
+
+test("an unconsumed request does not outlive leaving the tab or closing", () => {
+ reset();
+ store.getState().openAudioApi(REQUEST);
+ // Reselecting the tab keeps it while the card's chunk may still be loading.
+ store.getState().setActiveTab("api-keys");
+ assert.deepEqual(store.getState().audioApiRequested, REQUEST);
+ store.getState().setActiveTab("general");
+ assert.equal(store.getState().audioApiRequested, null);
+
+ store.getState().openAudioApi(REQUEST);
+ store.getState().closeDialog();
+ assert.equal(store.getState().audioApiRequested, null);
+
+ store.getState().openAudioApi(REQUEST);
+ store.getState().openConnectionSettings("provider-1");
+ assert.equal(store.getState().audioApiRequested, null);
+});
diff --git a/studio/frontend/tests/audio-api-snippets.test.ts b/studio/frontend/tests/audio-api-snippets.test.ts
new file mode 100644
index 00000000000..d21bb1aa74b
--- /dev/null
+++ b/studio/frontend/tests/audio-api-snippets.test.ts
@@ -0,0 +1,423 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+const S = await import(
+ "../src/features/settings/components/audio-api-snippets.ts"
+);
+type Model = Parameters<typeof S.pickAudioApiModel>[0][number];
+
+const BASE = "http://127.0.0.1:8888";
+const KEY = "sk-unsloth-abc";
+const tts = (id: string, loaded = false): Model => ({
+ id,
+ loaded,
+ task: "text-to-speech",
+});
+const asr = (id: string, loaded = false): Model => ({
+ id,
+ loaded,
+ task: "automatic-speech-recognition",
+});
+const cpp = (name: string) => `audio-cpp/audio.cpp-gguf/${name}`;
+
+const PATHS: Record<string, string[]> = {
+ speak: ["/v1/audio/speech"],
+ clone: ["/v1/audio/inputs", "/v1/audio/voices", "/v1/audio/speech"],
+ transcribe: ["/v1/audio/transcriptions"],
+ separate: ["/v1/audio/inputs", "/v1/audio/run"],
+ convert: ["/v1/audio/inputs", "/v1/audio/run"],
+ music: ["/v1/audio/run"],
+ edit: ["/v1/audio/inputs", "/v1/audio/run"],
+};
+
+const EXAMPLES = Object.keys(
+ PATHS,
+) as (keyof typeof S.AUDIO_API_PLACEHOLDER_MODELS)[];
+const VARIANTS = [
+ { lang: "curl", os: "unix" },
+ { lang: "curl", os: "windows" },
+ { lang: "python", os: "unix" },
+ { lang: "javascript", os: "unix" },
+] as const;
+
+test("every example names its routes, the server, the key and the model", () => {
+ for (const example of EXAMPLES) {
+ for (const { lang, os } of VARIANTS) {
+ const model = S.AUDIO_API_PLACEHOLDER_MODELS[example];
+ const code = S.buildAudioApiSnippet(example, {
+ base: BASE,
+ apiKey: KEY,
+ model,
+ lang,
+ os,
+ });
+ const where = `${example} ${lang} ${os}`;
+ for (const path of PATHS[example]) {
+ const call =
+ lang === "curl"
+ ? path
+ : path.replace(
+ /^\/v1\/audio\/(speech|transcriptions)$/,
+ "client.audio.$1",
+ );
+ assert.ok(code.includes(call), `${where}: ${call}`);
+ }
+ assert.ok(code.includes(BASE), `${where}: base`);
+ assert.ok(code.includes(KEY), `${where}: key`);
+ assert.ok(code.includes(model), `${where}: model`);
+ }
+ }
+});
+
+test("Windows curl runs curl.exe with backtick continuations, bash with backslashes", () => {
+ const input = { base: BASE, apiKey: KEY, model: cpp("HTDemucs-GGUF") };
+ const win = S.buildAudioApiSnippet("separate", {
+ ...input,
+ lang: "curl",
+ os: "windows",
+ });
+ assert.match(win, /curl\.exe /);
+ assert.match(win, / `\n/);
+ assert.ok(!/ \\\n/.test(win));
+ assert.match(win, /"input_id": "\$\(\$source\.id\)"/);
+ const unix = S.buildAudioApiSnippet("separate", {
+ ...input,
+ lang: "curl",
+ os: "unix",
+ });
+ assert.match(unix, / \\\n/);
+ assert.ok(!unix.includes("curl.exe"));
+ assert.match(unix, /jq -n --arg source "\$SOURCE"/);
+});
+
+test("model ids and text are escaped for each language", () => {
+ const model = `odd"name'$x`;
+ const input = { base: BASE, apiKey: KEY, model };
+ const python = S.buildAudioApiSnippet("speak", {
+ ...input,
+ lang: "python",
+ os: "unix",
+ });
+ assert.ok(python.includes(`model=${JSON.stringify(model)}`));
+ const js = S.buildAudioApiSnippet("speak", {
+ ...input,
+ lang: "javascript",
+ os: "unix",
+ });
+ assert.ok(js.includes(`model: ${JSON.stringify(model)}`));
+ const bash = S.buildAudioApiSnippet("speak", {
+ ...input,
+ lang: "curl",
+ os: "unix",
+ });
+ const quoted = bash.slice(
+ bash.indexOf("-d '") + 4,
+ bash.indexOf("' \\\n -o"),
+ );
+ assert.equal(JSON.parse(quoted.replace(/'\\''/g, "'")).model, model);
+ const ps = S.buildAudioApiSnippet("speak", {
+ ...input,
+ lang: "curl",
+ os: "windows",
+ });
+ assert.ok(ps.includes('"model": "odd\\"name\'`$x"'));
+});
+
+test("the Edit body follows the model's family", () => {
+ const input = {
+ base: BASE,
+ apiKey: KEY,
+ lang: "python",
+ os: "unix",
+ } as const;
+ const dots = S.buildAudioApiSnippet("edit", {
+ ...input,
+ model: cpp("DotTTS-Edit-GGUF"),
+ });
+ assert.ok(dots.includes('<sub targ=\\"red\\">brown</sub>'));
+ const firered = S.buildAudioApiSnippet("edit", {
+ ...input,
+ model: cpp("FireRedAudio-GGUF"),
+ });
+ assert.ok(firered.includes("Replace 'brown' with 'red'."));
+ const vevo = S.buildAudioApiSnippet("edit", {
+ ...input,
+ model: cpp("Vevo2-GGUF"),
+ });
+ assert.ok(!vevo.includes("markup") && !vevo.includes("instructions"));
+});
+
+test("timestamps are asked for only where the model returns them", () => {
+ assert.ok(S.transcribeWithTimestamps(cpp("Parakeet-TDT-0.6B-v3-GGUF")));
+ assert.ok(S.transcribeWithTimestamps(cpp("MOSS-Transcribe-Diarize-GGUF")));
+ assert.ok(!S.transcribeWithTimestamps(cpp("Qwen3-ASR-0.6B-GGUF")));
+ assert.ok(!S.transcribeWithTimestamps("openai/whisper-large-v3-turbo"));
+ const input = { base: BASE, apiKey: KEY, lang: "curl", os: "unix" } as const;
+ const timed = S.buildAudioApiSnippet("transcribe", {
+ ...input,
+ model: cpp("Parakeet-TDT-0.6B-v3-GGUF"),
+ });
+ assert.ok(timed.includes("timestamp_granularities[]=segment"));
+ const plain = S.buildAudioApiSnippet("transcribe", {
+ ...input,
+ model: "openai/whisper-large-v3-turbo",
+ });
+ assert.ok(
+ !plain.includes("timestamp_granularities") &&
+ !plain.includes("verbose_json"),
+ );
+});
+
+test("the JavaScript transcription uploads a sized file, not a chunked stream", () => {
+ const js = S.buildAudioApiSnippet("transcribe", {
+ base: BASE,
+ apiKey: KEY,
+ model: cpp("Parakeet-TDT-0.6B-v3-GGUF"),
+ lang: "javascript",
+ os: "unix",
+ });
+ assert.ok(js.includes('import OpenAI, { toFile } from "openai";'));
+ assert.ok(
+ js.includes(
+ 'file: await toFile(fs.readFileSync("speech.wav"), "speech.wav")',
+ ),
+ );
+ assert.ok(!js.includes("createReadStream"));
+});
+
+test("each example picks a downloaded model that can run it, loaded first", () => {
+ const models = [
+ tts(cpp("ACE-Step1.5-GGUF")),
+ tts(cpp("Qwen3-TTS-12Hz-0.6B-Base-GGUF")),
+ tts(cpp("Kokoro-82M-GGUF")),
+ tts(cpp("VoxCPM2-GGUF"), true),
+ tts(cpp("RVC-GGUF")),
+ tts(cpp("DotTTS-Edit-GGUF")),
+ asr("openai/whisper-small"),
+ asr(cpp("Parakeet-TDT-0.6B-v3-GGUF"), true),
+ ];
+ assert.equal(S.pickAudioApiModel(models, "speak"), cpp("VoxCPM2-GGUF"));
+ assert.equal(S.pickAudioApiModel(models, "clone"), cpp("VoxCPM2-GGUF"));
+ assert.equal(S.pickAudioApiModel(models, "convert"), cpp("RVC-GGUF"));
+ assert.equal(S.pickAudioApiModel(models, "music"), cpp("ACE-Step1.5-GGUF"));
+ assert.equal(S.pickAudioApiModel(models, "edit"), cpp("DotTTS-Edit-GGUF"));
+ assert.equal(
+ S.pickAudioApiModel(models, "transcribe"),
+ cpp("Parakeet-TDT-0.6B-v3-GGUF"),
+ );
+ assert.equal(
+ S.pickAudioApiModel(
+ [
+ tts(cpp("Breeze-TTS-2-GGUF")),
+ tts(cpp("Kokoro-82M-GGUF")),
+ tts(cpp("Chatterbox-Turbo-GGUF")),
+ ],
+ "speak",
+ ),
+ cpp("Kokoro-82M-GGUF"),
+ );
+ assert.equal(
+ S.pickAudioApiModel(
+ [asr(cpp("Qwen3-ASR-0.6B-GGUF")), asr(cpp("Parakeet-TDT-0.6B-v3-GGUF"))],
+ "transcribe",
+ ),
+ cpp("Parakeet-TDT-0.6B-v3-GGUF"),
+ );
+ assert.equal(S.pickAudioApiModel(models, "separate"), null);
+});
+
+test("music and clone-only models never speak, and an unknown repo uses the family hints", () => {
+ const models = [
+ tts(cpp("ACE-Step1.5-GGUF")),
+ tts(cpp("Qwen3-TTS-12Hz-0.6B-Base-GGUF")),
+ ];
+ assert.equal(S.pickAudioApiModel(models, "speak"), null);
+ assert.equal(
+ S.pickAudioApiModel([tts("someone/IndexTTS2-GGUF")], "clone"),
+ "someone/IndexTTS2-GGUF",
+ );
+ assert.equal(
+ S.pickAudioApiModel([tts("someone/IndexTTS2-GGUF")], "speak"),
+ null,
+ );
+ assert.equal(
+ S.pickAudioApiModel([tts("unsloth/orpheus-3b-0.1-ft")], "speak"),
+ "unsloth/orpheus-3b-0.1-ft",
+ );
+ assert.equal(S.pickAudioApiModel([], "transcribe"), null);
+});
+
+test("a page's model is used only where it can run the example", () => {
+ const listed = [
+ tts(cpp("Kokoro-82M-GGUF")),
+ tts("unsloth/orpheus-3b-0.1-ft"),
+ ];
+ assert.ok(!S.audioApiModelFits(listed, cpp("HTDemucs-GGUF"), "separate"));
+ assert.ok(!S.audioApiModelFits(listed, cpp("HTDemucs-GGUF"), "speak"));
+ assert.ok(!S.audioApiModelFits(listed, cpp("Kokoro-82M-GGUF"), "clone"));
+ assert.ok(S.audioApiModelFits(listed, "unsloth/orpheus-3b-0.1-ft", "speak"));
+ assert.ok(!S.audioApiModelFits(listed, "unsloth/Qwen3-8B-GGUF", "speak"));
+ assert.ok(S.audioApiModelFits(null, cpp("Kokoro-82M-GGUF"), "speak"));
+ assert.ok(!S.audioApiModelFits(null, "unsloth/Qwen3-8B-GGUF", "speak"));
+});
+
+test("the Convert and Music bodies follow what the model accepts", () => {
+ const input = {
+ base: BASE,
+ apiKey: KEY,
+ lang: "python",
+ os: "unix",
+ } as const;
+ const rvc = S.buildAudioApiSnippet("convert", {
+ ...input,
+ model: cpp("RVC-GGUF"),
+ });
+ assert.ok(!rvc.includes("voice.wav") && !rvc.includes('"target"'));
+ assert.ok(rvc.includes('"voice": "default"'));
+ const seed = S.buildAudioApiSnippet("convert", {
+ ...input,
+ model: cpp("SeedVC-MLX-GGUF"),
+ });
+ assert.ok(seed.includes('"target"') && seed.includes("voice.wav"));
+ for (const name of ["Stable-Audio-3-Small-SFX-GGUF", "ControlFoley-GGUF"]) {
+ const sfx = S.buildAudioApiSnippet("music", { ...input, model: cpp(name) });
+ assert.ok(sfx.includes('"mode": "sfx"') && !sfx.includes("lyrics"), name);
+ }
+ const song = S.buildAudioApiSnippet("music", {
+ ...input,
+ model: cpp("Stable-Audio-3-Small-Music-GGUF"),
+ });
+ assert.ok(song.includes('"mode": "song"'));
+});
+
+test("the JavaScript run examples wait past fetch's 5 minute limit", () => {
+ const input = {
+ base: BASE,
+ apiKey: KEY,
+ lang: "javascript",
+ os: "unix",
+ } as const;
+ for (const example of ["separate", "convert", "music", "edit"] as const) {
+ const code = S.buildAudioApiSnippet(example, {
+ ...input,
+ model: S.AUDIO_API_PLACEHOLDER_MODELS[example],
+ });
+ assert.ok(
+ code.includes("setGlobalDispatcher(new Agent({ headersTimeout: 0"),
+ example,
+ );
+ }
+ const speak = S.buildAudioApiSnippet("speak", {
+ ...input,
+ model: cpp("Kokoro-82M-GGUF"),
+ });
+ assert.ok(!speak.includes("undici"));
+});
+
+test("the key is the revealed one, else the placeholder this server admits", () => {
+ const local = {
+ base: "http://127.0.0.1:8888",
+ tunnel: false,
+ exposure: null,
+ };
+ assert.equal(
+ S.audioApiKey("sk-unsloth-real", { ...local, scope: "full" }),
+ "sk-unsloth-real",
+ );
+ assert.equal(S.audioApiKey(null, { ...local, scope: "full" }), "not-needed");
+ assert.equal(
+ S.audioApiKey(null, { ...local, scope: "inference" }),
+ "sk-unsloth-YOUR_KEY",
+ );
+ assert.equal(
+ S.audioApiKey(null, { ...local, scope: "off" }),
+ "sk-unsloth-YOUR_KEY",
+ );
+ assert.equal(
+ S.audioApiKey(null, { ...local, tunnel: true, scope: "full" }),
+ "sk-unsloth-YOUR_KEY",
+ );
+ assert.equal(
+ S.audioApiKey(null, {
+ base: "http://192.168.1.20:8888",
+ tunnel: false,
+ exposure: null,
+ scope: "full",
+ }),
+ "sk-unsloth-YOUR_KEY",
+ );
+});
+
+test("picking a language keeps the chat card's variant of it", () => {
+ assert.equal(S.audioLangToStore("pythonTools", "python"), null);
+ assert.equal(S.audioLangToStore("javascriptAdvanced", "javascript"), null);
+ assert.equal(S.audioLangToStore("pythonTools", "curl"), "curl");
+ assert.equal(S.audioLangToStore(null, "python"), "python");
+ assert.equal(S.langFromStored("curlTools"), "curl");
+});
+
+test("each Audio page opens the example for its workflow", () => {
+ assert.deepEqual(S.audioApiExampleFor("speak"), { tab: "speak", run: null });
+ assert.deepEqual(S.audioApiExampleFor("transcribe"), {
+ tab: "transcribe",
+ run: null,
+ });
+ assert.deepEqual(S.audioApiExampleFor("separate"), {
+ tab: "workflows",
+ run: "separate",
+ });
+ assert.deepEqual(S.audioApiExampleFor("edit"), {
+ tab: "workflows",
+ run: "edit",
+ });
+});
+
+test("the workflows a row advertises win over the name hints", () => {
+ const music = {
+ id: "MiniMaxAI/MiniMax-Music3",
+ loaded: true,
+ task: "text-to-speech" as const,
+ workflows: ["music"],
+ };
+ const separator = {
+ id: cpp("BS-RoFormer-GGUF"),
+ loaded: true,
+ task: "audio-to-audio" as const,
+ workflows: ["separate"],
+ };
+ assert.equal(S.pickAudioApiModel([music], "speak"), null);
+ assert.equal(S.pickAudioApiModel([music], "music"), music.id);
+ assert.equal(S.pickAudioApiModel([separator], "separate"), separator.id);
+ assert.ok(!S.audioApiModelFits([music], music.id, "speak"));
+ assert.ok(S.audioApiModelFits([separator], separator.id, "separate"));
+ assert.ok(!S.audioApiModelFits([], cpp("HTDemucs-GGUF"), "separate"));
+});
+
+test("curl stops on an HTTP error instead of saving it as audio", () => {
+ for (const os of ["unix", "windows"] as const) {
+ for (const example of ["speak", "clone", "separate"] as const) {
+ const snippet = S.buildAudioApiSnippet(example, {
+ base: BASE,
+ apiKey: KEY,
+ model: S.AUDIO_API_PLACEHOLDER_MODELS[example],
+ lang: "curl",
+ os,
+ });
+ for (const line of snippet
+ .split("\n")
+ .filter((l) => /\bcurl(\.exe)? /.test(l))) {
+ assert.match(
+ line,
+ /curl(\.exe)? -(sS)?f /,
+ `${os} ${example}: ${line}`,
+ );
+ }
+ }
+ }
+});
diff --git a/studio/frontend/tests/media-auto-switch-setting.test.ts b/studio/frontend/tests/media-auto-switch-setting.test.ts
index d4fc1171200..d2e511151be 100644
--- a/studio/frontend/tests/media-auto-switch-setting.test.ts
+++ b/studio/frontend/tests/media-auto-switch-setting.test.ts
@@ -52,6 +52,7 @@ globalThis.fetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
const {
invalidateOpenAIAutoSwitchSettings,
loadOpenAIAutoSwitchSettings,
+ subscribeOpenAIAutoSwitchSettings,
updateOpenAIAutoSwitchSettings,
} = await import("../src/features/settings/api/openai-auto-switch.ts");
@@ -105,3 +106,17 @@ test("a false toggle is sent, not dropped as absent", async () => {
media_auto_switch_model: false,
});
});
+
+test("a saved auto-switch value reaches subscribers until they unsubscribe", async () => {
+ invalidateOpenAIAutoSwitchSettings();
+ const seen: boolean[] = [];
+ const unsubscribe = subscribeOpenAIAutoSwitchSettings((settings) =>
+ seen.push(settings.enabled),
+ );
+ nextBody = { ...API, enabled: false };
+ await updateOpenAIAutoSwitchSettings({ enabled: false });
+ unsubscribe();
+ nextBody = { ...API, enabled: true };
+ await updateOpenAIAutoSwitchSettings({ enabled: true });
+ assert.deepEqual(seen, [false]);
+});
diff --git a/studio/frontend/tests/openai-model-catalog.test.ts b/studio/frontend/tests/openai-model-catalog.test.ts
index cf67b61e32b..1dc60fb78a4 100644
--- a/studio/frontend/tests/openai-model-catalog.test.ts
+++ b/studio/frontend/tests/openai-model-catalog.test.ts
@@ -2,29 +2,53 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import assert from "node:assert/strict";
-import test from "node:test";
+import test, { mock } from "node:test";
-import { chatModelsFromCatalog } from "../src/features/settings/api/openai-model-catalog.ts";
+import {
+ audioModelsFromCatalog,
+ chatModelsFromCatalog,
+ watchAudioModels,
+} from "../src/features/settings/api/openai-model-catalog.ts";
test("non-chat entries never reach the chat example picker", () => {
const models = chatModelsFromCatalog({
data: [
{ id: "unsloth/Qwen3-8B-GGUF", loaded: true, quant: "Q4_K_M" },
- { id: "unsloth/Z-Image-Turbo-GGUF", loaded: true, quant: "Q4_K_S", task: "text-to-image" },
+ {
+ id: "unsloth/Z-Image-Turbo-GGUF",
+ loaded: true,
+ quant: "Q4_K_S",
+ task: "text-to-image",
+ },
{ id: "Lightricks/LTX-2", loaded: false, task: "text-to-video" },
{ id: "tiny", loaded: false, task: "automatic-speech-recognition" },
- { id: "unsloth/orpheus-3b-0.1-ft-GGUF", loaded: false, quant: "Q8_0", task: "text-to-speech" },
- { id: "unsloth/Llama-3.2-1B-Instruct-GGUF", loaded: false, task: "text-generation" },
+ {
+ id: "unsloth/orpheus-3b-0.1-ft-GGUF",
+ loaded: false,
+ quant: "Q8_0",
+ task: "text-to-speech",
+ },
+ {
+ id: "unsloth/Llama-3.2-1B-Instruct-GGUF",
+ loaded: false,
+ task: "text-generation",
+ },
],
});
assert.deepEqual(models, [
{ id: "unsloth/Qwen3-8B-GGUF", loaded: true, quant: "Q4_K_M" },
- { id: "unsloth/Llama-3.2-1B-Instruct-GGUF", loaded: false, quant: undefined },
+ {
+ id: "unsloth/Llama-3.2-1B-Instruct-GGUF",
+ loaded: false,
+ quant: undefined,
+ },
]);
});
test("older servers without a task field list every entry as before", () => {
- const models = chatModelsFromCatalog({ data: [{ id: "a", loaded: true }, { id: "b" }] });
+ const models = chatModelsFromCatalog({
+ data: [{ id: "a", loaded: true }, { id: "b" }],
+ });
assert.deepEqual(models, [
{ id: "a", loaded: true, quant: undefined },
{ id: "b", loaded: false, quant: undefined },
@@ -34,5 +58,114 @@ test("older servers without a task field list every entry as before", () => {
test("malformed bodies yield no models", () => {
assert.deepEqual(chatModelsFromCatalog(null), []);
assert.deepEqual(chatModelsFromCatalog({}), []);
- assert.deepEqual(chatModelsFromCatalog({ data: [{ id: 3 }, { id: "" }, {}] }), []);
+ assert.deepEqual(
+ chatModelsFromCatalog({ data: [{ id: 3 }, { id: "" }, {}] }),
+ [],
+ );
+});
+
+test("the audio examples see only speech and transcription models", () => {
+ const models = audioModelsFromCatalog({
+ data: [
+ { id: "unsloth/Qwen3-8B-GGUF", loaded: true, quant: "Q4_K_M" },
+ { id: "unsloth/Z-Image-Turbo-GGUF", loaded: true, task: "text-to-image" },
+ { id: "tiny", loaded: true, task: "automatic-speech-recognition" },
+ {
+ id: "audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF",
+ loaded: false,
+ task: "text-to-speech",
+ },
+ { id: "", task: "text-to-speech" },
+ ],
+ });
+ assert.deepEqual(models, [
+ { id: "tiny", loaded: true, task: "automatic-speech-recognition" },
+ {
+ id: "audio-cpp/audio.cpp-gguf/Kokoro-82M-GGUF",
+ loaded: false,
+ task: "text-to-speech",
+ },
+ ]);
+ assert.deepEqual(audioModelsFromCatalog(null), []);
+});
+
+test("the audio examples keep the workflows a row advertises, separators included", () => {
+ const models = audioModelsFromCatalog({
+ data: [
+ {
+ id: "MiniMaxAI/MiniMax-Music3",
+ loaded: true,
+ task: "text-to-speech",
+ audio_workflows: ["music"],
+ },
+ {
+ id: "audio-cpp/audio.cpp-gguf/BS-RoFormer-GGUF",
+ loaded: true,
+ task: "audio-to-audio",
+ audio_workflows: ["separate", 3],
+ },
+ ],
+ });
+ assert.deepEqual(models, [
+ {
+ id: "MiniMaxAI/MiniMax-Music3",
+ loaded: true,
+ task: "text-to-speech",
+ workflows: ["music"],
+ },
+ {
+ id: "audio-cpp/audio.cpp-gguf/BS-RoFormer-GGUF",
+ loaded: true,
+ task: "audio-to-audio",
+ workflows: ["separate"],
+ },
+ ]);
+});
+
+test("the audio catalog is relisted until a model is resident, then more slowly", async () => {
+ mock.timers.enable({ apis: ["setTimeout"] });
+ try {
+ const answers = [
+ [{ id: "a", task: "text-to-speech" }],
+ null,
+ [{ id: "a", task: "text-to-speech", loaded: true }],
+ [],
+ ];
+ let calls = 0;
+ const seen: unknown[] = [];
+ const list = () => {
+ const next = answers[calls++];
+ return (
+ next === null
+ ? Promise.reject(new Error("offline"))
+ : Promise.resolve(next ?? [])
+ ) as Promise<never>;
+ };
+ const flush = () => new Promise<void>((r) => setImmediate(r));
+ const stop = watchAudioModels(list, (models) => seen.push(models));
+ await flush();
+ assert.equal(calls, 1);
+ mock.timers.tick(15000);
+ await flush();
+ // A failed relist keeps the last answer and retries at the fast pace.
+ assert.equal(calls, 2);
+ assert.equal(seen.length, 1);
+ mock.timers.tick(15000);
+ await flush();
+ assert.equal(calls, 3);
+ assert.equal(seen.length, 2);
+ // Something is resident: the next relist waits the slower beat.
+ mock.timers.tick(15000);
+ await flush();
+ assert.equal(calls, 3);
+ mock.timers.tick(45000);
+ await flush();
+ assert.equal(calls, 4);
+ stop();
+ mock.timers.tick(120000);
+ await flush();
+ assert.equal(calls, 4);
+ } finally {
+ mock.timers.reset();
+ }
});
diff --git a/studio/frontend/tests/settings-panel-prefs.test.ts b/studio/frontend/tests/settings-panel-prefs.test.ts
index 99c9ccf1dc2..323344d7f7e 100644
--- a/studio/frontend/tests/settings-panel-prefs.test.ts
+++ b/studio/frontend/tests/settings-panel-prefs.test.ts
@@ -112,6 +112,21 @@ test("a non-string model is refused rather than handed to the tab", () => {
assert.equal(out.fineTuneAction, "train");
});
+test("the Audio API tab persists and a non-string is dropped", () => {
+ useSettingsPanelPrefsStore.getState().setApiAudioExample("clone");
+ assert.equal(
+ JSON.parse(store.get(KEY) as string).state.apiAudioExample,
+ "clone",
+ );
+ const merged = useSettingsPanelPrefsStore.persist.getOptions().merge;
+ assert.ok(merged);
+ const out = merged(
+ { apiAudioExample: 7 },
+ useSettingsPanelPrefsStore.getState(),
+ ) as { apiAudioExample: unknown };
+ assert.equal(out.apiAudioExample, null);
+});
+
test("a persisted blob cannot replace the store actions", () => {
const merged = useSettingsPanelPrefsStore.persist.getOptions().merge;
assert.ok(merged);