Dify Octri Demo
POST/text-to-audio

Convert Text to Audio

Available for: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.

Converts text to speech audio. Pass text to synthesize arbitrary text, or message_id to voice an existing message's answer.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields
message_idstringoptional
ID of the message whose answer to voice. Takes priority over `text` when both are provided. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).
streamingbooleanoptional
Accepted for backward compatibility but has no effect. Whether the audio is streamed is determined by the configured TTS provider's output, not by this field.
textstringoptional
Text to synthesize into speech.
userstringoptional
End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).
voicestringoptional
Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/en/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default.

3 status codes
200Returns the generated audio. The `Content-Type` header reflects the provider's audio container, verified from the response bytes when recognizable. The body can be AAC, FLAC, MP4, MP3, Ogg, WAV, or WebM. Output that cannot be recognized is labeled with the provider's declared type, or `audio/mpeg` when none is declared. Streamed provider output is delivered with chunked transfer encoding; the request `streaming` field does not control this.
400- `app_unavailable` : The app is unavailable or misconfigured. - `invalid_param` : Text-to-speech is not enabled, `text` is missing, or no voice is available. - `provider_not_initialize` : The workspace has no default text-to-speech model, or the default one has no credentials configured. - `provider_quota_exceeded` : The model provider quota is exhausted. - `model_currently_not_support` : The current model does not support this operation. - `completion_request_error` : The text-to-speech request failed.

6 documented failures

  • app_unavailable

    App unavailable, please check your app configurations.

    app_unavailable

  • completion_request_error

    Completion request failed.

    completion_request_error

  • invalid_param

    TTS is not enabled

    invalid_param

  • model_currently_not_support

    Dify Hosted OpenAI trial currently not support the GPT-4 model.

    model_currently_not_support

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • provider_quota_exceeded

    Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

    provider_quota_exceeded

500`internal_server_error` : Internal server error.

One documented failure

  • internal_server_error

    The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.

    internal_server_error

Error handling

A 400 is returned: - app_unavailable : The app is unavailable or misconfigured.

  • invalid_param : Text-to-speech is not enabled, text is missing, or no voice is available.
  • provider_not_initialize : The workspace has no default text-to-speech model, or the default one has no credentials configured.
  • provider_quota_exceeded : The model provider quota is exhausted.
  • model_currently_not_support : The current model does not support this operation.
  • completion_request_error : The text-to-speech request failed. A 500 is returned: internal_server_error : Internal server error.