팟캐스트 현지화, 녹음된 회의록 번역, 또는 강의 더빙을 하려면 예전에는 세 가지 다른 서비스를 연결해야 했습니다. Telnyx AI Inference API는 STT (Speech-to-Text), 채팅 완성(chat completions), TTS (Text-to-Speech) 기능을 동일한 프라이빗 백본에서 제공하므로, 단일 Flask 앱으로 전체 파이프라인을 실행할 수 있습니다.

Telnyx의 코드 예시는 다음과 같습니다:

[https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-content-translator-python]

클론하여 몇 분 안에 실행할 수 있는 Python Flask 앱입니다. 전화번호, 웹훅 터널, 백그라운드 작업 러너가 필요 없습니다.

작동 방식 (The Flow)

사용자가 오디오 파일과 대상 언어를 POST 요청으로 전송합니다. 이 앱은 Telnyx STT를 호출하여 원본 언어로 오디오를 전사(transcribe)하고, AI Inference를 호출하여 TTS에 적합한 시스템 프롬프트와 함께 스크립트를 번역하며, 마지막으로 Telnyx TTS를 호출하여 번역된 텍스트를 오디오로 변환합니다. 긴 스크립트는 문장 경계에서 청킹(chunked)되어 TTS 모델이 지원하는 것보다 큰 입력을 받지 않도록 하며, 이 청크들은 하나의 mp3 파일로 연결됩니다.

응답에는 작업 ID, 두 가지 전사본(transcripts), 그리고 더빙된 오디오를 다운로드할 수 있는 URL이 포함됩니다.

제가 이 예시를 좋아하는 이유 (Why I Like This Example)

실시간 데모를 할 만큼 작으면서도, 오디오 번역 데모에서 종종 빠지는 부분들을 다루고 있습니다:

• 멀티파트 폼 데이터와 쓰기 가능한 임시 파일(writable temp file)을 사용한 파일 업로드
• 단계별 오류 처리가 적용된 세 가지 Telnyx AI 엔드포인트 연결
• 문장 경계에서의 긴 스크립트 청킹
• 원시 오디오, base64를 포함한 JSON, 또는 가져오기(fetch) URL이 포함된 JSON을 반환할 수 있는 TTS 엔드포인트의 응답 형태 처리
• 업로드로 인해 디스크 공간 누수를 막는 임시 파일 정리 기능
• STT의 감지 여부에 따라 자동 언어 감지 (또는 고정된 언어) 지원

가장 중요하게 생각하는 설계 선택은 단계별 오류 처리(per-stage error handling)입니다. 만약 8개 청크 중 3번째 청크에서 TTS 호출이 실패하더라도, STT 및 번역 작업 결과를 버리는 대신 스크립트가 여전히 온전한 상태로 200 partial 응답을 반환합니다.

로컬 환경에서 실행하기 (Run It Locally)

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-content-translator-python
cp .env.example .env
...

스페인어 클립을 영어로 번역하기:

curl -X POST http://localhost:5000/translate \
  -F audio=@spanish-sample.mp3 \
  -F source=es \
...

더빙된 오디오 다운로드하기:

curl -OJ http://localhost:5000/translate/<job_id>/audio

전체 스크립트 읽기:

curl http://localhost:5000/translate/<job_id> | python3 -m json.tool

데모할 내용 (What To Demo)

데모는 간결하게 구성하는 것이 좋겠습니다.

1. 지원되는 세트를 호출하기 위해 /languages 엔드포인트를 보여줍니다.
2. target=en을 지정하여 스페인어 오디오 파일을 POST하고 응답 구조(job_id, transcript 미리보기, audio_url)를 설명합니다.
3. 다운로드한 더빙된 mp3를 재생합니다.
4. 전체 스크립트를 위해 GET /translate/<job_id>를 보여줍니다.
5. (선택 사항) source=auto로 POST하여 언어 감지 기능을 보여줍니다.

이렇게 하면 구현 세부 사항에 빠지지 않으면서도 시청자에게 전체 과정을 보여줄 수 있습니다.

다음 단계로 나아갈 방향 (Where To Take It Next)

현재 데모는 번역 작업을 메모리(in-memory)에 한 시간 동안 유지합니다. 프로덕션 환경에서는 인메모리 jobs 딕셔너리를 오디오 블롭을 위한 오브젝트 스토리지(S3, GCS)와 메타데이터를 위한 데이터베이스(Postgres)로 대체하고, STT/번역/TTS를 큐(queue)에서 실행하며, 긴 작업의 경우 202 Accepted를 반환하고, API 키 인증을 추가하며, 업로드 크기와 오디오 길이에 대한 제한을 사전에 설정할 것입니다.

자료 (Resources)

자료 (Resources)

• 코드 예시(Code example): https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-content-translator-python
• Telnyx AI Inference 문서(docs): https://developers.telnyx.com/docs/inference
• Telnyx 개발자 문서(Developer Docs): https://developers.telnyx.com
• Telnyx 포털(Portal): https://portal.telnyx.com