음성-텍스트 변환

POST /v1/audio/transcriptions

오디오를 텍스트로 전사합니다. OpenAI Audio Transcriptions API와 호환됩니다——동일한 엔드포인트가 OpenAI Whisper / GPT-4o-transcribe 모델과 Google Gemini 모델을 모두 처리하며, gateway는 모델 ID에 따라 올바른 업스트림으로 라우팅합니다. 다음 중 하나를 받습니다 multipart/form-data 업로드(OpenAI SDK 호환) 또는 application/json base64로 인코딩된 오디오를 포함하는 본문.

요청 본문

지원되는 모델

어떤 모델을 골라야 할지 모르겠나요? 필요에 맞춰 선택하세요

Diarization = response_format=diarized_json을 설정하면 segments[].speaker를 얻습니다. 기본 업로드 한도 25 MB(오디오 형식 참조).

Google 모델은 Gemini API를 통해, 또는 BYOK Vertex 서비스 계정 키를 사용하여 Google Cloud Vertex AI를 통해 제공될 수 있습니다. 가용성은 워크스페이스에 활성화된 채널에 따라 다릅니다 — /v1/models 을(를) 호출하여 사용 가능한 모델을 확인하세요.

지원되는 오디오 형식

• mp3
• wav
• ogg
• flac
• m4a

multipart 업로드의 경우 형식은 파일명 확장자로부터 추론됩니다. base64(JSON) 요청의 경우 다음을 설정하세요 input_audio.format 을(를) 명시적으로 지정합니다. 최대 업로드 크기: 25 MB.

응답 형식

이 response_format 허용되는 값은 모델에 따라 다릅니다. json 은(는) 모든 모델의 기본값입니다(반환: { text, usage }); text 원시 전사 문자열을 반환합니다.

• whisper-1 — json, text, verbose_json
• gpt-4o-transcribe, gpt-4o-mini-transcribe — json, text
• chirp-3, chirp-2, seed-asr-bigmodel, qwen3-asr-flash, fun-asr-flash — json, text
• gpt-4o-transcribe-diarize, chirp-3, seed-asr-bigmodel, fun-asr, fun-asr-mtl — also diarized_json (화자 레이블이 붙은 세그먼트, 아래 참고)

verbose_json (세그먼트 타임스탬프)는 whisper-1 전용이며,

화자 분리

response_format=diarized_json을 설정하면 화자 라벨이 붙은 세그먼트를 얻습니다. 응답에 segments 배열이 추가되며, 각 항목에는 speaker 라벨과 start/end 타임스탬프(초)가 포함됩니다. gpt-4o-transcribe-diarize(OpenAI), chirp-3(Google), seed-asr-bigmodel(BytePlus — 중국어와 긴 녹음에 가성비 최고), fun-asr / fun-asr-mtl(Alibaba — 오프라인 녹음 파일, URL 또는 파일 허용)에서 지원됩니다. 다른 모델은 diarized_json을 무시하고 일반 텍스트를 반환합니다. chirp-2는 이를 거부합니다(chirp-3 사용).

화자 라벨은 제공업체 고유 방식입니다(예: chirp-3 및 seed-asr는 "0"/"1", gpt-4o-transcribe-diarize는 "A"/"B"). 서로 다른 화자를 구분하지만 안정적인 실제 신원은 아닙니다. gpt-4o-transcribe-diarize에서는 known_speaker_names를 전달해 라벨링을 유도할 수 있습니다.

# Chinese meeting, cheapest diarization (BytePlus seed-asr):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": { "url": "https://your-bucket/signed/meeting.wav", "language": "zh" },
    "response_format": "diarized_json"
  }'

# English / highest quality (Google chirp-3, <=60 s per request):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=chirp-3 \
  -F file=@call.wav \
  -F response_format=diarized_json

응답 예시

{
  "task": "transcribe",
  "text": "喂 你好 我这边是客服 有什么可以帮您",
  "duration": 6.2,
  "segments": [
    { "id": 0, "start": 0.10, "end": 0.90, "speaker": "0", "text": "喂 你好" },
    { "id": 1, "start": 1.20, "end": 6.20, "speaker": "1", "text": "我这边是客服 有什么可以帮您" }
  ]
}

요청 예시 (multipart)

curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=gpt-4o-transcribe \
  -F file=@meeting.mp3 \
  -F response_format=json \
  -F language=en

요청 예시(base64 JSON)

POST /v1/audio/transcriptions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "gpt-4o-transcribe",
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10I...",
    "format": "wav"
  },
  "response_format": "json",
  "language": "en"
}

예시 — 오프라인 ASR (seed-asr-bigmodel)

seed-asr-bigmodel(BytePlus 해외 오프라인 ASR)은 상호 배타적인 두 가지 입력을 받습니다: 가져올 수 있는 input_audio.url(권장 — 직접 발급한 만료 시간이 있는 서명된 객체 스토리지 URL이며, 오디오는 저희 스토리지에 전혀 저장되지 않습니다) 또는 직접 file/바이트 업로드(비공개 버킷에 임시 저장한 뒤 전사 직후 삭제합니다). 제한 사항: 스트리밍 미지원(stream=true는 400 반환); 파일 업로드는 최대 25 MB(더 큰 녹음은 URL 사용); 단일 요청 처리는 약 20분으로 제한되므로 매우 긴 오디오는 분할하세요. 오디오 길이 기준 과금($0.002/min).

# ① Quick test — replace ONLY YOUR_API_KEY and run it (uses our hosted sample audio).
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": {
      "url": "https://synthorai-asr-sample-360831509259.s3.us-west-1.amazonaws.com/seed-asr-sample.wav",
      "language": "zh"
    }
  }'
# → {"text":"..."}

# ② Your own audio file (<=25 MB) — replace key + file path.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=seed-asr-bigmodel \
  -F language=zh \
  -F file=@/path/to/your-audio.wav

# ③ Your own signed URL (recommended for large files / privacy) — replace key + URL.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seed-asr-bigmodel","input_audio":{"url":"https://your-bucket/signed/meeting.wav","language":"zh"}}'

참고 / 주의사항: (1) language는 선택 사항입니다 — 일반적인 값은 zh(표준 중국어), yue-CN(광둥어), en-US이며, 생략하면 자동 감지됩니다. (2) input_audio.url을 사용할 때 해당 URL은 전사 서비스가 공개적으로 가져올 수 있어야 합니다 — 비공개/내부/인증 뒤에 있는 URL은 실패하며, 만료 시간이 있는 서명된(사전 서명된) 객체 스토리지 URL이 권장 방식입니다. (3) 파일 업로드와 URL은 상호 배타적이므로 하나만 선택하세요. (4) 인식 가능한 음성이 없는 오디오(무음)는 오류가 아니라 빈 문자열 {"text":""}와 함께 200을 반환합니다.

예시 — OpenAI Python SDK

이 엔드포인트는 OpenAI 호환이므로 공식 OpenAI SDK는 다음을 재정의하여 바로 사용할 수 있습니다 base_url. whisper-1, gpt-4o-transcribe 및 모든 Gemini 전사 모델에서 동일하게 작동합니다 — 변경할 부분은 model.

from openai import OpenAI

client = OpenAI(
    base_url="https://synthorai.io/v1",
    api_key="YOUR_API_KEY",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=f,
        language="en",
        # prompt="Synthorai, BYOK, transcribe",   # optional vocabulary hint
        response_format="json",
    )

print(result.text)
# Token-level usage on gpt-4o-*:
if getattr(result, "usage", None):
    print(result.usage)

예시 — OpenAI Node.js SDK

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://synthorai.io/v1",
  apiKey: process.env.SYNTHORAI_API_KEY,
});

const result = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  language: "en",
  response_format: "json",
});

console.log(result.text);

스트리밍 (SSE)

설정: stream=true 대상: gpt-4o-transcribe, gpt-4o-mini-transcribe, 또는 모든 Gemini 전사 모델을 사용하면 오디오가 디코딩되는 동안 증분 이벤트를 받을 수 있습니다. 응답의 Content-Type은 text/event-stream 그리고 이벤트는 다음으로 끝납니다 data: [DONE]. whisper-1은 스트리밍을 지원하지 않습니다(설정 시 400 반환 stream=true).

gpt-4o-transcribe에서 볼 수 있는 이벤트 유형:

data: {"type":"transcript.text.delta","delta":"Hello "}

data: {"type":"transcript.text.delta","delta":"world."}

data: {"type":"transcript.text.done","text":"Hello world."}

data: {"type":"usage","usage":{"type":"tokens","input_tokens":689,"output_tokens":287,"total_tokens":976,"input_token_details":{"audio_tokens":689,"text_tokens":0,"cached_tokens":0}}}

data: [DONE]

Gemini streaming은 동일한 SSE 이벤트 이름을 사용하며, 게이트웨이는 동일한 정규화된 usage 객체를 발행하며, 다음에 문서화되어 있습니다 응답 예시— OpenAI와 Gemini에서 동일 — 따라서 클라이언트 코드는 provider 간에 이식 가능합니다. 마지막 usage 이벤트는 항상 전체 input_token_details 내역을 포함하여 정확한 오디오 요율 과금에 사용됩니다.

오류

모든 오류는 OpenAI 엔벨로프 형식을 따릅니다: { error: { message, type, code, param? } }. 일반적인 경우:

• 400 model_not_found ——해당 워크스페이스의 채널에서 모델이 전사 기능을 갖추고 있지 않습니다.
• 400 byok_strict_no_key ——워크스페이스가 엄격한 BYOK 모드이며 (byok_fallback_to_pool=false) 이며 확인된 제공업체에 대한 vault key가 없습니다.
• 400 content_policy_violation ——해당 prompt 필드가 가드레일 규칙을 위반했습니다(예: BYOK key 유출).
• 402 quota_exceeded ——예상 비용이 워크스페이스의 남은 할당량을 초과합니다. BYOK는 예외입니다.
• 408 ——요청 본문이 서버 읽기 타임아웃 내에 업로드를 완료하지 못했습니다. 느린 연결로 큰 오디오를 보낼 때 흔히 발생합니다. 다시 시도하거나 더 작은 파일을 보내세요.
• 413 ——오디오가 25 MB 한도를 초과했습니다.
• 502 upstream_error ——업스트림 네트워크 장애 또는 모델 제공업체의 2xx 이외 응답.

응답 예시

{
  "text": "Thanks for joining today's call. Let's get started.",
  "usage": {
    "type": "tokens",
    "input_tokens": 689,
    "output_tokens": 287,
    "total_tokens": 976,
    "input_token_details": {
      "audio_tokens": 689,
      "text_tokens": 0,
      "cached_tokens": 0
    }
  }
}