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

# Text-to-Speech

> Convert text into natural, fluent speech

Synchronous endpoint — returns the audio stream directly when the request completes.

<RequestExample>
  ```bash cURL theme={"system"}
  curl https://www.qingbo.dev/v1/audio/speech \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "tts-1",
      "voice": "nova",
      "input": "欢迎使用 清波 API 文字转语音服务。"
    }' \
    --output output.mp3
  ```

  ```python Python theme={"system"}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://www.qingbo.dev/v1",
      api_key="YOUR_API_KEY"
  )

  response = client.audio.speech.create(
      model="tts-1",
      voice="nova",
      input="欢迎使用 清波 API 文字转语音服务。"
  )

  response.stream_to_file("output.mp3")
  ```

  ```javascript JavaScript theme={"system"}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    baseURL: 'https://www.qingbo.dev/v1',
    apiKey: 'YOUR_API_KEY'
  });

  const response = await client.audio.speech.create({
    model: 'tts-1',
    voice: 'nova',
    input: '欢迎使用 清波 API 文字转语音服务。'
  });

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync('output.mp3', buffer);
  ```

  ```go Go theme={"system"}
  package main

  import (
      "bytes"
      "encoding/json"
      "io"
      "net/http"
      "os"
  )

  func main() {
      payload := map[string]string{
          "model": "tts-1",
          "voice": "nova",
          "input": "欢迎使用 清波 API 文字转语音服务。",
      }

      body, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", "https://www.qingbo.dev/v1/audio/speech", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")

      resp, _ := http.DefaultClient.Do(req)
      defer resp.Body.Close()

      out, _ := os.Create("output.mp3")
      defer out.Close()
      io.Copy(out, resp.Body)
  }
  ```

  ```java Java theme={"system"}
  import java.net.http.*;
  import java.net.URI;
  import java.nio.file.*;

  public class Main {
      public static void main(String[] args) throws Exception {
          String payload = """
          {
            "model": "tts-1",
            "voice": "nova",
            "input": "欢迎使用 清波 API 文字转语音服务。"
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://www.qingbo.dev/v1/audio/speech"))
              .header("Authorization", "Bearer YOUR_API_KEY")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<byte[]> response = client.send(request,
              HttpResponse.BodyHandlers.ofByteArray());
          Files.write(Path.of("output.mp3"), response.body());
      }
  }
  ```
</RequestExample>

## Available Models

| Model ID   | Description                   |
| ---------- | ----------------------------- |
| `tts-1`    | Standard quality, low latency |
| `tts-1-hd` | High-definition quality       |

## Request Parameters

<ParamField body="model" type="string" required>
  Model ID: `tts-1`, `tts-1-hd`
</ParamField>

<ParamField body="input" type="string" required>
  The text to convert.
</ParamField>

<ParamField body="voice" type="string" default="alloy">
  Voice: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`
</ParamField>

## Response

Returns an audio file stream (MP3 format) — save it directly to a file.