> ## 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`         | 媒体时长超过两小时                 |
| 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`      | 转录引擎无法完成                  |