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

# 创建音频转录

> 使用兼容 OpenAI 的 Yelu Audio Transcriptions API 将音频转换为文本。

转录上传的音频文件。本端点使用 `multipart/form-data`，而不是 JSON。

## 端点

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/audio/transcriptions
```

## 请求头

<ParamField header="Authorization" type="string" required>格式为 `Bearer $YELU_API_KEY`。</ParamField>
<ParamField header="Content-Type" type="string" required>带自动生成 boundary 的 `multipart/form-data`。请让客户端库自动设置。</ParamField>

## 请求体

<ParamField body="file" type="file" required>要转录的音频。格式与大小限制取决于模型和部署配置。</ParamField>
<ParamField body="model" type="string" required>账号可用的转录模型 ID，例如已开启时使用 `whisper-1`。</ParamField>
<ParamField body="language" type="string">ISO 639-1 语言代码，例如 `zh`。</ParamField>
<ParamField body="prompt" type="string">辅助专有名词拼写或上下文延续的提示。</ParamField>
<ParamField body="response_format" type="string" default="json">`json`、`text`、`srt`、`verbose_json` 或 `vtt`，取决于模型。</ParamField>
<ParamField body="temperature" type="number" default="0">转录模型支持的采样温度。</ParamField>
<ParamField body="timestamp_granularities[]" type="string[]">兼容模型可返回 `word` 或 `segment` 时间戳。</ParamField>

## 响应

当 `response_format=json` 时：

<ResponseField name="text" type="string" required>转录文本。</ResponseField>

Verbose 格式还可能包含语言、时长、Word 和 Segment。Text、SRT 与 VTT 返回非 JSON Body。

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/audio/transcriptions \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -F "file=@meeting.m4a" \
    -F "model=whisper-1" \
    -F "language=zh" \
    -F "response_format=json"
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { openAsBlob } from 'node:fs';

  const form = new FormData();
  form.append('file', await openAsBlob('meeting.m4a'), 'meeting.m4a');
  form.append('model', 'whisper-1');
  form.append('language', 'zh');
  form.append('response_format', 'json');
  const response = await fetch('https://api.yelu.ai/v1/audio/transcriptions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}` },
    body: form,
  });
  if (!response.ok) throw new Error(await response.text());
  console.log((await response.json()).text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  with open("meeting.m4a", "rb") as audio:
      response = requests.post(
          "https://api.yelu.ai/v1/audio/transcriptions",
          headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
          files={"file": ("meeting.m4a", audio, "audio/mp4")},
          data={"model": "whisper-1", "language": "zh", "response_format": "json"},
          timeout=300,
      )
  response.raise_for_status()
  print(response.json()["text"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {"text":"今天我们评审了网关迁移计划，并决定在上线前测试流式响应。"}
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {"error":{"message":"An audio file is required.","type":"invalid_request_error","param":"file","code":"missing_required_parameter"}}
  ```
</ResponseExample>

## 错误码

| 状态码         | 含义                    |
| ----------- | --------------------- |
| `400`       | 文件/模型缺失，或格式、选项无效      |
| `401`       | Key 缺失或无效             |
| `403`       | 转录能力或模型未开启            |
| `404`       | 模型不可用                 |
| `413`       | 音频过大                  |
| `415`       | 媒体类型或 multipart 编码不支持 |
| `429`       | 达到请求限制                |
| `500`–`504` | 网关或上游转录失败             |

<Tip>Node.js 20 及以上版本支持 `openAsBlob`。不要手动设置 multipart 的 `Content-Type`，Fetch 会添加正确的 boundary。</Tip>