# Gemini 3.8 Flash TTS

> Generate expressive multilingual speech with Gemini 3.8 Flash TTS. Direct emotion and pacing with separate style instructions, choose from 30 preset voices, and create structured two-speaker dialogue.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/gemini-3-8-flash-tts
- Model page ID: `gemini-3-8-flash-tts`
- API model ID: `gemini-3.8-flash-tts`
- Category: Music
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- Text and style instructions: 9 credits ($0.045) per 1000 characters

For more details, see https://poyo.ai/models/gemini-3-8-flash-tts.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  - Options: `"gemini-3.8-flash-tts"`
- `callback_url` (`string`, optional):
  Optional completion or failure callback URL.

### Input Schema

Use either text (single speaker) or speakers with turns (dialogue). These modes are mutually exclusive; dialogue cannot include top-level text or voice.

The API accepts the following `input` parameters:

- `voice` (`VoiceEnum`, optional):
  Single-speaker voice, default Kore. Omit when using speakers and turns.
  - Default: `"Kore"`
  - Options: `"Achernar"`, `"Achird"`, `"Algenib"`, `"Algieba"`, `"Alnilam"`, `"Aoede"`, `"Autonoe"`, `"Callirrhoe"`, `"Charon"`, `"Despina"`, `"Enceladus"`, `"Erinome"`, `"Fenrir"`, `"Gacrux"`, `"Iapetus"`, `"Kore"`, `"Laomedeia"`, `"Leda"`, `"Orus"`, `"Pulcherrima"`, `"Puck"`, `"Rasalgethi"`, `"Sadachbia"`, `"Sadaltager"`, `"Schedar"`, `"Sulafat"`, `"Umbriel"`, `"Vindemiatrix"`, `"Zephyr"`, `"Zubenelgenubi"`
- `speakers` (`list`, optional):
  Required together with turns for dialogue. Exactly two speakers with distinct non-empty speaker_id values. Omit text and top-level voice.
  - Array of object
  - Length: 2 to 2
- `turns` (`list`, optional):
  Required together with speakers for dialogue. At least one turn; speaker_id must reference a configured speaker. Each turn supports optional style_instructions.
  - Array of object
  - Length: 1 to unbounded
- `enable_safety_checker` (`boolean`, optional):
  Enable input safety checking. Disabling requires account authorization when applicable.
  - Default: `true`
- `style_instructions` (`string`, optional):
  Global delivery style, separate from the transcript.
- `text` (`string`, optional):
  Single-speaker transcript. Required for single-speaker mode. Omit when using speakers and turns. Complete input is limited to 8192 tokens.
  - Length: 1 to unbounded characters

Required Parameters Example:

```json
{
  "model": "gemini-3.8-flash-tts",
  "input": {
    "text": "Hello! Welcome to PoYo."
  }
}
```

Full Example:

```json
{
  "model": "gemini-3.8-flash-tts",
  "input": {
    "text": "Hello! Welcome to PoYo.",
    "voice": "Kore",
    "enable_safety_checker": true
  }
}
```

example-2:

```json
{
  "model": "gemini-3.8-flash-tts",
  "input": {
    "speakers": [
      {
        "speaker_id": "host",
        "voice": "Kore"
      },
      {
        "speaker_id": "guest",
        "voice": "Puck"
      }
    ],
    "turns": [
      {
        "speaker_id": "host",
        "text": "Welcome!"
      },
      {
        "speaker_id": "guest",
        "text": "Thank you.",
        "style_instructions": "Warm and friendly."
      }
    ]
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`integer`, required):
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/models/gemini-3-8-flash-tts/examples/gemini-3-8-flash-tts-default-output-1-eef1d81ec1547b0f.wav",
        "file_type": "audio"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"gemini-3.8-flash-tts","input":{"text":"Hello! Welcome to PoYo."}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"gemini-3.8-flash-tts\",\n  \"input\": {\n    \"text\": \"Hello! Welcome to PoYo.\"\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "gemini-3.8-flash-tts",
  "input": {
    "text": "Hello! Welcome to PoYo."
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/gemini-3-8-flash-tts)
- [API Documentation](https://docs.poyo.ai/api-manual/music-series/gemini-3-8-flash-tts)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/music-series/gemini-3-8-flash-tts.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`