# 文字轉語音

**API:** Model API

**Endpoint:** `POST /api/v1/audio/speech`

**Tags:** Audio

Use model to select the speech generation model. Channel selection is unavailable for speech generation requests.

## Base URL

- `https://openapi.felo.ai` — 正式環境

## Authentication

- `FeloBearerAuth` (http bearer) — 以 `Authorization: Bearer <key>` 形式傳送的 Felo API 金鑰。
- `FeloApiKey` (apiKey in header `X-API-Key`) — 以 `X-API-Key: <key>` 形式傳送的 Felo API 金鑰。

## Request body

Required: **yes**

### application/json

Schema:

```json
{
  "type": "object",
  "required": [
    "model",
    "input"
  ],
  "additionalProperties": false,
  "properties": {
    "model": {
      "type": "string",
      "maxLength": 256
    },
    "input": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "voice": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Optional non-blank voice ID. The upstream model determines whether a voice is required and which IDs it accepts. Catalog voices are examples."
    },
    "response_format": {
      "type": "string",
      "enum": [
        "pcm",
        "mp3"
      ],
      "default": "pcm"
    },
    "speed": {
      "type": "number",
      "default": 1,
      "description": "Currently only 1 is supported."
    }
  }
}
```

## Responses

### 200 — 成功回傳音訊位元組：MP3 為 `audio/mpeg`，原始 PCM 為 `audio/pcm`，不是 WAV、JSON 或 SSE。播放前確認 HTTP 狀態與傳輸完整；`--fail` 避免把錯誤本文寫入音訊。中斷後丟棄不完整檔案。播放原始 PCM 需要通道的音訊參數，不可猜測。 依通道計費：STT 使用 `input_audio_second` 或 token；TTS 使用 `input_character`。`speech_billing_unit` 的 `utf16_code_unit` 和 `unicode_code_point` 對 emoji 計數不同。預占不是費用上限，結算可能非同步；缺少證據不代表免費。兩個介面都接受 `X-Felo-Channel`，只向選定通道派發一次。逾時或斷線後不要自動重試，也應停用 SDK 重試；保留 `X-Request-Id` 及可用的 `X-Generation-Id` 供核對。Console Playground 尚未支援語音呼叫。 `configured_rates` 依凍結費率及可信用量結算；`upstream_cost` 依可信上游成本與發布的加價、折扣結算。

**audio/mpeg**

Schema: string, (binary)

```json
{
  "type": "string",
  "format": "binary"
}
```

**audio/pcm**

Schema: string, (binary)

```json
{
  "type": "string",
  "format": "binary"
}
```
