> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 음성-텍스트 변환

> OpenAI 호환 /audio/transcriptions 엔드포인트로 Venice 음성-텍스트 모델을 사용해 오디오를 전사하세요.

음성-텍스트 변환은 음성 오디오를 문자로 전사합니다. 오디오 파일을 `/audio/transcriptions`로 전송하고 전사 모델을 선택한 뒤 원하는 응답 형식을 지정하세요.

대화 녹음을 다루고 계신가요? [음성-텍스트 변환으로 회의록 만들기](/guides/media/meeting-notes)는 오디오 파일에서 시작해 합의된 시점(초 단위)을 인용하는 결정 사항과 실행 항목까지 다루며, 어떤 모델이 세그먼트 타이밍을 반환하는지, 화자가 누구인지 전혀 밝히지 않는 전사를 어떻게 처리하는지도 설명합니다.

## 기본 사용법

<CodeGroup>
  ```python Python theme={null}
  import os

  import requests

  with open("meeting.mp3", "rb") as audio:
      response = requests.post(
          "https://api.venice.ai/api/v1/audio/transcriptions",
          headers={"Authorization": f"Bearer {os.environ['VENICE_API_KEY']}"},
          files={"file": audio},
          data={
              "model": "nvidia/parakeet-tdt-0.6b-v3",
              "response_format": "json",
          },
      )

  response.raise_for_status()
  print(response.json()["text"])
  ```

  ```javascript Node.js theme={null}
  import { createReadStream } from "node:fs";
  import FormData from "form-data";

  const form = new FormData();
  form.append("file", createReadStream("meeting.mp3"));
  form.append("model", "nvidia/parakeet-tdt-0.6b-v3");
  form.append("response_format", "json");

  const response = await fetch("https://api.venice.ai/api/v1/audio/transcriptions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      ...form.getHeaders(),
    },
    body: form,
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  const transcript = await response.json();
  console.log(transcript.text);
  ```

  ```bash cURL theme={null}
  curl https://api.venice.ai/api/v1/audio/transcriptions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    --form file=@meeting.mp3 \
    --form model=nvidia/parakeet-tdt-0.6b-v3 \
    --form response_format=json
  ```
</CodeGroup>

## 지원 입력

지원되는 오디오 형식은 `wav`, `wave`, `flac`, `m4a`, `aac`, `mp4`, `mp3`, `ogg`, `oga`, `webm`입니다. 파일의 MIME 유형 또는 확장자 중 하나가 이 목록에 있으면 허용되며, 업로드된 바이트도 매직 바이트 검사를 통과해야 합니다 — 파일 이름을 지원되는 확장자로 바꾸는 것만으로는 통과할 수 없습니다. 현재 모델 지원과 가격 정보는 [음성-텍스트 모델](/models/speech-to-text) 페이지를 참조하세요.

## 응답 형식

| 형식     | 사용 시점                                                           |
| ------ | --------------------------------------------------------------- |
| `json` | 구조화된 응답을 원할 때: `text`와 함께, 가능한 경우 `duration` 및 `timestamps` 포함. |
| `text` | JSON 파싱 없이 순수 텍스트를 원할 때.                                        |

<Note>
  `response_format`이 허용하는 값은 이 두 가지뿐입니다. `srt`, `vtt`, `verbose_json` 옵션은 없으며 — 요청하면 `400`이 반환됩니다. 자막을 만들려면 `timestamps: true`를 `response_format: json`과 함께 사용하고 타이밍 데이터를 직접 렌더링하세요.
</Note>

## 타임스탬프

`timestamps=true`를 전달하면 전사 결과와 함께 타이밍 데이터를 받을 수 있습니다. 지원 여부는 모델별로 다르며, 세분성도 다릅니다:

| 모델                            | 세분성       |
| ----------------------------- | --------- |
| `elevenlabs/scribe-v2`        | `word`    |
| `stt-xai-v1`                  | `word`    |
| `openai/whisper-large-v3`     | `segment` |
| `fal-ai/wizper`               | `segment` |
| `nvidia/parakeet-tdt-0.6b-v3` | 없음        |

<Warning>
  기본 모델인 `nvidia/parakeet-tdt-0.6b-v3`은 `timestamps=true`를 받아들이고는 무시합니다 — 오류도 경고도 없이 `text`만 포함된 응답을 받게 됩니다. 타이밍이 필요하면 위 표에서 모델을 선택하고, 읽기 전에 `timestamps` 키가 존재하는지 확인하세요.
</Warning>

```bash theme={null}
curl https://api.venice.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  --form file=@meeting.mp3 \
  --form model=elevenlabs/scribe-v2 \
  --form timestamps=true \
  --form response_format=json
```

```json theme={null}
{
  "text": "The quick brown fox jumps over the lazy dog.",
  "duration": 4.099,
  "timestamps": {
    "word": [
      { "word": "The", "start": 0.0, "end": 0.14 },
      { "word": "quick", "start": 0.14, "end": 0.42 }
    ]
  }
}
```

세그먼트 수준 모델은 대신 `segment` 배열을 반환하며, 각 항목은 `{ "text": "...", "start": 0.0, "end": 3.2 }` 형태입니다. 모든 시간은 초 단위입니다.

<Note>
  어떤 Venice 전사 모델도 화자 분리(speaker diarization)를 수행하지 않으므로, 어떤 응답에도 `speaker` 필드가 없습니다. 전사 결과는 단일 텍스트 스트림입니다 — 화자는 이름이 소리 내어 언급될 때만 식별할 수 있습니다.
</Note>

## 프로덕션 팁

* 가능하면 오디오를 선명하게 유지하고 화자가 겹치지 않도록 하세요.
* 워크플로에 낮은 지연 시간이나 손쉬운 재시도가 필요하다면 매우 긴 녹음을 더 작은 청크로 분할하세요.
* 감사 추적을 위해 각 전사 결과와 함께 원본 오디오 경로, 모델 ID, 응답 형식을 저장하세요.

## 관련 리소스

* [오디오 전사 API](/api-reference/endpoint/audio/transcriptions)
* [음성-텍스트 모델](/models/speech-to-text)
* [텍스트-음성 변환 가이드](/guides/media/text-to-speech)