텍스트 변환 결과 편집

개요

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

이 기능은 자체 파이프라인에서 별도의 후처리 단계를 대체합니다. 일반적인 용도는 날짜, 시간 또는 단위 표기 방식 정규화, 약어 확장, 필요 없는 콘텐츠 제거, 다른 스타일이나 어조 적용, 텍스트 변환 결과 재포맷입니다.

예를 들어, 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_v2",
        # 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 v2 Realtime은 커밋된 각 텍스트 변환 결과에서 동일한 지침을 지원합니다. 실시간 텍스트 변환 결과 편집 가이드를 참조하세요.

지침 작성

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

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

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

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

응답 형식

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

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초가 청구됩니다.

다음 단계