> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audixa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Generation

> Start a text-to-speech generation job

Submits a text-to-speech task and returns a `generation_id` for tracking. The audio is generated asynchronously—use the [Get Generation](/api-reference/generation) endpoint to check when it's ready.

```bash Endpoint theme={null}
POST https://api.audixa.ai/v3/tts
```

## Request

<ParamField body="text" type="string" required>
  The text to convert to speech. Maximum 50,000 characters (varies by plan).
</ParamField>

<ParamField body="voice_id" type="string" required>
  The voice ID to use. Get available voices from [/voices](/api-reference/voices).
</ParamField>

<ParamField body="model" type="string" default="base">
  The model tier to use.

  * `base`: Standard high-quality voices. Lowest cost/latency.
  * `advanced`: Premium voices. Supports cloning and higher expressiveness.
</ParamField>

<ParamField body="speed" type="number" default="1.0">
  Playback speed multiplier. Range: `0.5` to `2.0`.
</ParamField>

### Advanced Model Settings

<ParamField body="cfg_weight" type="number" default="2.5">
  Controls how strictly the model follows the text/style. Range: `1.0` - `5.0`.
</ParamField>

<ParamField body="exaggeration" type="number" default="0.5">
  Controls emotional fluctuation/expressiveness. Range: `0.0` - `1.0`.
</ParamField>

<ParamField body="audio_format" type="string" default="wav">
  Output format: `wav` or `mp3`.
</ParamField>

<ParamField body="language_code" type="string">
  Optional language code for the input text. The accepted values depend on
  `model`:

  * **Base model** uses single-letter codes:
    `a` (American English), `b` (British English), `j` (Japanese),
    `z` (Mandarin Chinese), `e` (Spanish), `f` (French), `h` (Hindi),
    `i` (Italian), `p` (Brazilian Portuguese).
  * **Advanced model** uses ISO 639-1 codes:
    `en`, `ar`, `da`, `de`, `el`, `es`, `fi`, `fr`, `he`, `hi`, `it`,
    `ja`, `ko`, `ms`, `nl`, `no`, `pl`, `pt`, `ru`, `sv`, `sw`, `tr`, `zh`.

  If omitted, the model falls back to its default language.
</ParamField>

## Response

<ResponseField name="generation_id" type="string">
  Unique identifier for this generation job. Use this to poll [/tts](/api-reference/generation).
</ResponseField>

<ResponseField name="status" type="string">
  Initial status: `IN_QUEUE`.
</ResponseField>

<ResponseField name="input_text" type="string">
  The input text that was submitted.
</ResponseField>

<ResponseField name="voice_id" type="string">
  Voice ID used for generation.
</ResponseField>

<ResponseField name="voice_name" type="string">
  Human-readable voice name.
</ResponseField>

<ResponseField name="model" type="string">
  TTS model used (`base` or `advanced`).
</ResponseField>

<ResponseField name="tokens" type="integer">
  Number of tokens consumed.
</ResponseField>

<ResponseField name="dollar_cost" type="number">
  Cost in USD (set when generation completes).
</ResponseField>

<ResponseField name="method" type="string">
  Payment method used: `API_WALLET` or `CREDITS_BALANCE`.
</ResponseField>

<ResponseField name="audio_url" type="string">
  URL to download the generated audio (when status=`COMPLETED`).
</ResponseField>

<ResponseField name="error_message" type="string">
  Error details if status=`FAILED`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp when processing started.
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 timestamp when processing completed.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.audixa.ai/v3/tts" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "text": "Hello world from Audixa!",
      "voice_id": "am_ethan",
      "model": "base",
      "speed": 1.0,
      "audio_format": "wav",
      "language_code": "a"
    }'
  ```

  ```python Python theme={null}
  import audixa

  audixa.set_api_key("YOUR_API_KEY")

  # Asynchronous generation (returns immediately)
  generation_id = audixa.tts(
      "Hello world from Audixa!",
      voice_id="am_ethan",
      model="base",
  )
  print(f"Generation ID: {generation_id}")

  # Or generate and wait for completion
  audio_url = audixa.tts_and_wait(
      "Hello world from Audixa!",
      voice_id="am_ethan",
  )

  # Advanced model in a non-English language
  audio_url = audixa.tts_and_wait(
      "Hallo, willkommen bei Audixa!",
      voice_id="am_ethan",
      model="advanced",
      language_code="de",
  )
  ```

  ```typescript TypeScript theme={null}
  import Audixa from 'audixa';

  const audixa = new Audixa('YOUR_API_KEY');

  // Asynchronous generation
  const { generation_id } = await audixa.startTTS({
    text: 'Hello world from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Generation ID:', generation_id);

  // Or generate and wait (convenience method)
  const audioUrl = await audixa.generateTTS({
    text: 'Hello world from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Audio URL:', audioUrl);
  ```

  ```javascript JavaScript theme={null}
  import Audixa from 'audixa';

  const audixa = new Audixa('YOUR_API_KEY');

  // Asynchronous generation
  const { generation_id } = await audixa.startTTS({
    text: 'Hello world from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Generation ID:', generation_id);

  // Or generate and wait (convenience method)
  const audioUrl = await audixa.generateTTS({
    text: 'Hello world from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Audio URL:', audioUrl);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "generation_id": "gen_abc123xyz",
    "status": "IN_QUEUE",
    "input_text": "Hello world from Audixa!",
    "voice_id": "am_ethan",
    "voice_name": "Ethan",
    "model": "base",
    "tokens": 6,
    "dollar_cost": 0.000006,
    "method": null,
    "created_at": "2025-02-05T12:00:00Z",
    "started_at": null,
    "completed_at": null
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="400 Bad Request">
  Invalid parameters (e.g. invalid model, voice not found).
</Accordion>

<Accordion title="402 Payment Required">
  Insufficient balance.
</Accordion>

<Accordion title="429 Too Many Requests">
  Rate limit exceeded.
</Accordion>