Soniox | TanStack AI 文档

Soniox 适配器提供对 Soniox 语音转录模型的访问。

安装

npm install @soniox/tanstack-ai-adapter

认证

在您的环境中设置 SONIOX_API_KEY，或在创建适配器时传递 apiKey。从 Soniox 控制台获取您的 API 密钥。

基本用法

typescript

import { generateTranscription } from "@tanstack/ai";
import { sonioxTranscription } from "@soniox/tanstack-ai-adapter";

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio: audioFile,
  modelOptions: {
    enableLanguageIdentification: true,
    enableSpeakerDiarization: true,
  },
});

console.log(result.text);
console.log(result.segments);

基本用法 - 自定义 API 密钥

typescript

import { generateTranscription } from "@tanstack/ai";
import { createSonioxTranscription } from "@soniox/tanstack-ai-adapter";

const adapter = createSonioxTranscription("stt-async-v3", process.env.SONIOX_API_KEY!);

const result = await generateTranscription({
  adapter,
  audio: audioFile,
});

适配器配置

使用 createSonioxTranscription 自定义适配器实例

typescript

import { createSonioxTranscription } from "@soniox/tanstack-ai-adapter";

const adapter = createSonioxTranscription("stt-async-v3", process.env.SONIOX_API_KEY!, {
  baseUrl: "https://api.soniox.com",
  pollingIntervalMs: 1000,
  timeout: 180000,
});

选项

apiKey - 覆盖 SONIOX_API_KEY（在使用 createSonioxTranscription 时必需）
baseUrl - 自定义 API 基本 URL。默认值为 https://api.soniox.com
headers - 额外的请求头
timeout - 语音转录超时时间，单位为毫秒（默认：180000）
pollingIntervalMs - 语音转录轮询间隔，单位为毫秒（默认：1000）

如果您需要数据驻留，请参阅 Soniox 区域端点。

语音转录选项

通过 modelOptions 传递每次请求的选项

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    languageHints: ["en", "es"],
    enableLanguageIdentification: true,
    enableSpeakerDiarization: true,
    context: {
      terms: ["Soniox", "TanStack"],
    },
  },
});

可用选项

languageHints - 用于偏向识别的 ISO 语言代码数组
languageHintsStrict - 当为 true 时，更依赖语言提示（并非所有模型都支持）
enableLanguageIdentification - 自动检测语音语言
enableSpeakerDiarization - 识别和分离不同的说话者
context - 额外的上下文，以提高准确性
clientReferenceId - 可选的客户端定义的参考 ID
webhookUrl - 完成通知的 Webhook URL
webhookAuthHeaderName - Webhook 身份验证头名称
webhookAuthHeaderValue - Webhook 身份验证头值
translation - 翻译配置

有关更多详细信息，请查看 Soniox API 参考。

语言提示

Soniox 自动检测和转录 60 多种语言的语音。当您知道音频中可能出现哪些语言时，提供 languageHints 以提高准确性，通过偏向于这些语言来提高识别度。

语言提示不会限制识别。如果您传递 TanStack language 选项，此适配器会将它合并到 languageHints 中。

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    languageHints: ["en", "es"],
  },
});

有关更多详细信息，请参阅 Soniox 语言提示文档。

Context

提供自定义上下文以提高语音转录和翻译的准确性。上下文有助于模型理解您的领域，识别重要术语并应用自定义词汇。

context 对象支持四个可选部分

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    context: {
      general: [
        { key: "domain", value: "Healthcare" },
        { key: "topic", value: "Diabetes management consultation" },
        { key: "doctor", value: "Dr. Martha Smith" },
      ],
      text: "The patient has a history of...",
      terms: ["Celebrex", "Zyrtec", "Xanax"],
      translationTerms: [
        { source: "Mr. Smith", target: "Sr. Smith" },
        { source: "MRI", target: "RM" },
      ],
    },
  },
});

有关更多详细信息，请参阅 Soniox 上下文文档。

翻译

配置您的语音转录的翻译

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    translation: {
      type: "one_way",
      targetLanguage: "es",
    },
  },
});

对于双向翻译

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    translation: {
      type: "two_way",
      languageA: "en",
      languageB: "es",
    },
  },
});

在使用翻译时，API 会返回语音转录标记和翻译标记。 segments 数组始终仅包含语音转录标记。要访问翻译标记，请使用 providerMetadata 并按 translation_status === "translation" 过滤。

访问原始标记

在使用翻译或处理多语言音频时，您可能需要访问带有每标记语言信息和翻译状态的原始标记。适配器会在运行时附加一个非标准 providerMetadata 字段

typescript

const result = await generateTranscription({
  adapter: sonioxTranscription("stt-async-v3"),
  audio,
  modelOptions: {
    translation: { type: "one_way", targetLanguage: "es" },
  },
});

const rawTokens = (result as any).providerMetadata?.soniox?.tokens;

if (rawTokens) {
  rawTokens.forEach((token) => {
    // token.text - token text
    // token.start_ms - start time in milliseconds
    // token.end_ms - end time in milliseconds
    // token.language - detected language for this token
    // token.translation_status - translation status (if translation enabled)
    // token.speaker - speaker identifier
    // token.confidence - confidence score
  });
}

下一步

Soniox 控制台 - 管理 API 密钥和项目
Soniox API 文档 - 完整的 Soniox API 参考
语音转录指南 - 了解 TanStack AI 中的语音转录