본문으로 건너뛰기

Soniox

Soniox 어댑터는 Soniox 전사 모델에 대한 액세스를 제공합니다.

설치​

npm install @soniox/tanstack-ai-adapter

인증​

환경에 SONIOX_API_KEY를 설정하거나 어댑터를 생성할 때 apiKey를 전달합니다. API 키는 Soniox Console에서 발급받습니다.

기본 사용법​

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

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 키​

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

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

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

어댑터 구성​

createSonioxTranscription을 사용하여 어댑터 인스턴스를 사용자 지정합니다.

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를 통해 전달합니다.

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

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 - 완료 알림을 위한 웹훅 URL입니다.
  • webhookAuthHeaderName - 웹훅 인증 헤더 이름입니다.
  • webhookAuthHeaderValue - 웹훅 인증 헤더 값입니다.
  • translation - 번역 구성입니다.

자세한 내용은 Soniox API 레퍼런스를 참조합니다.

언어 힌트​

Soniox는 60개 이상의 언어를 자동으로 감지하고 전사합니다. 오디오에 포함될 가능성이 높은 언어를 알고 있다면 languageHints를 제공하여 해당 언어 쪽으로 인식을 유도하고 정확도를 높입니다.

언어 힌트는 인식을 제한하지 않습니다. TanStack language 옵션을 전달하면 이 어댑터가 해당 값을 languageHints에 병합합니다.

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

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

자세한 내용은 Soniox 언어 힌트 문서를 참조합니다.

컨텍스트​

사용자 지정 컨텍스트를 제공하여 전사 및 번역 정확도를 높입니다. 컨텍스트는 모델이 도메인을 이해하고, 중요한 용어를 인식하며, 사용자 지정 어휘를 적용하도록 돕습니다.

context 객체는 네 가지 선택적 섹션을 지원합니다.

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

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 컨텍스트 문서를 참조합니다.

번역​

전사에 대한 번역을 구성합니다.

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

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

양방향 번역의 경우:

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

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 필드를 연결합니다.

// ignore: providerMetadata is a non-standard runtime extension not on TranscriptionResult;
// accessing it requires a cast that cannot be expressed without `as`.
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
  });
}

다음 단계​