탐색으로 건너뛰기

전사문 편집

이 가이드에서는 음성 텍스트 변환 API를 사용하여 자연어 지침으로 전사문을 편집하는 방법을 소개합니다.

사용 방법 가이드 · 음성 텍스트 변환 빠른 시작을 완료했다고 가정합니다.

개요

전사문 편집은 실험적 기능이며, 기본 전사 비용에 추가로 30%의 비용이 발생합니다. 요청당 최소 10초 분량의 오디오를 기준으로 청구됩니다. 자세한 가격 정보는 API 가격 페이지를 참조하세요.

전사문 편집을 사용하면 전사 요청에 자연어 지침을 첨부할 수 있습니다. 오디오가 전사되면 지침이 전사문에 적용되며, 편집된 텍스트가 원본과 함께 반환됩니다.

이를 통해 자체 파이프라인에서 별도의 후처리 단계를 대체할 수 있습니다. 일반적인 용도로는 날짜, 시간 또는 단위 표기 방식 표준화, 약어 확장, 필요 없는 콘텐츠 제거, 다른 스타일 또는 어조 적용, 전사문 재서식 등이 있습니다.

예를 들어, Write all dates in ISO 8601 format (YYYY-MM-DD) 지침과 함께 음성 메일을 전사하면 두 버전의 텍스트가 모두 반환됩니다.

{
"language_code": "eng",
"language_probability": 0.9912,
"text": "Hi, this is Jill. Your appointment is confirmed for the twelfth of July twenty twenty-six, and the follow-up is on the third of August.",
"words": [
{ "text": "Hi,", "start": 0.12, "end": 0.38, "type": "word", "logprob": 0.0 },
{ "text": " ", "start": 0.38, "end": 0.41, "type": "spacing", "logprob": 0.0 },
{ "text": "this", "start": 0.41, "end": 0.55, "type": "word", "logprob": 0.0 },
...
],
"transcription_id": "Y2ZX8AxHUzTPCIualYiE",
"edited_transcript": {
"kind": "transcript",
"text": "Hi, this is Jill. Your appointment is confirmed for 2026-07-12, and the follow-up is on 2026-08-03."
}
}

text 및 words 필드는 항상 원본 전사문을 나타냅니다. 편집된 버전은 edited_transcript에 별도로 반환됩니다.

전사문 편집 통합

전사문 편집은 convert 메서드에 transcript_edit 파라미터를 전달하여 음성 텍스트 변환 API에 통합됩니다. 지침은 최대 2000자까지 입력할 수 있습니다.

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
with open("voicemail.mp3", "rb") as audio_file:
transcription = elevenlabs.speech_to_text.convert(
file=audio_file,
model_id="scribe_v3",
# Natural-language instruction applied to the finished transcript.
transcript_edit="Write all dates in ISO 8601 format (YYYY-MM-DD)",
)
print("Original:", transcription.text)
print("Edited:", transcription.edited_transcript)

전사문 편집은 동기 요청과 웹훅 요청 모두에서 작동합니다. 웹훅 요청의 경우 edited_transcript는 웹훅 페이로드의 transcription 객체에 포함됩니다.

Scribe v3 Live 및 Scribe v2 Realtime은 커밋된 각 전사문에서 동일한 지침을 지원합니다. 실시간 전사문 편집 가이드를 참조하세요.

지침 작성

지침은 관련이 있는 경우 전체 전사문에 적용되며, 첫 번째 항목만이 아니라 일치하는 모든 항목이 편집됩니다. 지침으로 특정 단어나 구문을 변경하고 나머지는 그대로 둘 수도 있으며, 전체 텍스트를 다시 작성하거나 주석을 추가할 수도 있습니다. 하나의 지침에 여러 편집을 결합할 수 있습니다.

다음 예시는 지원되는 지침의 범위를 보여 줍니다.

지침효과
Write all dates in ISO 8601 format (YYYY-MM-DD)the twelfth of July twenty twenty-six이 2026-07-12로 변경됨
Write times in 24-hour formathalf past two in the afternoon이 14:30으로 변경됨
Expand abbreviations such as "ETA" and "ASAP" on first useETA가 estimated time of arrival (ETA)로 변경됨
Add the sentiment of every sentence in brackets at the end. Choose from [positive, negative, neutral]Thanks, that was really helpful.이 Thanks, that was really helpful. [positive]로 변경됨
Redact every curse word with its first letter followed by stars, e.g. s***That was a damn good call.이 That was a d*** good call.로 변경됨
Format the transcript as a bulleted list, one sentence per bullet전체 전사문을 다시 서식 지정

일부 조정에는 편집 지침보다 저렴하고 예측 가능한 전용 파라미터가 있습니다. 특정 이름과 용어의 인식 정확도를 높이려면 키텀 프롬프팅을, 군더더기 단어와 비유창성을 제거하려면 no_verbatim을, 숫자와 단어 중 하나를 선택하려면 numbers_format (Scribe v3)을 사용하세요. 이러한 옵션으로 처리할 수 없는 변경에만 전사문 편집을 사용하세요.

지침을 작성할 때 다음 사항을 유의하세요.

  • 원하는 출력을 명확하게 지정하세요. Write all dates in ISO 8601 format (YYYY-MM-DD)은 fix the dates보다 더 신뢰할 수 있습니다.
  • 지침은 어떤 언어로도 작성할 수 있지만, 영어로 작성한 지침이 가장 잘 작동합니다. 편집된 전사문은 원본 언어로 유지됩니다.
  • 지침만 실행됩니다. 오디오에서 말한 내용은 데이터로 취급되며 지침 적용 방식을 변경할 수 없습니다.
  • 전사문에서 지침의 영향을 받는 내용이 없으면 편집된 전사문은 원본과 동일합니다.

응답 형식

transcript_edit가 설정되면 응답에 edited_transcript 객체가 포함됩니다. kind 필드는 편집 성공 여부를 나타냅니다.

kind필드설명
transcripttext편집된 전사문입니다. 편집이 수행되지 않은 경우 원본 text와 동일합니다.
errorerror_type (edit_failed), message편집 결과를 생성할 수 없습니다. 전사 자체는 성공했으며 원본 text는 계속 반환됩니다.

transcript_edit를 요청하지 않은 경우 이 필드는 없습니다.

편집 실패
{
"text": "Hi, this is Jill. Your appointment is confirmed for ...",
"edited_transcript": {
"kind": "error",
"error_type": "edit_failed",
"message": "The transcript could not be edited. Please try again."
}
}

알아둘 동작은 다음과 같습니다.

  • 편집된 전사문은 일반 텍스트입니다. 단어 수준 타임스탬프, 화자 라벨 및 additional_formats는 계속해서 원본 전사문을 나타냅니다.
  • 편집은 전사가 완료된 후 실행되므로 전사문의 길이에 따라 지연 시간이 늘어납니다.
  • 추가 비용은 요청의 오디오 길이에 적용되며, 요청당 최소 10초가 청구됩니다.

전사문 편집은 entity_detection, entity_redaction 또는 use_multi_channel과 함께 사용할 수 없습니다. 이를 함께 사용하는 요청은 잘못된 파라미터 오류와 함께 거부됩니다.

다음 단계