# 번역

> 변환과 함께 또는 나중에 스크립트를 다른 언어로 번역하고, 이중 언어 또는 번역만 담긴 텍스트, SRT, VTT를 읽어요.

Canonical: https://transcript1.com/ko/docs/translation
Language: ko
Last updated: 2026-10-31

transcript1은 먼저 미디어를 텍스트로 변환한 다음, 스크립트 텍스트를 원하는 언어로 번역해요. 번역은 세그먼트 단위로 맞춰지고 원본 타임스탬프와 화자를 그대로 유지해요. 텍스트 번역만 제공하고, 더빙이나 번역된 오디오는 없어요.

번역은 무료예요. 0분을 쓰고 사용 내역에 무료 "Translation" 항목으로 표시돼요. 텍스트 변환 분은 평소처럼 적용되고, 번역이 실패해도 스크립트가 실패하거나 환불되지 않아요.

## 텍스트 변환과 함께 번역하기

스크립트를 만드는 요청에 `translate_to`를 추가하세요. `es`나 `en`처럼 소문자 두 글자의 ISO 639-1 코드예요. `POST /v1/transcriptions`의 JSON 본문에 있는 영상 링크, 청크 업로드 예약, 한 번에 끝나는 멀티파트 업로드에서 모두 쓸 수 있어요.

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "translate_to": "es"}'
```

파일을 업로드할 때는 `translate_to`를 폼 필드로 보내세요:

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a \
  -F translate_to=en
```

MCP의 `transcribe` 도구도 `translate_to`를 받아요. 요청 하나에 번역 언어는 하나예요.

## 이미 있는 스크립트 번역하기

완료된 변환 작업의 번역을 요청하세요:

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/translations" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "en"}'
```

API는 `202`를 돌려줘요:

```json
{
  "transcription_id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "language": "en",
  "status": "processing"
}
```

| 상태 | 의미 |
|---|---|
| `404` | 변환 작업을 찾을 수 없어요. |
| `409 transcript_not_ready` | 변환 작업이 아직 `completed`가 아니에요. |
| `422` | 언어가 올바른 두 글자 코드가 아니에요. |

이 호출은 멱등이에요. `processing`이나 `completed` 상태의 번역은 그대로 반환되고, `failed` 상태의 번역은 다시 시도돼요. MCP 도구 `translate_transcription`은 `id`와 `language`를 받아요.

## 번역 읽기

`GET /v1/transcriptions/:id`와 텍스트, SRT, VTT 다운로드는 `translation`을 받아요:

| `translation` | 결과 |
|---|---|
| `both` (기본값) | JSON 세그먼트에 `translation` 필드가 붙어요. 텍스트에서는 번역 줄이 원문 아래에 들어가요. SRT와 VTT 큐는 두 줄로, 원문 다음에 번역이 와요. |
| `only` | 번역문이 `text`를 대신해요. 타임스탬프와 화자는 그대로예요. |
| `none` | 원문 스크립트만. |

응답에는 `translation` 객체가 들어 있어요. 번역을 요청하지 않았다면 `null`이에요:

```json
{
  "translation": { "language": "es", "status": "completed" }
}
```

`status`는 `processing`, `completed`, `failed` 중 하나예요. 실패한 번역에는 `error` 메시지도 함께 들어가요. `wait`는 요청한 번역도 기다려요. 대기 시간이 지나면 상태는 `processing`이에요. MCP의 `get_transcription` 도구에도 같은 값을 받는 `translation` 매개변수가 있어요.

## 웹훅

바뀌지 않는 `transcription.completed`, `transcription.failed` 외에, 번역 결과를 알려 주는 이벤트가 두 개 있어요:

| `type` | 전송되는 때 |
|---|---|
| `transcription.translation.completed` | 요청한 번역이 `completed`가 되었을 때. |
| `transcription.translation.failed` | 요청한 번역이 `failed`가 되었을 때. |

`data`는 변환 작업 객체에 `translation: { language, status, error }`를 더한 거예요. 서명과 전송 규칙은 [Webhooks](https://transcript1.com/ko/docs/webhooks)에서 볼 수 있어요.