> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stream speech
> 텍스트를 음성으로 변환하여 청크 단위 오디오 스트림으로 반환합니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/stream-text-to-speech)을 함께 확인해 주세요.
생성된 음성을 청크 단위로 스트리밍 반환하여 전체 클립이 준비되기 전부터 재생을 시작할 수 있습니다. 스트리밍과 빠른 비스트리밍 모델 중 어느 것을 선택할지에 대해서는 [Docs: Stream speech](/ko/docs/text-to-speech/stream-speech)와 [지연시간 최적화](/ko/docs/production/latency-optimization)를 참고해 주십시오.
스트리밍은 현재 \*\*`sona_speech_1`\*\*에서만 지원됩니다.
## 엔드포인트
```http theme={"dark"}
POST https://supertoneapi.com/v1/text-to-speech/{voice_id}/stream
```
## 경로 파라미터
| Name | Required | Description |
| ---------- | :------: | -------------- |
| `voice_id` | ✅ | 대상 보이스의 ID입니다. |
## 요청 본문
`Content-Type: application/json`
| Name | Required | Description |
| ------------------ | :------: | -------------------------------------------------------------------------------------------- |
| `text` | ✅ | 변환할 텍스트입니다. **최대 300자.** |
| `language` | ✅ | 언어 코드입니다. 지원: `en`, `ko`, `ja`. |
| `style` | — | 감정 스타일입니다(예: `neutral`, `happy`). 생략하면 보이스의 기본 스타일이 적용됩니다. |
| `model` | — | 반드시 `sona_speech_1`이어야 합니다(스트리밍을 지원하는 유일한 모델입니다). |
| `output_format` | — | `wav`(기본값) 또는 `mp3`. |
| `voice_settings` | — | 고급 보이스 파라미터입니다 — 필드와 범위는 [Create speech](/ko/api-reference/endpoints/text-to-speech)와 동일합니다. |
| `include_phonemes` | — | `true`이면 청크별 음소 데이터를 포함한 NDJSON으로 응답됩니다. 기본값은 `false`. |
## 응답
**기본값 (`include_phonemes=false`):** 바이너리 오디오 스트림입니다.
* `Content-Type: audio/wav` 또는 `audio/mpeg`(`output_format`에 따름).
* 첫 번째 청크에는 오디오 파일 헤더가 포함되며, 이후 청크는 원시 오디오 데이터입니다.
**`include_phonemes=true`일 때:** 줄바꿈으로 구분된 JSON(NDJSON), 청크당 하나의 객체:
```jsonl theme={"dark"}
{"audio_base64":"...","phonemes":{"symbols":["","h"],"start_times_seconds":[0,0.05],"durations_seconds":[0.05,0.08]}}
{"audio_base64":"...","phonemes":{"symbols":["ɐ","ɡ"],"start_times_seconds":[0.13,0.19],"durations_seconds":[0.06,0.04]}}
```
## 참고사항
* Stream speech는 현재 **베타**이며 `sona_speech_1`만 지원합니다.
* `text`가 300자를 초과하면 `400`을 반환합니다. SDK는 더 긴 입력을 자동으로 청크 분할하여 이터레이터로 전달합니다.
* `speed`는 `duration` 이후에 적용됩니다(예: `duration=5` + `speed=2` ≈ 10초).
* `style`을 생략하면 보이스의 기본 스타일이 사용됩니다. 기본값은 [Get voice](/ko/api-reference/endpoints/get-voice)로 확인해 주십시오.
## 함께 보기
스트리밍을 사용할 시점과 SDK별 청크 소비 방법입니다.
OpenAI 및 Anthropic과의 엔드 투 엔드 레시피입니다.
## OpenAPI
````yaml openapi.json POST /v1/text-to-speech/{voice_id}/stream
openapi: 3.0.0
info:
title: Supertone Public API
description: >-
Supertone API is a RESTful API for using our state-of-the-art AI voice
models.
version: 0.9.6
contact: {}
servers:
- url: https://supertoneapi.com
description: Production
security: []
tags:
- name: voices
description: Voice Library API endpoints
- name: custom_voices
description: Custom Voice Management API endpoints
- name: text_to_speech
description: Text-to-Speech API endpoints
- name: usage
description: Usage Analytics API endpoints
paths:
/v1/text-to-speech/{voice_id}/stream:
post:
tags:
- text_to_speech
summary: Convert text to speech with streaming response
description: >-
Convert text to speech using the specified voice with streaming
response. Returns binary audio stream.
operationId: stream_speech
parameters:
- name: voice_id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/APIConvertTextToSpeechUsingCharacterRequest'
responses:
'200':
description: >-
Streaming audio data in binary format or NDJSON format with phoneme
data based on includePhonemes parameter
content:
audio/wav:
schema:
type: string
format: binary
description: Binary audio stream (when includePhonemes=false or omitted)
audio/mpeg:
schema:
type: string
format: binary
description: Binary audio stream (when includePhonemes=false or omitted)
application/x-ndjson:
schema:
type: string
description: >-
NDJSON stream with consistent format - each chunk contains
audio_base64 and phonemes fields (one null, one populated)
example: >
{"audio_base64":"UklGRnoGAABXQVZF...","phonemes":null}
{"audio_base64":null,"phonemes":{"symbols":["","h","ɐ","l","oʊ"],"start_times_seconds":[0,0.1,0.2,0.3,0.4],"durations_seconds":[0.1,0.1,0.1,0.1,0.2]}}
{"audio_base64":"E4ATABFAD4AMQAp...","phonemes":null}
{"audio_base64":null,"phonemes":{"symbols":["w","ɝ","l","d"],"start_times_seconds":[0.5,0.6,0.7,0.8],"durations_seconds":[0.1,0.1,0.1,0.1]}}
headers:
Content-Type:
description: >-
Content type: audio/* for binary stream, application/x-ndjson
for phoneme data
schema:
type: string
enum:
- audio/wav
- audio/mpeg
- application/x-ndjson
example: audio/mpeg
Transfer-Encoding:
description: Chunked transfer encoding
schema:
type: string
example: chunked
Cache-Control:
description: No cache headers
schema:
type: string
example: no-cache
X-Content-Type-Options:
description: Security header to prevent MIME sniffing
schema:
type: string
example: nosniff
Trailer:
description: Announces that X-Audio-Length will be sent as a trailer header
schema:
type: string
example: X-Audio-Length
X-Audio-Length:
description: >-
Total duration of the audio in seconds (sent as trailer header
after streaming completes)
schema:
type: number
'400':
description: 'Bad Request: Invalid request data or parameters'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: 'Unauthorized: Invalid API key'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
'402':
description: 'Payment Required: Not enough credits'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequiredErrorResponse'
'403':
description: 'Forbidden: Permission denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
'404':
description: 'Not Found: Voice not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/RequestTimeoutErrorResponse'
'429':
description: 'Too Many Requests: Rate limit exceeded'
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
'500':
description: 'Internal Server Error: Failed to process streaming TTS'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- api-key: []
components:
schemas:
APIConvertTextToSpeechUsingCharacterRequest:
type: object
properties:
text:
type: string
description: The text to convert to speech
maxLength: 300
language:
type: string
description: The language code of the text
enum:
- en
- ko
- ja
- bg
- cs
- da
- el
- es
- et
- fi
- hu
- it
- nl
- pl
- pt
- ro
- ar
- de
- fr
- hi
- id
- ru
- vi
- hr
- lt
- lv
- sk
- sl
- sv
- tr
- uk
style:
type: string
description: The style of character to use for the text-to-speech conversion
model:
type: string
description: The model type to use for the text-to-speech conversion
enum:
- sona_speech_1
- sona_speech_2
- sona_speech_2_flash
- supertonic_api_1
- supertonic_api_3
default: sona_speech_1
output_format:
type: string
description: >-
The desired output format of the audio file (wav, mp3). Default is
wav.
enum:
- wav
- mp3
default: wav
voice_settings:
$ref: '#/components/schemas/ConvertTextToSpeechParameters'
include_phonemes:
type: boolean
description: Return phoneme timing data with the audio
default: false
normalized_text:
type: string
description: >-
Pre-normalized text for TTS. Only used with sona_speech_2 and
sona_speech_2_flash models.
required:
- text
- language
BadRequestErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
type: string
description: Bad request error message
example: Invalid request data
required:
- status
- message
UnauthorizedErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Unauthorized error details
example:
message: Invalid API Key
error: Unauthorized
statusCode: 401
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
PaymentRequiredErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Payment required error details
example:
message: Not enough credits
error: Payment Required
statusCode: 402
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
ForbiddenErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Forbidden error details
example:
message: Permission denied
error: Forbidden
statusCode: 403
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
NotFoundErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Not found error details
example:
message: Voice not found
error: Not Found
statusCode: 404
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
RequestTimeoutErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Request timeout error details
example:
message: Request timed out
error: Request Timeout
statusCode: 408
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
TooManyRequestsErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Too many requests error details
example:
message: rate limit exceeded
error: Too Many Requests
statusCode: 429
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
InternalServerErrorResponse:
type: object
properties:
status:
type: string
description: Response status
example: error
message:
description: Internal server error details
example:
message: Failed to convert text to speech
error: Internal Server Error
statusCode: 500
allOf:
- $ref: '#/components/schemas/ErrorMessageData'
required:
- status
- message
ConvertTextToSpeechParameters:
type: object
properties:
pitch_shift:
type: number
default: 0
minimum: -24
maximum: 24
pitch_variance:
type: number
default: 1
minimum: 0
maximum: 2
speed:
type: number
default: 1
minimum: 0.5
maximum: 2
duration:
type: number
description: Duration parameter for TTS generation
default: 0
minimum: 0
maximum: 60
similarity:
type: number
description: Similarity parameter for voice matching
default: 3
minimum: 1
maximum: 5
text_guidance:
type: number
description: Text guidance parameter for generation control
default: 1
minimum: 0
maximum: 4
subharmonic_amplitude_control:
type: number
description: Subharmonic amplitude control parameter
default: 1
minimum: 0
maximum: 2
ErrorMessageData:
type: object
properties:
message:
type: string
description: Error message
example: Invalid API Key
error:
type: string
description: Error type
example: Unauthorized
status_code:
type: number
description: HTTP status code
example: 401
required:
- message
- error
- status_code
securitySchemes:
api-key:
type: apiKey
in: header
name: x-sup-api-key
````