API v1
Complete reference
Guide aligned with Google Cloud TTS

Audio API Documentation

This guide covers the full technical flow: models, voices, languages, request formats, sync/async/stream examples, SSE events, signed webhooks, and compatibility notes.

Comenzar en 5 minutos

1. Crear API key

Desde /settings/api.

2. Probar sync

Ejecuta una solicitud minima y valida respuesta JSON.

3. Escalar a stream/async

SSE en tiempo real o jobs asincronos con webhook firmado.

curl -X POST "https://studio.dropabyte.com/v1/tts" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk_live_..." \
    -d '{
      "text": "Hello, this is a synchronous synthesis request.",
      "modelId": "google_gemini_2_5_flash_tts",
      "voiceName": "Zephyr",
      "languageCode": "en-US",
      "audioEncoding": "OGG_OPUS",
      "speakingRate": 1.0
    }'
Endpoints

POST /api/v1/tts

POST /api/v1/tts/stream

POST /api/v1/audio/generate-async

GET /api/v1/audio/status?jobId=:jobId

GET /api/v1/audio/download?jobId=:jobId

Authentication

x-api-key: sk_live_...

Authorization: Bearer sk_live_...

Diagnostic sandbox: admin panel only.

Security

Webhook with HMAC SHA-256 signature.

Safe comparison with timingSafeEqual.

Timestamp tolerance control.

Available models

Internally mapped to compatible providers (Cloud TTS by default; Vertex optional by feature flag).

ModelAPI IDCategoryMulti-speakerLatencyAPI cost / 100 chars
Gemini 3.1 Progoogle_gemini_3_1_pro_ttsGeminiSi< 500ms15
Gemini 3.1 Flashgoogle_gemini_3_1_flash_ttsGeminiSi< 500ms8
Gemini 3.1 Lite (Preview)google_gemini_3_1_lite_preview_ttsGeminiSi< 300ms6
Gemini 2.5 Progoogle_gemini_2_5_pro_ttsGeminiSi< 500ms15
Gemini 2.5 Flashgoogle_gemini_2_5_flash_ttsGeminiSi< 500ms8
Gemini 2.5 Flash Lite (Preview)google_gemini_2_5_flash_lite_ttsGeminiSi< 300ms6
Chirp 3 HDchirp-3-hdChirpNo< 150ms12
Neural2 Standardneural2-standardNeuralNo300-500ms10

Official Google TTS families

Reference guide based on official Google docs: Standard, WaveNet, Neural2, Studio, and Chirp 3 HD.

FamilyRecommended use caseControlMulti-speakerName example
StandardCost-efficient and general-purpose scenariosSSMLNoen-US-Standard-A
WaveNetBetter naturalness for premium general usageSSMLNoen-US-Wavenet-D
Neural2Modern neural voices for production appsSSMLNoen-US-Neural2-F
StudioNarration, news, media, and long-form contentSSML (with some restrictions)Single + Studio multi-speaker variantsen-US-Studio-O
Chirp 3 HDLow-latency natural conversationAdvanced controls; no full SSML supportDepends on flow/modelen-US-Chirp3-HD-Zephyr

Gemini TTS and 2.5 variants

Reference for Gemini audio models. In Google TTS, gemini-2.5-flash-tts and gemini-2.5-pro-tts are officially listed.

ModelID / CatalogBest forI/OMulti-speakerFormats
Gemini 2.5 Flash TTSgemini-2.5-flash-ttsLow latency, high volume, better cost-performanceText -> AudioYes (single and multi-speaker)LINEAR16, ALAW, MULAW, MP3, OGG_OPUS, PCM
Gemini 2.5 Pro TTSgemini-2.5-pro-ttsHigher expressiveness and style controlText -> AudioYes (single and multi-speaker)LINEAR16, ALAW, MULAW, MP3, OGG_OPUS, PCM
Gemini 2.5 Flash-Lite (Vertex catalog)Gemini 2.5 Flash-LiteMassive inference, very cost/latency-sensitive usageGeneral Gemini model in VertexVerify TTS availability by region/projectDepends on active endpoint/release

Note: Gemini 2.5 Flash-Lite appears in the general Vertex AI Gemini catalog. Exact TTS availability may vary by endpoint, region, and release stage.

Validate effective availability with project-level tests and official release notes.

Curated voices in the app
Voices visible in Studio and ready to use by name.
Achernar (Femenine)
google_gemini_3_1_pro_tts
Achird (Masculine)
google_gemini_3_1_pro_tts
Algenib (Masculine)
google_gemini_3_1_pro_tts
Algieba (Masculine)
google_gemini_3_1_pro_tts
Alnilam (Masculine)
google_gemini_3_1_pro_tts
Aoede (Femenine)
google_gemini_3_1_pro_tts
Autonoe (Femenine)
google_gemini_3_1_pro_tts
Callirrhoe (Femenine)
google_gemini_3_1_pro_tts
Charon (Masculine)
google_gemini_3_1_pro_tts
Despina (Femenine)
google_gemini_3_1_pro_tts
Enceladus (Masculine)
google_gemini_3_1_pro_tts
Erinome (Femenine)
google_gemini_3_1_pro_tts
Fenrir (Masculine)
google_gemini_3_1_pro_tts
Gacrux (Femenine)
google_gemini_3_1_pro_tts
Iapetus (Masculine)
google_gemini_3_1_pro_tts
Kore (Femenine)
google_gemini_3_1_pro_tts
Laomedeia (Femenine)
google_gemini_3_1_pro_tts
Leda (Femenine)
google_gemini_3_1_pro_tts
Orus (Masculine)
google_gemini_3_1_pro_tts
Pulcherrima (Femenine)
google_gemini_3_1_pro_tts
Puck (Masculine)
google_gemini_3_1_pro_tts
Rasalgethi (Masculine)
google_gemini_3_1_pro_tts
Sadachbia (Masculine)
google_gemini_3_1_pro_tts
Sadaltager (Masculine)
google_gemini_3_1_pro_tts
Schedar (Masculine)
google_gemini_3_1_pro_tts
Sulafat (Femenine)
google_gemini_3_1_pro_tts
Umbriel (Masculine)
google_gemini_3_1_pro_tts
Vindemiatrix (Femenine)
google_gemini_3_1_pro_tts
Zephyr (Femenine)
google_gemini_3_1_pro_tts
Zubenelgenubi (Masculine)
google_gemini_3_1_pro_tts
Achernar (Femenine)
google_gemini_3_1_flash_tts
Achird (Masculine)
google_gemini_3_1_flash_tts
Algenib (Masculine)
google_gemini_3_1_flash_tts
Algieba (Masculine)
google_gemini_3_1_flash_tts
Alnilam (Masculine)
google_gemini_3_1_flash_tts
Aoede (Femenine)
google_gemini_3_1_flash_tts
Autonoe (Femenine)
google_gemini_3_1_flash_tts
Callirrhoe (Femenine)
google_gemini_3_1_flash_tts
Charon (Masculine)
google_gemini_3_1_flash_tts
Despina (Femenine)
google_gemini_3_1_flash_tts
Enceladus (Masculine)
google_gemini_3_1_flash_tts
Erinome (Femenine)
google_gemini_3_1_flash_tts
Fenrir (Masculine)
google_gemini_3_1_flash_tts
Gacrux (Femenine)
google_gemini_3_1_flash_tts
Iapetus (Masculine)
google_gemini_3_1_flash_tts
Kore (Femenine)
google_gemini_3_1_flash_tts
Laomedeia (Femenine)
google_gemini_3_1_flash_tts
Leda (Femenine)
google_gemini_3_1_flash_tts
Orus (Masculine)
google_gemini_3_1_flash_tts
Pulcherrima (Femenine)
google_gemini_3_1_flash_tts
Puck (Masculine)
google_gemini_3_1_flash_tts
Rasalgethi (Masculine)
google_gemini_3_1_flash_tts
Sadachbia (Masculine)
google_gemini_3_1_flash_tts
Sadaltager (Masculine)
google_gemini_3_1_flash_tts
Schedar (Masculine)
google_gemini_3_1_flash_tts
Sulafat (Femenine)
google_gemini_3_1_flash_tts
Umbriel (Masculine)
google_gemini_3_1_flash_tts
Vindemiatrix (Femenine)
google_gemini_3_1_flash_tts
Zephyr (Femenine)
google_gemini_3_1_flash_tts
Zubenelgenubi (Masculine)
google_gemini_3_1_flash_tts
Achernar (Femenine)
google_gemini_3_1_lite_preview_tts
Achird (Masculine)
google_gemini_3_1_lite_preview_tts
Algenib (Masculine)
google_gemini_3_1_lite_preview_tts
Algieba (Masculine)
google_gemini_3_1_lite_preview_tts
Alnilam (Masculine)
google_gemini_3_1_lite_preview_tts
Aoede (Femenine)
google_gemini_3_1_lite_preview_tts
Autonoe (Femenine)
google_gemini_3_1_lite_preview_tts
Callirrhoe (Femenine)
google_gemini_3_1_lite_preview_tts
Charon (Masculine)
google_gemini_3_1_lite_preview_tts
Despina (Femenine)
google_gemini_3_1_lite_preview_tts
Enceladus (Masculine)
google_gemini_3_1_lite_preview_tts
Erinome (Femenine)
google_gemini_3_1_lite_preview_tts
Fenrir (Masculine)
google_gemini_3_1_lite_preview_tts
Gacrux (Femenine)
google_gemini_3_1_lite_preview_tts
Iapetus (Masculine)
google_gemini_3_1_lite_preview_tts
Kore (Femenine)
google_gemini_3_1_lite_preview_tts
Laomedeia (Femenine)
google_gemini_3_1_lite_preview_tts
Leda (Femenine)
google_gemini_3_1_lite_preview_tts
Orus (Masculine)
google_gemini_3_1_lite_preview_tts
Pulcherrima (Femenine)
google_gemini_3_1_lite_preview_tts
Puck (Masculine)
google_gemini_3_1_lite_preview_tts
Rasalgethi (Masculine)
google_gemini_3_1_lite_preview_tts
Sadachbia (Masculine)
google_gemini_3_1_lite_preview_tts
Sadaltager (Masculine)
google_gemini_3_1_lite_preview_tts
Schedar (Masculine)
google_gemini_3_1_lite_preview_tts
Sulafat (Femenine)
google_gemini_3_1_lite_preview_tts
Umbriel (Masculine)
google_gemini_3_1_lite_preview_tts
Vindemiatrix (Femenine)
google_gemini_3_1_lite_preview_tts
Zephyr (Femenine)
google_gemini_3_1_lite_preview_tts
Zubenelgenubi (Masculine)
google_gemini_3_1_lite_preview_tts
Achernar (Femenine)
google_gemini_2_5_pro_tts
Achird (Masculine)
google_gemini_2_5_pro_tts
Algenib (Masculine)
google_gemini_2_5_pro_tts
Algieba (Masculine)
google_gemini_2_5_pro_tts
Alnilam (Masculine)
google_gemini_2_5_pro_tts
Aoede (Femenine)
google_gemini_2_5_pro_tts
Autonoe (Femenine)
google_gemini_2_5_pro_tts
Callirrhoe (Femenine)
google_gemini_2_5_pro_tts
Charon (Masculine)
google_gemini_2_5_pro_tts
Despina (Femenine)
google_gemini_2_5_pro_tts
Enceladus (Masculine)
google_gemini_2_5_pro_tts
Erinome (Femenine)
google_gemini_2_5_pro_tts
Fenrir (Masculine)
google_gemini_2_5_pro_tts
Gacrux (Femenine)
google_gemini_2_5_pro_tts
Iapetus (Masculine)
google_gemini_2_5_pro_tts
Kore (Femenine)
google_gemini_2_5_pro_tts
Laomedeia (Femenine)
google_gemini_2_5_pro_tts
Leda (Femenine)
google_gemini_2_5_pro_tts
Orus (Masculine)
google_gemini_2_5_pro_tts
Pulcherrima (Femenine)
google_gemini_2_5_pro_tts
Puck (Masculine)
google_gemini_2_5_pro_tts
Rasalgethi (Masculine)
google_gemini_2_5_pro_tts
Sadachbia (Masculine)
google_gemini_2_5_pro_tts
Sadaltager (Masculine)
google_gemini_2_5_pro_tts
Schedar (Masculine)
google_gemini_2_5_pro_tts
Sulafat (Femenine)
google_gemini_2_5_pro_tts
Umbriel (Masculine)
google_gemini_2_5_pro_tts
Vindemiatrix (Femenine)
google_gemini_2_5_pro_tts
Zephyr (Femenine)
google_gemini_2_5_pro_tts
Zubenelgenubi (Masculine)
google_gemini_2_5_pro_tts
Achernar (Femenine)
google_gemini_2_5_flash_tts
Achird (Masculine)
google_gemini_2_5_flash_tts
Algenib (Masculine)
google_gemini_2_5_flash_tts
Algieba (Masculine)
google_gemini_2_5_flash_tts
Alnilam (Masculine)
google_gemini_2_5_flash_tts
Aoede (Femenine)
google_gemini_2_5_flash_tts
Autonoe (Femenine)
google_gemini_2_5_flash_tts
Callirrhoe (Femenine)
google_gemini_2_5_flash_tts
Charon (Masculine)
google_gemini_2_5_flash_tts
Despina (Femenine)
google_gemini_2_5_flash_tts
Enceladus (Masculine)
google_gemini_2_5_flash_tts
Erinome (Femenine)
google_gemini_2_5_flash_tts
Fenrir (Masculine)
google_gemini_2_5_flash_tts
Gacrux (Femenine)
google_gemini_2_5_flash_tts
Iapetus (Masculine)
google_gemini_2_5_flash_tts
Kore (Femenine)
google_gemini_2_5_flash_tts
Laomedeia (Femenine)
google_gemini_2_5_flash_tts
Leda (Femenine)
google_gemini_2_5_flash_tts
Orus (Masculine)
google_gemini_2_5_flash_tts
Pulcherrima (Femenine)
google_gemini_2_5_flash_tts
Puck (Masculine)
google_gemini_2_5_flash_tts
Rasalgethi (Masculine)
google_gemini_2_5_flash_tts
Sadachbia (Masculine)
google_gemini_2_5_flash_tts
Sadaltager (Masculine)
google_gemini_2_5_flash_tts
Schedar (Masculine)
google_gemini_2_5_flash_tts
Sulafat (Femenine)
google_gemini_2_5_flash_tts
Umbriel (Masculine)
google_gemini_2_5_flash_tts
Vindemiatrix (Femenine)
google_gemini_2_5_flash_tts
Zephyr (Femenine)
google_gemini_2_5_flash_tts
Zubenelgenubi (Masculine)
google_gemini_2_5_flash_tts
Achernar (Femenine)
google_gemini_2_5_flash_lite_tts
Achird (Masculine)
google_gemini_2_5_flash_lite_tts
Algenib (Masculine)
google_gemini_2_5_flash_lite_tts
Algieba (Masculine)
google_gemini_2_5_flash_lite_tts
Alnilam (Masculine)
google_gemini_2_5_flash_lite_tts
Aoede (Femenine)
google_gemini_2_5_flash_lite_tts
Autonoe (Femenine)
google_gemini_2_5_flash_lite_tts
Callirrhoe (Femenine)
google_gemini_2_5_flash_lite_tts
Charon (Masculine)
google_gemini_2_5_flash_lite_tts
Despina (Femenine)
google_gemini_2_5_flash_lite_tts
Enceladus (Masculine)
google_gemini_2_5_flash_lite_tts
Erinome (Femenine)
google_gemini_2_5_flash_lite_tts
Fenrir (Masculine)
google_gemini_2_5_flash_lite_tts
Gacrux (Femenine)
google_gemini_2_5_flash_lite_tts
Iapetus (Masculine)
google_gemini_2_5_flash_lite_tts
Kore (Femenine)
google_gemini_2_5_flash_lite_tts
Laomedeia (Femenine)
google_gemini_2_5_flash_lite_tts
Leda (Femenine)
google_gemini_2_5_flash_lite_tts
Orus (Masculine)
google_gemini_2_5_flash_lite_tts
Pulcherrima (Femenine)
google_gemini_2_5_flash_lite_tts
Puck (Masculine)
google_gemini_2_5_flash_lite_tts
Rasalgethi (Masculine)
google_gemini_2_5_flash_lite_tts
Sadachbia (Masculine)
google_gemini_2_5_flash_lite_tts
Sadaltager (Masculine)
google_gemini_2_5_flash_lite_tts
Schedar (Masculine)
google_gemini_2_5_flash_lite_tts
Sulafat (Femenine)
google_gemini_2_5_flash_lite_tts
Umbriel (Masculine)
google_gemini_2_5_flash_lite_tts
Vindemiatrix (Femenine)
google_gemini_2_5_flash_lite_tts
Zephyr (Femenine)
google_gemini_2_5_flash_lite_tts
Zubenelgenubi (Masculine)
google_gemini_2_5_flash_lite_tts
Achernar (Femenine)
chirp-3-hd
Achird (Masculine)
chirp-3-hd
Algenib (Masculine)
chirp-3-hd
Algieba (Masculine)
chirp-3-hd
Alnilam (Masculine)
chirp-3-hd
Aoede (Femenine)
chirp-3-hd
Autonoe (Femenine)
chirp-3-hd
Callirrhoe (Femenine)
chirp-3-hd
Charon (Masculine)
chirp-3-hd
Despina (Femenine)
chirp-3-hd
Enceladus (Masculine)
chirp-3-hd
Erinome (Femenine)
chirp-3-hd
Fenrir (Masculine)
chirp-3-hd
Gacrux (Femenine)
chirp-3-hd
Iapetus (Masculine)
chirp-3-hd
Kore (Femenine)
chirp-3-hd
Laomedeia (Femenine)
chirp-3-hd
Leda (Femenine)
chirp-3-hd
Orus (Masculine)
chirp-3-hd
Puck (Masculine)
chirp-3-hd
Pulcherrima (Femenine)
chirp-3-hd
Rasalgethi (Masculine)
chirp-3-hd
Sadachbia (Masculine)
chirp-3-hd
Sadaltager (Masculine)
chirp-3-hd
Schedar (Masculine)
chirp-3-hd
Sulafat (Femenine)
chirp-3-hd
Umbriel (Masculine)
chirp-3-hd
Vindemiatrix (Femenine)
chirp-3-hd
Zephyr (Femenine)
chirp-3-hd
Zubenelgenubi (Masculine)
chirp-3-hd
Neural2-A (Masculine)
neural2-standard
Neural2-C (Femenine)
neural2-standard
Neural2-D (Masculine)
neural2-standard
Neural2-E (Femenine)
neural2-standard
Neural2-F (Femenine)
neural2-standard
Neural2-G (Femenine)
neural2-standard
Neural2-H (Femenine)
neural2-standard
Neural2-I (Masculine)
neural2-standard
Neural2-J (Masculine)
neural2-standard
Chirp/HD voice names (Google guide)
Google publishes a broader inventory by language and voice type. This list shows common base names.
Achird
Algenib
Aoede
Callirrhoe
Charon
Enceladus
Fenrir
Kore
Leda
Orus
Puck
Schedar
Umbriel
Zephyr

For full up-to-date inventory by region/language, use GET https://texttospeech.googleapis.com/v1/voices.

Languages

Common languages enabled in the app (BCP-47). Google Cloud supports a wider catalog by voice type.

en-US - English (US)
es-MX - Español (México)
es-US - Español (EE. UU.)
es-ES - Español (España)
fr-FR - Français
de-DE - Deutsch
it-IT - Italiano
pt-BR - Português (Brasil)
ja-JP - 日本語
ko-KR - 한국어
zh-CN - 中文 (Simp)

Official real-time voices/languages lookup:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://texttospeech.googleapis.com/v1/voices"

Request formats

curl -X POST "https://studio.dropabyte.com/v1/tts" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk_live_..." \
    -d '{
      "text": "Hello, this is a synchronous synthesis request.",
      "modelId": "google_gemini_2_5_flash_tts",
      "voiceName": "Zephyr",
      "languageCode": "en-US",
      "audioEncoding": "OGG_OPUS",
      "speakingRate": 1.0
    }'

Supported parameters

FieldTypeRequiredDescription
textstringConditionalPlain text to synthesize (use text or turns).
turnsarray<{speaker,text}>ConditionalStructured multi-speaker dialogue.
speakersarray<{speaker,voiceName}>NoVoice mapping by speaker in dialogue mode.
modelIdstringYesTTS model ID.
voiceNamestringNoPrimary voice when not using multi-speaker.
languageCodestringNoBCP-47 code such as en-US or es-ES.
audioEncodingMP3|OGG_OPUS|LINEAR16|PCM|WAVNoAudio output format.
sampleRateHertznumberNoTarget sample rate in Hz.
speakingRatenumberNoSpeech rate.
pitchnumberNoPitch adjustment.
volumeGainDbnumberNoVolume gain in dB.
editing.normalizebooleanNo (async)Normalize post-processed volume.
editing.trimSilencebooleanNo (async)Trim leading/trailing silence.
editing.backgroundAudioUrlurlNo (async)Background layer for FFmpeg mix.
webhookUrlurlNo (async)Callback URL after job completion.
webhookSecretstringNo (async)Secret for HMAC SHA-256 signature.

Codificaciones de audio

audioEncodingMIME tipicoNotas
MP3audio/mpegTamano pequeno, ideal para entrega web/mobile.
OGG_OPUSaudio/oggMuy eficiente para voz y streaming.
LINEAR16audio/wavPCM con encabezado WAV en salidas sync.
PCMaudio/wavSin compresion, util para pipelines DSP.
WAVaudio/wavSalida WAV directa para compatibilidad.

Respuestas y eventos

Errores y estados HTTP

400 Body invalido o parametros fuera de rango.
401 Falta API key.
403 API key invalida o revocada.
402 Creditos insuficientes.
404 Job no encontrado.
500 Error interno en TTS o post-proceso.

Webhooks firmados (HMAC)

Headers enviados
Si incluyes webhookSecret (o configuras WEBHOOK_SIGNING_SECRET) se adjuntan headers de firma.

x-dropabyte-signature: hex HMAC SHA-256

x-dropabyte-timestamp: unix ms

x-dropabyte-signature-alg: hmac-sha256

Verificacion recomendada
import crypto from "crypto";

export function verifyDropabyteWebhook({
  rawBody,
  signature,
  timestamp,
  secret,
  toleranceMs = 5 * 60 * 1000,
}: {
  rawBody: string;
  signature: string;
  timestamp: string;
  secret: string;
  toleranceMs?: number;
}) {
  const now = Date.now();
  const ts = Number(timestamp);
  if (!Number.isFinite(ts)) return false;
  if (Math.abs(now - ts) > toleranceMs) return false;

  const payloadToSign = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac("sha256", secret).update(payloadToSign).digest("hex");

  const expectedBuf = Buffer.from(expected, "utf8");
  const receivedBuf = Buffer.from(signature || "", "utf8");
  if (expectedBuf.length !== receivedBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}
Esta referencia esta preparada para implementacion directa de backend y frontend.