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

# 语音转文本

> 将音频文件转录为文本。

将音频文件转录为文本。使用 multipart 表单上传（非 JSON）。最大文件大小：25 MB。

## 身份验证

需要 Bearer 令牌。参见[身份验证](/api-reference/authentication)。

## 请求体（multipart/form-data）

<ParamField body="file" type="Blob" required>
  待转录的音频文件。支持的格式：MP3、MP4、MPEG、MPGA、M4A、WAV、WEBM。
</ParamField>

<ParamField body="language" type="string">
  语言提示（ISO 639-1 代码，例如 `"en"`、`"es"`、`"fr"`）。如果省略，将自动检测语言。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/audio/stt \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -F "file=@recording.mp3" \
    -F "language=en"
  ```

  ```typescript SDK theme={null}
  const file = new Blob([audioBytes], { type: "audio/mp3" });
  const result = await theo.stt(file, "en");

  console.log(result.text);             // 转录文本
  console.log(result.language);         // 检测到的语言
  console.log(result.duration_seconds); // 音频时长
  ```
</CodeGroup>

## 响应

<ResponseField name="id" type="string">
  唯一的转录 ID（以 `stt_` 为前缀）。
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 时间戳。
</ResponseField>

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

<ResponseField name="language" type="string | null">
  检测到或指定的语言。
</ResponseField>

<ResponseField name="duration_seconds" type="number | null">
  音频文件的时长（秒）。
</ResponseField>

<ResponseField name="usage" type="object">
  <Expandable title="Usage object">
    <ResponseField name="cost_cents" type="number">费用（单位：分）。</ResponseField>
  </Expandable>
</ResponseField>

### 响应示例

```json theme={null}
{
  "id": "stt_abc123",
  "created": "2026-04-10T12:00:00Z",
  "text": "Welcome to Theo. How can I help you today?",
  "language": "en",
  "duration_seconds": 3.2,
  "usage": { "cost_cents": 0.01 }
}
```

## 错误

| 状态码 | 错误码 | 描述 |
| - | - | - |
| 400 | `missing_file` | 缺少 `file`（multipart 表单上传） |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 502 | `stt_provider_error` | Theo 转录引擎返回错误 — 请重试 |
| 503 | `stt_unavailable` | 当前实例未配置语音转文本功能 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.