> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 미디어 전사

> 오디오 또는 비디오 파일을 완전한 JSON, SRT 또는 VTT로 전사합니다

# 미디어 전사

오디오 또는 비디오 파일을 업로드하고 대본을 직접 받으세요. 이 독립형 엔드포인트는 더빙 프로젝트를 생성하지 않습니다.

이 엔드포인트는 최대 **200 MB** 및 **2시간** 길이의 파일을 허용합니다. 번역 API와 동일한 API 키 액세스 규칙을 사용합니다.
성공적인 요청은 HTTP `200`을 반환합니다.

## 요청

다음 필드와 함께 `multipart/form-data`을 전송하세요.

<ParamField header="x-api-key" type="string" required>
  귀하의 VoiceCheap API 키입니다.
</ParamField>

<ParamField body="file" type="file" required>
  전사할 오디오 또는 비디오 파일입니다. 지원되는 형식은 MP4, MOV, MKV, WebM, MPEG, MP3, WAV, M4A, FLAC, OGG 및 AAC입니다.
</ParamField>

<ParamField body="outputFormat" type="string" default="json">
  응답 형식: `json`, `srt` 또는 `vtt`.
</ParamField>

<ParamField body="originalLanguage" type="string" default="auto-detect">
  지원되는 원본 언어 ISO 코드입니다. 원본 언어를 모르는 경우 `auto-detect`으로 두세요. 지원되지 않는 명시적 언어는 처리 시작 전에 유효성 검사 오류를 반환합니다.
</ParamField>

<ParamField body="numberOfSpeakers" type="string" default="auto-detect">
  `auto-detect` 또는 `1`에서 `32` 사이의 정수입니다.
</ParamField>

<ParamField body="brandVocabulary" type="string">
  인식할 이름, 브랜드, 약어 또는 도메인 용어의 JSON 문자열 배열입니다. 요청된 용어는 저장된 계정 또는 팀 용어집과 병합됩니다.

  ```json theme={null}
  ["VoiceCheap", "SmartSync", "ITC Global"]
  ```
</ParamField>

<ParamField body="removeFillerWords" type="boolean" default="true">
  대본에서 일반적인 추임새 단어를 제거합니다.
</ParamField>

<ParamField body="includeSpeakerLabels" type="boolean" default="false">
  SRT 큐 앞에 `Speaker N:`을 접두사로 붙이거나 VTT 음성 태그를 추가합니다. JSON은 항상 모든 세그먼트와 단어에 숫자 화자를 포함합니다.
</ParamField>

## JSON 응답

JSON은 가장 완전한 출력 형식입니다. 여기에는 전체 텍스트, 언어 신뢰도, 미디어 길이, 화자, 타임스탬프가 포함된 세그먼트 및 타임스탬프가 포함된 단어가 포함됩니다.

```json theme={null}
{
  "source": "standalone",
  "language": "en",
  "languageConfidence": 0.99,
  "duration": 12.4,
  "text": "Welcome to VoiceCheap.",
  "speakers": [{ "id": 0, "label": "Speaker 1" }],
  "segments": [
    {
      "index": 0,
      "text": "Welcome to VoiceCheap.",
      "begin": 0.18,
      "end": 1.74,
      "duration": 1.56,
      "speaker": 0,
      "language": "en",
      "confidence": 0.94,
      "words": [
        {
          "index": 0,
          "text": "Welcome",
          "speaker": 0,
          "confidence": 0.96,
          "begin": 0.18,
          "end": 0.62,
          "duration": 0.44
        }
      ]
    }
  ],
  "words": [
    {
      "index": 0,
      "text": "Welcome",
      "speaker": 0,
      "confidence": 0.96,
      "begin": 0.18,
      "end": 0.62,
      "duration": 0.44
    }
  ]
}
```

## 예시

<CodeGroup>
  ```bash cURL — JSON theme={null}
  curl -X POST "https://api.voicecheap.ai/v1/transcribe" \
    -H "x-api-key: vc_your-api-key" \
    -F "file=@interview.mp4" \
    -F "outputFormat=json" \
    -F "numberOfSpeakers=2" \
    -F 'brandVocabulary=["VoiceCheap","SmartSync"]'
  ```

  ```bash cURL — SRT theme={null}
  curl -X POST "https://api.voicecheap.ai/v1/transcribe" \
    -H "x-api-key: vc_your-api-key" \
    -F "file=@interview.mp4" \
    -F "outputFormat=srt" \
    -F "includeSpeakerLabels=true" \
    --output interview.srt
  ```

  ```bash cURL — VTT theme={null}
  curl -X POST "https://api.voicecheap.ai/v1/transcribe" \
    -H "x-api-key: vc_your-api-key" \
    -F "file=@interview.mp4" \
    -F "outputFormat=vtt" \
    --output interview.vtt
  ```
</CodeGroup>

## 오류

| 상태  | 코드                          | 설명                                  |
| --- | --------------------------- | ----------------------------------- |
| 400 | `FILE_REQUIRED`             | 업로드된 파일이 없습니다                       |
| 400 | `INVALID_FILE_TYPE`         | 지원되지 않는 파일 형식입니다                    |
| 400 | `INVALID_MEDIA_STREAM`      | 파일에 오디오 스트림이 없습니다                   |
| 400 | `DURATION_DETECTION_FAILED` | 미디어 길이를 읽을 수 없습니다                   |
| 400 | `DURATION_TOO_LONG`         | 미디어가 2시간보다 깁니다                      |
| 400 | `INVALID_BRAND_VOCABULARY`  | 하나 이상의 용어집 항목이 유효하지 않습니다            |
| 400 | `INVALID_BOOLEAN_VALUE`     | 멀티파트 불리언 값이 `true` 또는 `false`이 아닙니다 |
| 400 | `INVALID_JSON_FORMAT`       | JSON으로 인코딩된 멀티파트 필드가 잘못되었습니다        |
| 400 | `INVALID_MULTIPART_REQUEST` | 멀티파트 폼 데이터가 잘못되었거나 너무 큽니다           |
| 413 | `FILE_TOO_LARGE`            | 파일이 200 MB를 초과합니다                   |
| 502 | `TRANSCRIPTION_EMPTY`       | 전사 결과 사용 가능한 음성이 없습니다               |
| 502 | `TRANSCRIPTION_FAILED`      | 전사 엔진이 완료되지 못했습니다                   |