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

> オーディオを生成せず、クレジットも消費せずに、指定したテキストから生成される音声の長さを推定します。

<Note>
  このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/api-reference/endpoints/predict-duration)もあわせてご確認ください。
</Note>

指定された入力から生成される音声の予想される長さ（秒）を返します。コスト見積もり、UI のヒント表示、バッチジョブの事前チェックなどに有用です。

<Note>
  このエンドポイントは **クレジットを消費しません**。300 文字の上限は適用され、自動チャンキングは行われません。
</Note>

## エンドポイント

```http theme={"dark"}
POST https://supertoneapi.com/v1/predict-duration/{voice_id}
```

## パスパラメータ

| Name       | Required | Description   |
| ---------- | :------: | ------------- |
| `voice_id` |     ✅    | 対象ボイスの ID です。 |

## リクエストボディ

[音声生成](/ja/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` を通じて長さに影響します。全項目は [音声生成](/ja/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 のヒント表示や予算の事前チェックに安全にご利用いただけます。

## 関連項目

<CardGroup cols={2}>
  <Card title="Docs: Cost and usage" icon="credit-card" href="/ja/docs/production/cost-and-usage#predict-duration">
    予測と予算管理に predict\_duration を活用する方法。
  </Card>

  <Card title="Create speech" icon="comment" href="/ja/api-reference/endpoints/text-to-speech">
    見積もりを確認したうえで、実際にオーディオを生成します。
  </Card>
</CardGroup>


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

````