Scribe One 전사 가이드: 요청 한 번에 음성을 텍스트로

Scribe One은 플랫폼에서 가장 작은 엔드포인트이면서, 사람들이 그 위에 엉뚱한 것을 가장 자주 만드는 엔드포인트예요. 오디오 파일을 받아서 그 안에 담긴 말을 돌려줘요. 자막 파일도, 화자가 구분된 대본도, 스트림도 아니고 오직 말만요. 전사 기능을 만드는 일의 대부분은 이 사실에 맞춰 내 쪽 파이프라인을 짜는 일이에요. 그래서 이 엔드포인트를 있는 그대로 소개하고, 거기에 맞는 워크플로를 알려 드릴게요.

요청은 이게 전부예요

multipart POST 한 번이면 끝이에요. 폴링할 작업도, 웹훅도 없어요.

curl https://eroq.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F model=eroq-scribe-one \
  -F [email protected]

응답도 이게 전부예요.

{
  "model": "eroq-scribe-one",
  "text": "That noise is the reactor missing its coolant flush.",
  "usage": { "audio_seconds": 4.2, "credits_spent": 1, "credits_remaining": 882 }
}

file 파트는 반드시 wav 또는 mp3여야 해요. 다른 컨테이너는 몰래 변환되지 않고 unsupported_format으로 거부돼요. 그러니 브라우저에서 녹음한다면 WebAudio로 WAV를 녹음하거나, 업로드 전에 클라이언트에서 다시 인코딩하세요. 녹음기에서 바로 나온 .ogg나 .m4a는 그대로 튕겨 나와요. 전체 파라미터 목록은 전사 레퍼런스에 있어요.

1분에 1크레딧

Scribe One은 오디오가 시작된 1분마다 1 크레딧을 청구해요. 1분을 조금이라도 넘기면 다음 1분이 시작된 것으로 계산해요. 길이는 전사가 실행되기 전에 파일 자체에서 읽고, 응답에는 그 길이가 청구액 옆에 usage.audio_seconds로 표시돼요. 그래서 보낸 오디오와 청구액을 언제든 대조해 볼 수 있어요.

실제로는 이런 뜻이에요.

• 4초짜리 음성 메시지는 1 크레딧이에요. 59초짜리도 똑같고, 61초면 2 크레딧이에요.
• 1시간 분량의 오디오는 어떻게 보내든 60 크레딧이에요. 나눠 보낼 때 추가로 드는 건 올림 비용뿐이에요. 요청마다 마지막 1분을 각각 올림하기 때문에, 30초짜리 클립 20개는 20 크레딧인 반면 같은 10분을 파일 하나로 보내면 10 크레딧이에요.
• 음성 메모는 일부러 저렴하게 설계한 경우예요. 짧은 메시지가 쌓인 받은편지함이라면 하나에 1크레딧씩이라서, 모든 음성 메모와 라이브러리의 모든 클립을 일단 전부 전사해 두는 것도 부담 없는 비용이 돼요.

언어 자동 감지, 그리고 직접 지정할 때

언어는 오디오에서 감지돼요. 필수 파라미터도 없고 언어별로 고를 모델도 없어서, 여러 언어가 섞인 받은편지함도 내 쪽에 라우팅 로직 없이 처리돼요.

선택 항목인 language 필드는 ISO 코드(en, fr, de)를 제약이 아닌 힌트로 받아요. 이 값을 보낼 만한 상황은 딱 두 가지예요. 사용자의 프로필 설정이나 항상 한 언어만 쓰는 채널처럼 맥락에서 이미 언어를 알고 있을 때, 그리고 짧거나 잡음이 많은 오디오의 언어가 잘못 감지될 때예요. 네 단어짜리 클립은 감지기가 판단할 재료가 거의 없는데, 힌트 하나면 공짜로 해결돼요.

8 MB 상한과 그 아래로 맞추는 법

업로드는 8 MB로 제한되고, 문서에서는 이를 압축 오디오 약 8분 분량으로 안내해요. 아카이브가 아니라 음성 메시지 길이의 자료에 맞춘 의도적인 설정이고, 설계할 때 기준으로 삼아야 할 제약이에요.

핵심은 비트레이트예요. 8 MB는 일반적인 팟캐스트 비트레이트로 약 8분이에요. 64 kbps 모노로 다시 인코딩하면 같은 8 MB에 대략 두 배를 담을 수 있고, 말소리에는 이렇다 할 손실이 없어요. 그래서 긴 녹음도 요청 몇 번이면 돼요.

ffmpeg -i episode.mp3 -c:a libmp3lame -b:a 64k -ac 1 \
  -f segment -segment_time 600 part%02d.mp3

64 kbps 모노의 10분 세그먼트는 각각 약 4.8 MB라서, 긴 첫 문장이 들어가도 상한 안에 여유 있게 들어가요. 40분짜리 에피소드는 정확히 10분짜리 요청 네 번이니 전체에 40 크레딧이에요. 분 단위로 딱 떨어지는 세그먼트는 올림할 게 없어서, 한 파일로 보낼 때와 비용이 같아요.

고정 길이로 자를 때 주의할 점이 하나 있어요. 단어 중간에서 잘릴 수 있고, 그러면 잘린 양쪽이 각각 조금씩 틀리게 전사돼요. 이음새가 중요하다면 타이머 대신 무음 구간에서 자르거나, 세그먼트를 1~2초씩 겹치게 자르고 텍스트를 합칠 때 겹친 부분을 걷어내세요.

전사는 미디어 레이트 리밋을 함께 써요. 무료 워크스페이스에서는 키당 분당 6건이고, 플랜에 따라 배수가 곱해져요. 잘게 나눈 에피소드 하나에는 차고 넘치지만, 아카이브를 한꺼번에 소급 처리한다면 알아 둘 만해요. 실패한 요청은 자동으로 환불되니까, 소급 처리 중에 네트워크가 잠깐 끊겨도 헛돈을 내지 않아요.

내 내레이션에 자막 달기

흔한 경우는 이래요. MP3는 있는데 대본이 없어요. 직접 녹음한 것일 수도, 예전 에피소드일 수도, 이제 텍스트로 갖고 싶은 음성 메모일 수도 있어요. 전사한 다음, 타이밍은 이미 타임라인을 쥐고 있는 도구에서 맞추세요.

역할 분담을 분명히 해 두세요. 사람들이 지나치게 기대하는 지점이 바로 여기거든요. Scribe One은 텍스트 덩어리를 돌려줘요. SRT도, VTT도, 단어별 타이밍도 돌려주지 않으니, 혼자서는 타임라인에 자막을 배치할 수 없어요. 대신 정확한 텍스트를 줘요. 자막 도구가 가장 못하는 부분이자, 직접 타이핑하면 가장 오래 걸리는 부분이죠. 이 텍스트를 편집 프로그램의 자막 정렬 기능에 붙여 넣고 타이밍 작업은 거기에 맡기세요.

오디오를 직접 나눴다면 대략적인 타이밍은 덤으로 얻어요. 10분 지점에서 시작하는 세그먼트의 텍스트는 10분 지점에 속하니까요. 큐 단위의 정확도는 여전히 정렬 도구의 몫이지만, 챕터 마커, 쇼 노트, 검색용 인덱스에는 이미 가진 세그먼트 단위 기준점이면 충분해요.

반대 방향으로 가면 루프가 완성돼요. 사용자의 음성 메시지를 전사하고, chat completion으로 답을 만든 다음, 그 답을 /v1/audio/speech로 다시 음성으로 렌더하세요. 음성 입력, 텍스트 추론, 음성 출력까지 호출 세 번이면 되고 스트리밍 인프라도 필요 없어요. 음성 쪽 단계와 지연 시간을 줄이는 요령은 AI 캐릭터를 위한 TTS에서 다뤄요.

한계, 있는 그대로

이 한계에 부딪히지 말고, 이 한계를 전제로 설계하세요.

• 화자 분리 없음. 응답에는 화자 라벨도, 발화 경계도 없어요. 누가 말했는지 알아야 한다면 참여자를 각각 별도 트랙으로 녹음해 하나씩 전사한 다음, 내 쪽에서 타임스탬프 순으로 엮으세요.
• 단어 단위, 세그먼트 단위 타임스탬프 없음. 응답은 text뿐이에요. 타이밍은 오디오를 어떻게 잘랐는지에서 나오거나, 다음 단계의 정렬 도구에서 나와요.
• 자막 파일 없음. SRT도, VTT도, JSON 큐 목록도 없어요.
• 스트리밍, 실시간 전사 없음. 완성된 파일에 대한 요청과 응답이지, 실시간 소켓이 아니에요.
• CLI 명령 없음. eroq CLI는 이미지, 동영상, 음성을 다루고, 전사는 curl이나 SDK 호출로 해요.

이 중 어느 것도 로드맵에 대한 암시가 아니에요. 지금 이 엔드포인트가 하는 일이 이렇다는 뜻이고, 엔드포인트가 충족하지 않는 가정 위에 기능을 설계하는 건 이 사실을 가장 비싸게 알게 되는 방법이에요. 그룹 통화에 화자 라벨이 필요한 제품이라면, 솔직한 답은 파라미터가 아니라 트랙 분리예요.

API의 음성 쪽이 제공하는 기능 전체를 보려면 보이스 플랫폼 페이지를 확인하세요. 엔드포인트가 한곳에 모여 있어요. 음성 텍스트 변환(STT)은 한 문단짜리 정의이고, 소급 처리 규모를 가늠한다면 요금제에서 크레딧 팩을 확인할 수 있어요.

자주 묻는 질문

Scribe One 전사 비용은 얼마인가요?

오디오가 시작된 1분마다 1 크레딧이고, 요청당 최소 1분이 청구돼요. 음성 메모 하나는 1 크레딧, 1시간 분량의 오디오는 60 크레딧이에요. 측정된 길이는 usage.audio_seconds로 돌아오고, 실패한 요청은 자동으로 환불돼요.

전사 엔드포인트는 어떤 오디오 형식을 지원하나요?

WAV와 MP3만 지원해요. 그 밖의 형식은 변환되지 않고 unsupported_format을 반환하니, 먼저 내 쪽에서 다시 인코딩하세요. 녹음 파이프라인이라면 브라우저에서 WebAudio로 WAV를 녹음하는 게 일반적인 해결책이에요.

타임스탬프나 화자 라벨을 받을 수 있나요?

아니요. 응답에는 전사된 텍스트와 usage 블록만 있고, 단어별 타이밍, 세그먼트, 화자 분리는 없어요. 대략적인 타이밍이 필요하면 오디오를 정해진 오프셋으로 자르고, 라벨이 필요하면 화자별로 트랙을 나누고, 자막이 프레임 단위로 정확해야 하면 다음 단계에서 정렬 도구를 돌리세요.

언어를 자동으로 감지하나요?

네, 언어 감지는 자동이고 파라미터가 필요 없어요. 오디오가 짧거나 잡음이 많을 때, 또는 사용자 맥락에서 이미 언어를 알고 있을 때는 language에 ISO 코드를 힌트로 넘길 수 있어요. 추가 비용 없이 정확도가 올라가요.

오디오 파일과 키가 있나요? curl 한 번이면 텍스트가 나와요. API 키를 발급받으면 처음 받는 50 크레딧으로, 돈을 쓰기 전에 오디오 50분을 전사할 수 있어요.