> ## 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.
# Predict duration
> 주어진 텍스트로 생성될 음성의 길이를 추정합니다 — 오디오를 생성하거나 크레딧을 소비하지 않습니다.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/api-reference/endpoints/predict-duration)을 함께 확인해 주세요.
주어진 입력으로 생성될 음성의 예상 길이(초)를 반환합니다. 비용 예측, UI 힌트 표시, 배치 작업 사전 점검에 유용합니다.
이 엔드포인트는 **크레딧을 소비하지 않습니다.** 동일한 300자 제한이 적용되며, 자동 청크 분할은 수행하지 않습니다.
## 엔드포인트
```http theme={"dark"}
POST https://supertoneapi.com/v1/predict-duration/{voice_id}
```
## 경로 파라미터
| Name | Required | Description |
| ---------- | :------: | -------------- |
| `voice_id` | ✅ | 대상 보이스의 ID입니다. |
## 요청 본문
[Create speech](/ko/api-reference/endpoints/text-to-speech)와 동일한 구조입니다 — `text`, `language`, `style`, `model`, `voice_settings` — 단, 길이에 영향을 주지 않는 `output_format`, `include_phonemes`, `normalized_text`는 제외됩니다.
| Name | Required | Description |
| ---------------- | :------: | ------------------------------------------------------------------------------------------------------------------ |
| `text` | ✅ | 분석할 텍스트입니다. **최대 300자.** |
| `language` | ✅ | 언어 코드입니다. 보이스와 모델이 모두 지원해야 합니다. |
| `style` | — | 감정 스타일입니다. 기본값은 보이스의 첫 번째 스타일입니다. |
| `model` | — | TTS 모델입니다. 기본값은 `sona_speech_1`. |
| `voice_settings` | — | `speed`와 `duration`을 통해 길이에 영향을 미칩니다. 전체 표는 [Create speech](/ko/api-reference/endpoints/text-to-speech)를 참고해 주십시오. |
## 요청 예시
```http theme={"dark"}
POST /v1/predict-duration/20160a4c5ba38967330c84
x-sup-api-key: $SUPERTONE_API_KEY
Content-Type: application/json
{
"text": "This is a long-form sentence for duration prediction.",
"language": "en",
"style": "neutral"
}
```
## 응답
```json theme={"dark"}
{
"duration": 3.57
}
```
길이는 초 단위 float 값으로 반환됩니다.
## 참고사항
* 예측 시점과 실제 `create_speech` 호출 시점에 **동일한 `model`과 `speed`를 사용해 주십시오** — 두 값 모두 결과에 영향을 미칩니다. 서로 다른 속도로 예측하고 생성하면 길이가 일치하지 않습니다.
* **크레딧은 차감되지 않습니다.** UI 힌트나 예산 사전 점검 용도로 안전하게 사용할 수 있습니다.
## 함께 보기
예측과 예산 책정에 predict\_duration을 활용하는 방법입니다.
추정치를 검증한 뒤 실제로 오디오를 생성합니다.
## OpenAPI
````yaml /openapi.json POST /v1/predict-duration/{voice_id}
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/predict-duration/{voice_id}:
post:
tags:
- text_to_speech
summary: Predict text-to-speech duration
description: >-
Predict the duration of text-to-speech conversion without generating
audio
operationId: predict_duration
parameters:
- name: voice_id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PredictTTSDurationRequest'
responses:
'200':
description: Returns predicted duration of the audio in seconds
content:
application/json:
schema:
type: object
properties:
duration:
type: number
'400':
description: >-
Bad Request: Invalid request data for duration prediction or invalid
request body/headers
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: 'Unauthorized: Invalid API key'
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
'402':
description: 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: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
'500':
description: 'Internal Server Error: Failed to convert text to speech'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- api-key: []
components:
schemas:
PredictTTSDurationRequest:
type: object
properties:
text:
type: string
description: The text to convert to speech. Max length is 300 characters.
maxLength: 300
language:
type: string
description: Language code of the voice
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'
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
````