> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 트랜스크립트 편집

> **Note**
>
> **사용 방법 가이드** · [Speech to Text 빠른 시작](/docs/ko/eleven-api/guides/cookbooks/speech-to-text)을 완료했다고 가정합니다.

## 개요

> **Warning**
>
> 트랜스크립트 편집은 실험적 기능이며, 기본 트랜스크립션 비용에 추가로 30%가 부과됩니다. 요청당 최소 10초의 오디오가 청구됩니다. 자세한 가격 정보는 [API 가격 페이지](https://elevenlabs.io/pricing/api?price.section=speech_to_text\&price.sections=speech_to_text,speech_to_text#pricing-table)를
> 참조하세요.

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

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

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

```json maxLines=0
{
  "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자까지 입력할 수 있습니다.

```python maxLines=0
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)
```

```typescript maxLines=0
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import { readFile } from "node:fs/promises";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

const audioBlob = new Blob([await readFile("voicemail.mp3")], { type: "audio/mp3" });

const transcription = await elevenlabs.speechToText.convert({
  file: audioBlob,
  modelId: "scribe_v2",
  // Natural-language instruction applied to the finished transcript.
  transcriptEdit: "Write all dates in ISO 8601 format (YYYY-MM-DD)",
});

console.log("Original:", transcription.text);
console.log("Edited:", transcription.editedTranscript);
```

트랜스크립트 편집은 동기 요청과 [webhook](/docs/ko/eleven-api/guides/how-to/speech-to-text/batch/webhooks) 요청 모두에서 작동합니다. webhook 요청의 경우 `edited_transcript`는 webhook 페이로드의 `transcription` 객체에 포함됩니다.

Scribe v2 Realtime은 커밋된 각 트랜스크립트에서 동일한 지침을 지원합니다. [실시간 트랜스크립트 편집 가이드](/docs/ko/eleven-api/guides/how-to/speech-to-text/realtime/transcript-editing)를 참조하세요.

## 지침 작성

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

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

| 지침                                                                                                      | 효과                                                                                        |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `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 format`                                                                         | `half past two in the afternoon`이 `14:30`으로 변경됩니다.                                        |
| `Expand abbreviations such as "ETA" and "ASAP" on first use`                                            | `ETA`가 `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`                                     | 전체 트랜스크립트의 형식을 변경합니다.                                                                     |

> **Note**
>
> 일부 조정에는 편집 지침보다 비용이 낮고 결과를 더 예측하기 쉬운 전용 파라미터가 있습니다. 특정 이름과 용어의 인식을 유도하려면 [keyterm prompting](/docs/ko/eleven-api/guides/how-to/speech-to-text/batch/keyterm-prompting)을 사용하고, 추임새와
> 비유창성을 제거하려면 `no_verbatim`을 사용하며, 숫자와 단어 중 표기 방식을 선택하려면(지원되는 경우) `numbers_format`을 사용하세요.
> 이러한 옵션으로 처리할 수 없는 변경에만 트랜스크립트 편집을 사용하세요.

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

* 원하는 출력을 구체적으로 명시하세요. `Write all dates in ISO 8601 format (YYYY-MM-DD)`는 `fix the dates`보다 더 신뢰할 수 있습니다.
* 지침은 어떤 언어로든 작성할 수 있지만, 영어로 작성한 지침이 가장 잘 작동합니다. 편집된 트랜스크립트는 원본 언어로 유지됩니다.
* 지침만 수행됩니다. 오디오에서 말한 콘텐츠는 데이터로 처리되며 지침 적용 방식을 변경할 수 없습니다.
* 트랜스크립트에서 지침의 영향을 받는 내용이 없으면 편집된 트랜스크립트는 원본과 동일합니다.

## 응답 형식

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

| `kind`       | 필드                                      | 설명                                                       |
| ------------ | --------------------------------------- | -------------------------------------------------------- |
| `transcript` | `text`                                  | 편집된 트랜스크립트입니다. 편집이 이루어지지 않은 경우 원본 `text`와 동일합니다.         |
| `error`      | `error_type` (`edit_failed`), `message` | 편집 결과를 생성할 수 없습니다. 트랜스크립션 자체는 성공했으며 원본 `text`는 계속 반환됩니다. |

`transcript_edit`가 요청되지 않은 경우 이 필드는 없습니다.

**`편집 실패`**

```json title="편집 실패"
{
  "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초가 청구됩니다.

> **Warning**
>
> 트랜스크립트 편집은 `entity_detection`, `entity_redaction` 또는
> `use_multi_channel`과 함께 사용할 수 없습니다. 함께 사용하는 요청은 잘못된 파라미터 오류와 함께 거부됩니다.

## 다음 단계

#### [API 레퍼런스](/docs/ko/api-reference/speech-to-text)

전체 Speech to Text API 레퍼런스 및 파라미터.

#### [Webhook](/docs/ko/eleven-api/guides/how-to/speech-to-text/batch/webhooks)

편집된 트랜스크립트를 포함한 트랜스크립트를 webhook을 통해 비동기적으로 수신하세요.