> ## 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.