트랜스크립트 편집

개요

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

이 기능은 자체 파이프라인에서 별도의 후처리 단계를 수행할 필요를 없애 줍니다. 일반적인 용도로는 날짜, 시간 또는 단위 표기 방식 정규화, 약어 확장, 불필요한 콘텐츠 제거, 다른 스타일이나 톤 적용, 트랜스크립트 재포맷 등이 있습니다.

예를 들어, 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 파라미터를 전달하여 Speech to Text 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)

트랜스크립트 편집은 동기 요청과 webhook 요청 모두에서 작동합니다. webhook 요청의 경우 edited_transcript는 webhook 페이로드의 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초가 청구됩니다.

다음 단계