BroadRouter

API로 WhatsApp 음성 메시지를 텍스트로 전사하기

업데이트

ffmpeg로 변환한 뒤 API로 보내면 됩니다. WhatsApp 음성 메시지는 .ogg 파일에 담긴 Opus 오디오라서 전사 엔드포인트가 그대로 받지 않습니다. 각 파일을 16kHz 모노 WAV로 바꾼 다음, 알맞은 language 필드와 함께 BroadNet Transcribe Arabic이나 BroadNet Transcribe로 보내세요. 짧은 스크립트 하나로 폴더 전체를 처리할 수 있습니다.

채팅에서 음성 메시지를 내보내면(또는 WhatsApp Business 연동으로 받으면) .ogg 파일이 생깁니다. Meta의 Cloud API 문서에 따르면 WhatsApp 음성 메시지는 Opus 코덱으로 인코딩된 .ogg 파일입니다. 휴대폰 녹음은 .m4a인 경우가 많습니다. BroadNet 전사 엔드포인트는 WAV와 MP3를 받으므로 먼저 변환하세요.

1. 파일 하나 변환하기

ffmpeg -i voice-note.ogg -ar 16000 -ac 1 voice-note.wav

-ar 16000 -ac 1 옵션은 16kHz 모노 오디오를 만듭니다. BroadNet 문서가 음성 메시지와 휴대폰 녹음에 쓰는 변환 방식입니다. .m4a 파일에도 같은 명령이 통합니다. 16kHz 모노 16비트 WAV는 초당 32,000바이트이므로, 파일 크기 상한인 26,214,400바이트에는 약 13분 분량이 들어갑니다. 더 긴 녹음이라면 오디오 분할 도구가 필요한 조각 수를 계산하고 ffmpeg 명령을 만들어 줍니다.

2. 폴더 전체 전사하기

import os, pathlib, subprocess
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

for src in sorted(pathlib.Path("voice-notes").glob("*.ogg")):
    wav = src.with_suffix(".wav")
    subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-i", str(src), "-ar", "16000", "-ac", "1", str(wav)], check=True)
    with open(wav, "rb") as audio:
        text = client.audio.transcriptions.create(
            model="broadnet/cohere-transcribe-arabic",
            file=audio,
            language="ar",          # use "en", "es", ... with broadnet/cohere-transcribe
        ).text
    src.with_suffix(".txt").write_text(text, encoding="utf-8")
    print(src.name, "->", text[:60])

.txt 파일은 각 음성 메시지 옆에 저장됩니다. 들어오는 WhatsApp Business 메시지마다 같은 단계를 자동으로 실행하려면 n8n WhatsApp 음성 메시지 워크플로를 참고하세요.

비용

1분짜리 음성 메시지의 비용은 아랍어 모델이 $0.0042, 14개 언어 모델이 $0.002입니다. 오디오와 전사 텍스트는 요청이 끝나면 보관되지 않습니다. 데이터 비보관을 참고하세요.

문제 해결

  • 아랍어 대신 라틴 문자가 나올 때: language="ar"를 추가하세요. BroadNet 문서는 language를 항상 보내라고 안내합니다.

  • 413 오류: 파일이 26,214,400바이트(25 MiB)를 넘었습니다. 긴 녹음은 10분 단위 WAV 조각으로 나누세요.

    ffmpeg -i long-note.ogg -ar 16000 -ac 1 -f segment -segment_time 600 part-%03d.wav
  • 업로드할 때 400 또는 422: 파일이 실제로 WAV나 MP3인지, .wav로 이름만 바꾼 .ogg 파일은 아닌지 확인하세요. ffmpeg 변환을 실행하세요.

  • ffmpeg: command not found: 패키지 관리자로 ffmpeg를 설치하세요(예: apt install ffmpeg 또는 brew install ffmpeg).

  • 429 오류: 종량제 키는 동시에 요청 4개까지 허용합니다. 파일을 작은 풀로 나눠 처리하세요. BroadNet 오류 코드 전체를 참고하세요.

모델, 형식, 정확도에 대한 자세한 내용은 아랍어 음성 인식 가이드에 있습니다. 다른 제공업체의 오디오 분당 요금을 비교하려면 공개된 음성 인식 API 가격 지수를 보세요. 모든 가격에 출처와 날짜가 붙어 있습니다. 음성에는 16kHz면 충분한 이유는 샘플링 레이트를 참고하세요.

자주 묻는 질문

WhatsApp 음성 메시지는 어떤 오디오 형식인가요?

Ogg 컨테이너에 담긴 Opus 오디오이며 .ogg 파일로 저장됩니다. Meta의 Cloud API 문서에 따르면 음성 메시지는 Opus 코덱으로 인코딩된 .ogg 파일이어야 하고, 모노만 지원합니다.

.ogg 파일을 전사 API에 그대로 보낼 수 있나요?

BroadNet Inference에는 보낼 수 없습니다. 전사 엔드포인트가 WAV와 MP3를 받으므로 먼저 ffmpeg로 음성 메시지를 변환하세요. 명령 하나로 16kHz 모노 WAV가 됩니다.

전사가 끝난 뒤에도 음성 메시지가 저장되나요?

BroadNet은 오디오와 전사 텍스트가 요청 처리에만 쓰이고 보관되지 않는다고 밝힙니다. 결제와 보안을 위해 처리 시간, 상태, 사용량처럼 내용이 없는 기록만 남깁니다.

아랍어 음성 메시지에는 어떤 모델을 써야 하나요?

BroadNet Transcribe Arabic(broadnet/cohere-transcribe-arabic)을 쓰고 language를 ar로 설정하세요. BroadNet Transcribe(broadnet/cohere-transcribe)가 지원하는 나머지 13개 언어에는 이 모델을 쓰세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기