> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# xAI TTS 1
> Convert text into speech with xAI TTS, choosing from five voices and multiple languages for narration, dialogue, and spoken content.
1. Submit the request with `VIDGO_API_KEY`. A `task_id` is returned immediately. Keep it until the task reaches `finished` or `failed`.
2. Use [Query Task Status](/api-manual/task-management/status) to retrieve the result. If you provide a `callback_url`, Vidgo sends the result to your [webhook](/api-manual/task-management/webhooks) when the task finishes or fails.
# xAI TTS 1
Convert text into speech with xAI TTS, choosing from five voices and multiple languages for narration, dialogue, and spoken content.
## Available Models
* **xai/tts/v1** - Convert text into speech.
## Output Options
### Output Format
* `output_format`: Optional. Supply an object with the fields below.
* `output_format.codec`: Optional. Accepted values: `mp3`, `wav`, `pcm`, `mulaw`, `alaw`. Default: `mp3`.
* `output_format.sample_rate`: Optional. Sample rate in Hz. Accepted values: `8000`, `16000`, `22050`, `24000`, `44100`, `48000`. Default: `24000`.
* `output_format.bit_rate`: Optional. MP3 bitrate in bits per second. Accepted values: `32000`, `64000`, `96000`, `128000`, `192000`, `null`. MP3 default: `128000`.
* For `mp3`, use `output_format.bit_rate` to select the bitrate. For `wav`, `pcm`, `mulaw`, and `alaw`, omit `bit_rate` or set it to `null`.
## Key Features
* Convert text into speech.
* Select a voice with `voice` and specify the spoken language with `language_code`.
* Direct pauses, laughter, sighs, whispers, and slower phrases through tags in `text`.
## Advanced Parameters
Set `model` and optional `callback_url` at the request root. Place all workflow parameters, including output options, inside `input`.
### Text
* `text`: Required. Supply the text to speak. Length: **1-15,000 characters**.
* Enter spoken text after trimming leading and trailing whitespace. Tags, punctuation, and spaces within the text count toward the length.
* Add `[laugh]`, `[pause]`, or `[sigh]` where the sound belongs. Use `text` for whispered passages and `text` for slower delivery.
### Voice
* `voice`: Optional. Select the voice. Accepted values: `eve`, `ara`, `rex`, `sal`, `leo`. Default: `eve`.
### Language Code
* `language_code`: Optional. String. Default: `auto`.
- `auto`
- `en`
- `ar-EG`
- `ar-SA`
- `ar-AE`
- `bn`
- `zh`
- `fr`
- `de`
- `hi`
- `id`
- `it`
- `ja`
- `ko`
- `pt-BR`
- `pt-PT`
- `ru`
- `es-MX`
- `es-ES`
- `tr`
- `vi`
## Output Files
* Read every item in the returned `files` array.
* Generated audio uses `file_type: "audio"`.
* Use `file_url` to download the generated speech.
## Request Example
```json theme={null}
{
"model": "xai/tts/v1",
"input": {
"text": "Welcome to our story. [pause] Listen closely. [laugh] Let us begin.",
"voice": "eve",
"language_code": "auto",
"output_format": {
"codec": "mp3",
"sample_rate": 24000,
"bit_rate": 128000
}
}
}
```
## OpenAPI
````yaml api-manual/music-series/xai-tts-v1.json POST /api/generate/submit
openapi: 3.0.0
info:
title: Vidgo API - xAI TTS 1
description: >-
Convert text into speech with xAI TTS, choosing from five voices and
multiple languages for narration, dialogue, and spoken content.
version: 1.0.0
servers:
- url: https://api.vidgo.ai
security:
- BearerAuth: []
paths:
/api/generate/submit:
post:
tags:
- Audio Series
summary: xAI TTS 1
description: >-
Generate speech from 1–15,000 characters using one of five voices. Place
speech settings inside input. Retrieve generated audio through the task
status endpoint; audio entries in files use file_type: audio.
operationId: submit_xai_tts_v1
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
additionalProperties: true
properties:
model:
type: string
example: xai/tts/v1
enum:
- xai/tts/v1
input:
type: object
required:
- text
additionalProperties: false
properties:
text:
type: string
minLength: 1
maxLength: 15000
description: >-
Text to speak, from 1 to 15,000 characters after
trimming leading and trailing whitespace. Use `[laugh]`,
`[pause]`, `[sigh]`, `text`, or
`text` to direct delivery.
voice:
type: string
enum:
- eve
- ara
- rex
- sal
- leo
default: eve
description: >-
Choose eve, ara, rex, sal, or leo for your narrator or
character. Default: eve.
language_code:
type: string
enum:
- auto
- en
- ar-EG
- ar-SA
- ar-AE
- bn
- zh
- fr
- de
- hi
- id
- it
- ja
- ko
- pt-BR
- pt-PT
- ru
- es-MX
- es-ES
- tr
- vi
default: auto
description: >-
Choose a listed BCP-47 language code, or auto for
automatic language detection.
output_format:
type: object
additionalProperties: false
properties:
codec:
type: string
enum:
- mp3
- wav
- pcm
- mulaw
- alaw
default: mp3
description: >-
Audio encoding: mp3, wav, pcm, mulaw, or alaw.
Default: mp3.
sample_rate:
type: integer
enum:
- 8000
- 16000
- 22050
- 24000
- 44100
- 48000
default: 24000
description: >-
Sample rate in Hz: 8000, 16000, 22050, 24000, 44100,
or 48000. Default: 24000.
bit_rate:
type: integer
nullable: true
enum:
- 32000
- 64000
- 96000
- 128000
- 192000
- null
default: 128000
description: >-
MP3 bitrate in bits per second: 32000, 64000, 96000,
128000, 192000, or null. MP3 default: 128000. For
wav, pcm, mulaw, and alaw, omit bit_rate or set it
to null.
description: >-
An object containing codec, sample_rate, and the MP3
bit_rate setting.
callback_url:
type: string
nullable: true
description: >-
Provide a public HTTP(S) callback_url to receive task
completion notifications. HTTPS is recommended.
description: >-
Place model and callback_url at the root. Put text, voice,
language_code, and output_format inside input.
example:
model: xai/tts/v1
input:
text: >-
Welcome to our story. [pause] Listen
closely. [laugh] Let us begin.
voice: eve
language_code: auto
output_format:
codec: mp3
sample_rate: 24000
bit_rate: 128000
responses:
'200':
description: Task submitted
content:
application/json:
schema:
type: object
required:
- code
- data
properties:
code:
type: integer
enum:
- 200
data:
type: object
required:
- task_id
- status
- created_time
properties:
task_id:
type: string
status:
type: string
enum:
- not_started
- running
- finished
- failed
created_time:
type: string
format: date-time
example:
code: 200
data:
task_id: task-unified-example
status: running
created_time: '2026-09-10T08:00:00'
'400':
description: Review the request parameters and account balance.
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'401':
description: Invalid credentials
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'403':
description: Access denied
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'404':
description: Unknown or disabled model
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'408':
description: Request timed out
content:
text/plain:
schema:
type: string
example: Request timeout
'422':
description: Invalid JSON or non-object request body
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'429':
description: >-
Request limit reached. Retry after the interval indicated by the
service.
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'500':
description: Internal error
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'502':
description: Task submission failed. Retry the request.
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'503':
description: Service temporarily unavailable. Retry later.
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Use VIDGO_API_KEY.
````