Developer documentation
Speech API reference
Giggy provides text-to-speech and speech-to-text APIs. Batch costs $2 per million characters (Fast $5) and $0.02 per audio hour (Fast $0.04), and runs at the lowest queue priority; Fast and Streaming deliver sooner. REST and MCP default to Fast when mode is omitted.
API authentication
Use https://api.giggy.ai/v1 for TTS and STT. Existing integrations can keep https://giggy.ai/v1; API keys, request formats, billing and generation history are shared. Keep each operation on its admitting origin. Send xi-api-key: <key>. Keys start with giggy_sk_, are shown once when created or rotated, and are rejected immediately after revocation. Each Personal space or Workspace may keep up to ten active REST API keys. A key permanently belongs to the Personal space or Workspace in which it was created; switching the browser to another Workspace does not transfer the key. Keep keys server-side in GIGGY_API_KEY, never browser code.
API errors and status codes
Handle the HTTP status first and inspect the structured detail fields type, code, message, status, request_id and param. 400: malformed JSON, generation UUID or list parameters. 401: missing, invalid or revoked key. 402: inspect detail.code for credits, recharge or spending-policy restrictions. 404: generation or voice unavailable to the owning Personal space or Workspace. 409: idempotency key reused with different parameters. 422: invalid text, mode, voice, language, output, option, body property or idempotency key. 429: honor Retry-After, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; Reset is seconds remaining, not a Unix timestamp. Per credential per minute: 60 Batch speech-generation POST requests, 120 generation-event-stream GET requests, 600 reads/list/balance requests and 120 MCP requests. Fast and Streaming speech-generation POST requests have no per-credential 60-request limit; IP safeguards and credit admission still apply. 500: request failed. 503: required storage or media-signing service unavailable. 504: the synchronous wait expired; the durable generation may still be processing or may later fail. Reconcile the known generation or History. Any TTS submission retry must reuse the same Idempotency-Key and unchanged request; never automatically replay a consumed audio stream.
Text-to-speech billing
Batch: $2.00; Fast: $5.00 per 1,000,000 input characters; Streaming: $10.00 per 1,000,000 input characters with Pro, Studio or Scale credits. Starter and Creator cost more per credit.
TTS counts Unicode code points in the full submitted text, including spaces and punctuation, not UTF-8 bytes or generated audio duration. The same character rates apply across supported languages. Each paid request rounds up to a pricing block with a minimum charge. REST and MCP use the app's selected-mode rates; free homepage and authenticated Playground previews retain their preview exemption.
Batch: 10 credits per started 50-character block, minimum 10 credits. Fast: 10 credits per started 20-character block, minimum 10 credits. Streaming: 10 credits per started 10-character block, minimum 10 credits. See pricing and plan estimates.
API base URL
Use https://api.giggy.ai/v1 for text-to-speech and speech-to-text. Existing integrations can continue using https://giggy.ai/v1 with the same API keys, request formats, billing and generation history. Keep each operation on the origin where it was admitted.
Core developer endpoints
- POST /v1/text-to-speech — native Giggy text-to-speech with Batch, Fast, and Streaming modes. Batch costs $2 per million characters (Fast $5) and runs at the lowest queue priority.
- POST /v1/audio/speech — OpenAI-compatible text-to-speech adapter for voice-product integrations.
- POST /v1/audio/transcriptions — WAV PCM16, mono, 8 kHz or 16 kHz. Batch, Fast and uploaded-recording Streaming: 0.5 seconds–12 hours. Batch costs 2,000 credits per audio hour; Fast costs 4,000; Streaming costs 8,000, rounded up per request. Batch/Fast return HTTP 202 generation JSON; Streaming returns cumulative transcript SSE.
- Request privacy (TTS/STT) — Put
privacy: {content_retention_12h: true, compute_eea_adequate_only: true}last in the JSON body or WebSocketstartmessage. Raw WAV STT uses trailingcontent_retention_12h=true&compute_eea_adequate_only=truequery parameters. Optional booleans; omission or false preserves the existing policy. See request shapes and fields. - WebSocket wss://api.giggy.ai/v1/audio/transcriptions — production default for live STT. Authenticate with Authorization: Bearer or xi-api-key in the upgrade headers. Send start, wait for generation_created and ready, then send binary mono audio (LINEAR16 at 8 or 16 kHz, or MULAW at 8 kHz) and stop on the same socket. Transcription and input_complete events return there. HTTPS/SSE live input remains an explicit legacy transport.
- GET /v1/voices — list public Giggy voices.
- GET /v1/my-voices — list custom voices owned by the API-key scope.
- GET /v1/generations/{generationUuid} — read durable generation state and completed results.
- GET /v1/generations/{generationUuid}/stream — stream generation events and ordered PCM chunks using server-sent events.
- GET /v1/integrations/voices — public connector voice catalog.
- POST /v1/integrations/vapi/text-to-speech/{voiceId} — Vapi custom TTS webhook.
Partner integrations: LiveKit, Pipecat and Jambonz
Use these compatibility integrations with your existing voice stack. They do not establish upstream provider listings or commercial partnerships. Keep Giggy API keys server-side. Existing integrations can retain the legacy origin and installed transport until their adapter is updated and qualified.
LiveKit
Configure the LiveKit OpenAI TTS plugin with base_url=https://api.giggy.ai/v1, model=giggyspeech, your Giggy voice UUID and response_format=pcm. Supply STT, LLM, VAD and room transport separately; a base URL change does not supply a native STT adapter. Disable automatic synthesis replay after partial streaming. Native Giggy provider publication is not verified by this guide; this is the documented OpenAI-compatible TTS path.
LiveKit runnable TTS example. Older example checkouts may still use giggy.ai; explicitly configure api.giggy.ai for the API path.
Pipecat
pipecat-giggy 0.3.3 is the released Giggy-maintained TTS/live STT adapter. Install with python -m pip install pipecat-giggy==0.3.3; the tested Pipecat dependency is 1.12.0. It uses one-socket live STT with binary PCM, explicit stop, canonical decode preparation, fenced final events and saved-result verification. Applications own transport and upstream turn timing. Drain the lifecycle and surface verification errors after final text. Version 0.2.0 retains its earlier transport. Native LiveKit streaming STT remains available from its unreleased source PR.
Jambonz
Configure a custom STT provider with wss://api.giggy.ai/v1/audio/transcriptions and your Giggy API key. Jambonz sends Authorization: Bearer on the upgrade, then start, binary 8 kHz mono LINEAR16 and stop on one socket; transcription messages return there. Giggy converts 8 kHz continuously to canonical 16 kHz. Do not use the HTTPS recording endpoint for live recognition. Without external endpointing, the existing energy threshold and 650 ms silence rule delimit utterances; test quiet speech and noise. Unsupported hints reject explicitly.
Jambonz custom STT specification · Giggy live STT guide. The Jambonz-style wire protocol is tested; native media-server calls require separate end-to-end qualification. STT compatibility does not establish support for Jambonz streaming TTS.
Speech-to-text quickstart: Python and JavaScript
Giggy STT supports uploaded recordings and live microphone audio. Keep GIGGY_API_KEY on your server. Use https://api.giggy.ai/v1 for recording STT and wss://api.giggy.ai/v1/audio/transcriptions for live STT. Install the published Python SDK with python -m pip install giggy==0.2.1 (Python 3.10+) or JavaScript/TypeScript SDK with npm install @giggy-ai/sdk@0.2.1 (Node.js 22+). For uploaded recordings, prepare signed PCM16 mono 16 kHz WAV, for example with ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le recording.wav. Batch and Fast accept 0.5 seconds–12 hours. Batch costs half of Fast and runs at the lowest queue priority.
Python: retrieve the final transcript
import os
from giggy import Giggy
giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"], base_url="https://api.giggy.ai/v1")
result = giggy.transcriptions.transcribe("recording.wav", mode="batch")
print(result["text"])
JavaScript: retrieve the final transcript
import { Giggy } from '@giggy-ai/sdk';
const giggy = new Giggy({ apiKey: process.env.GIGGY_API_KEY, baseURL: 'https://api.giggy.ai/v1' });
const result = await giggy.transcriptions.transcribe({ audioPath: 'recording.wav', mode: 'batch' });
console.log(result.text);
These existing SDK methods submit once, wait for durable completion and fetch the signed transcript without forwarding your API key to the artifact host. The default SDK mode is Batch; direct REST requests default to paid Fast. For raw REST, POST the WAV body with Content-Type: audio/wav and xi-api-key. Batch/Fast admission returns HTTP 202 with generation.generation_uuid, not transcript text. Retain that UUID, read GET /v1/generations/{generationUuid} until completed, then fetch generation.result.url for the final transcript JSON. A timeout is not permission to upload the same recording again.
Choose the spoken language (optional)
ar- Arabic
yue- Cantonese
zh- Chinese (Mandarin)
cs- Czech
nl- Dutch
en- English
fil- Filipino
fr- French
de- German
el- Greek
hi- Hindi
hu- Hungarian
id- Indonesian
it- Italian
ja- Japanese
ko- Korean
ms- Malay
fa- Persian (Farsi)
pl- Polish
pt- Portuguese
ro- Romanian
ru- Russian
es- Spanish
sv- Swedish
th- Thai
tr- Turkish
vi- Vietnamese
For uploaded recordings in Batch, Fast, or Streaming, set language to a supported language code, such as en, to skip automatic language detection. With a raw WAV body, use POST /v1/audio/transcriptions?mode=fast&language=en. With a JSON data URL, include "language": "en". Use autodetect, the default, for automatic detection. Live WebSocket start accepts the same language values. Transcripts report detected languages as codes.
Choose the correct transcription workflow
| Workflow | Input and delivery | Completion |
|---|---|---|
| Uploaded recording: Batch or Fast | Completed WAV; HTTP 202 admission, then durable status | Fetch canonical transcript after completed |
| Streaming an uploaded recording | Completed WAV; cumulative transcript_chunk SSE revisions, up to 12 hours | Replace provisional text; reconcile the UUID and fetch the final result |
| Live microphone: Streaming | One authenticated WebSocket; send start, wait for ready, then binary PCM16 mono and stop; paid API up to 12 hours, previews and reference replay up to 30 seconds | Validate input_complete and final transcription identity/sequence; verify durable completion and saved transcript |
Application capture, resampling, VAD and turn boundaries are your responsibility. Closing unfinished live input cancels it; closing uploaded-recording SSE does not cancel the admitted recording. Paid API live input holds a five-minute block (667 credits, 1,334 with translation) and extends it automatically while audio flows. When no further credit can be held, the socket sends credits_low before the last block and a credits_exhausted error at its end, finalizes the transcript so far, and settles against accepted audio duration. Do not append cumulative revisions or treat them as verified final text.
Complete examples: Python uploaded-WAV Streaming · JavaScript uploaded-WAV Streaming · Python live microphone · Node live PCM replay. A replay example tests the live protocol; it does not capture microphone hardware.
Live STT: one WebSocket for audio and transcripts
Connect your server to wss://api.giggy.ai/v1/audio/transcriptions with Authorization: Bearer or xi-api-key in the upgrade headers. Keep credentials off browser clients. Send {"type":"start","format":"raw","encoding":"LINEAR16","sampleRateHz":16000,"interimResults":true,"options":{"endpointing":"external"}}; optionally set language. Telephony audio may use "sampleRateHz":8000 with "encoding":"LINEAR16" or "encoding":"MULAW" (G.711 μ-law, as sent by Twilio Media Streams); Giggy converts it to canonical 16 kHz. Wait for generation_created and ready before sending headerless binary mono audio in the declared encoding. Send {"type":"stop"} after the real tail. Do not open an HTTPS request every 20 ms.
Replace cumulative transcription text. Validate generation UUID, attempt, increasing sequence and is_final; require input_complete before publishing final text. Continue to canonical completion and verify saved text and duration. Jambonz can use the same endpoint with8 kHz LINEAR16 start/audio/stop;8 kHz is converted continuously to canonical 16 kHz. Without external endpointing, the existing energy threshold and 650ms silence rule delimit turns. Quiet speech and background noise require testing.
Paid API input supports 0.5 seconds to 12 hours. Live input holds credit in five-minute blocks while audio flows and settles against accepted duration. Previews and the reference replay are capped at 30 seconds. Start promptly, bound capture queues, and honor input/idle watchdogs. A disconnect cancels unfinished work; do not reconnect or replay ambiguous PCM. Existing HTTPS/SSE clients remain supported explicitly. Sockets remain pinned to the admitting controller while deployments drain.
Download the locked Node WebSocket reference client. Extract, run npm ci, set GIGGY_API_KEY and GIGGY_STT_ORIGIN=https://api.giggy.ai, then run npm start -- --input recording.wav --allow-billable. The example replays 0.5–30 seconds of PCM16 mono 16 kHz WAV at capture cadence; applications own microphone capture and endpointing. Published SDK transports do not automatically change when this guide changes.
Migrate an OpenAI or AssemblyAI application
OpenAI-compatible text-to-speech uses https://api.giggy.ai/v1/audio/speech: keep the OpenAI speech client, set its base URL to https://api.giggy.ai/v1, authenticate with your Giggy key, set model=giggyspeech and use a Giggy voice UUID. Choose a supported response format and disable automatic synthesis retries. See the existing OpenAI-client TTS example.
Speech-to-text is a separate contract. Changing an OpenAI client base URL alone does not migrate audio.transcriptions.create: the Giggy recording endpoint accepts raw WAV rather than an OpenAI multipart upload, uses xi-api-key and returns asynchronous admission or cumulative SSE. Replace the transcription call with the Giggy Python or JavaScript quickstart above, convert the recording locally and consume the verified final text. For AssemblyAI recording transcription, replace transcriber.transcribe(audio) with transcriptions.transcribe and transcript.text with the result text. For live microphone audio, use the WebSocket workflow above.
Speaker labels, word timestamps, confidence, chapters, sentiment and redaction options have no equivalent in this API. Remove unsupported options; do not invent fields. For explicit lifecycle control use submit/get/result. After interruption with a known UUID, reconcile that operation rather than automatically resubmitting it.
AI coding agents and MCP
Giggy exposes a Streamable HTTP MCP server at https://giggy.ai/mcp. MCP supports public voice discovery, owned custom-voice discovery, speech generation, recorded-audio transcription, and durable generation reads. MCP is not a live microphone transport. The Giggy WebSocket STT API supports live microphone audio separately.
Voice-agent compatibility
LiveKit, Pipecat and Vapi can use the existing TTS compatibility integrations. The Giggy-maintained Pipecat adapter 0.3.3 supplies one-socket WebSocket STT and decode preparation with upstream Pipecat VAD. Native Giggy LiveKit provider publication has not been verified here; use the documented Giggy SDK, WebSocket or Pipecat workflow for live STT. The Vapi custom TTS webhook does not make Giggy a native Vapi transcriber. See the framework capability guide. These integrations do not establish an upstream provider listing. Use the published OpenAPI contract for supported formats and rates. Compatibility synthesis uses paid modes.
Developer tools and integrations
Choose the contract for your integration: OpenAPI defines REST fields; the installed Python or Node SDK reference defines method arguments, return types and deadlines; the connected MCP tools/list schema defines tool arguments and input bounds. REST options are not automatically SDK or MCP options.
For a failed request, start with HTTP errors. Retain the package version, mode, transport, sanitized status/error and generation UUID when known. Inspect that generation on the admitting origin before another submission; do not replay ambiguously admitted input. Keep keys, signed URLs, audio and transcript content out of diagnostic reports.
Current package pins: Python giggy 0.2.1 (Python 3.10+), Node @giggy-ai/sdk 0.2.1 (Node.js 22+), pipecat-giggy 0.3.3 (Python 3.11+, Pipecat 1.12.0), and n8n-nodes-giggy 0.1.1 for self-hosted voiceovers. See the verified package compatibility and task guide for the dated registry check, expected results, code-only prompts and client setup. Historical adapter versions are not current install recommendations.
For lower-cost Batch TTS or recorded STT, explicitly select Batch. Completed REST TTS delivery and SDK speech.create return audio bytes; asynchronous REST requires Prefer: respond-async, while MCP returns a generation UUID for status and result retrieval. Recording SDK transcribe returns a transcript object; read its text field. Raw recording REST/MCP requires durable transcript retrieval. Live microphone and Pipecat workflows use paid Streaming; respect readiness, real ordered PCM, stop and final verification. Pipecat limits captured utterances to 0.5–30 seconds including real pre-roll. MCP accepts completed recordings, not live PCM. Skill installation does not establish an MCP connection or directory approval. Keep per-user keys in secret stores, verify browser OAuth separately, and never run paid examples during code-only validation.
- Transcribe recordings with the Python SDK (giggy 0.2.1, Python 3.10+) or JavaScript/TypeScript SDK (@giggy-ai/sdk 0.2.1, Node.js 22+).
- Stream speech with the Node TTS example.
- Build voice agents with Pipecat TTS/live STT (adapter 0.3.3, Python 3.11+, Pipecat 1.12.0) or the existing LiveKit/Vapi TTS examples. Applications own transport, VAD and turn boundaries.
- Automate Batch/Fast voiceovers with n8n-nodes-giggy 0.1.1 in self-hosted n8n. Cloud verification is not established.
- Connect coding assistants through the remote MCP server and agent skill. Each user supplies their own API key; plugin directory approvals are separate.
- Explore TTS and recorded-STT Postman requests, Voice AI Essentials and AI-readable documentation.
OpenAPI 3.1 specification · Speech API documentation · Pricing
TTS voice-library languages
- English
- Abkhazian
- Afar
- Afrikaans
- Akan / Twi
- Albanian
- Ambo-Pasco Quechua
- Amharic
- Arabic
- Aragonese
- Armenian
- Assamese
- Aymara
- Azerbaijani
- Balinese
- Bambara
- Bashkir
- Basque
- Belarusian
- Bengali
- Bhojpuri
- Bislama
- Bodo
- Bosnian
- Breton
- Buginese
- Bulgarian
- Bunun
- Burmese
- Cantonese
- Catalan
- Cebuano
- Central Kurdish
- Central Pashto
- Central Tarahumara
- Chamorro
- Chavacano
- Chichewa / Nyanja
- Chiquián Ancash Quechua
- Chokwe
- Cornish
- Corsican
- Croatian
- Czech
- Dagbani
- Danish
- Dhivehi
- Dinka
- Dogri
- Dutch
- Dzongkha
- Eastern Mari
- Eastern Punjabi
- Erzya
- Esperanto
- Estonian
- Ewe
- Faroese
- Fijian
- Filipino
- Finnish
- Fon
- French
- Friulian
- Fula / Fulfulde
- Ga
- Galician
- Gan Chinese
- Ganda
- Georgian
- German
- Greek
- Greenlandic
- Guarani
- Gujarati
- Haitian Creole
- Hakha Chin
- Hakka Chinese
- Hausa
- Hawaiian
- Hebrew
- Hiligaynon
- Hindi
- Hiri Motu
- Hmong
- Hmong Daw
- Hungarian
- Icelandic
- Igbo
- Ilocano
- Indonesian
- Inuktitut
- Irish
- Italian
- Japanese
- Javanese
- Kabardian
- Kabyle
- Kamba
- Kannada
- Kanuri
- Kashmiri
- Kashubian
- Kazakh
- Khmer
- Kikongo
- Kikuyu
- Kinyarwanda
- Kirundi
- Konkani
- Korean
- Kyrgyz
- Ladino
- Lao
- Latgalian
- Latvian
- Laz
- Ligurian
- Limburgish
- Lingala
- Lithuanian
- Loja Highland Quichua
- Luba-Kasai
- Luo
- Luxembourg German / Moselle Franconian
- Luxembourgish
- Macedonian
- Maithili
- Malagasy
- Malay
- Malayalam
- Maltese
- Mandarin Chinese
- Manipuri / Meitei
- Maori
- Marathi
- Marshallese
- Meru
- Min Nan / Hokkien
- Mingrelian
- Mongolian
- Nepali
- Nigerian Pidgin
- Northern Kurdish
- Norwegian
- Norwegian Bokmål
- Norwegian Nynorsk
- Nuer
- Occitan
- Odia
- Oromo
- Palauan
- Pashto
- Persian
- Polish
- Portuguese
- Puno Quechua
- Quechua
- Rifian
- Romagnol / Emilian-Romagnol
- Romani
- Romanian
- Romansh
- Rombo
- Rukai
- Runyankole
- Russian
- Sakizaya
- Sami, Northern
- Samoan
- Sanskrit
- Santali
- Sardinian
- Scots
- Scottish Gaelic
- Serbian
- Sesotho
- Shona
- Sicilian
- Sidamo
- Silesian
- Sindhi
- Sinhala
- Slovak
- Slovenian
- Somali
- Sorbian
- Spanish
- Svan
- Swahili
- Swati
- Swedish
- Tachelhit
- Tahitian
- Tajik
- Tamasheq / Tuareg
- Tamazight
- Tamil
- Telugu
- Tetum
- Thai
- Tibetan
- Tigrinya
- Tok Pisin
- Toki Pona
- Tongan
- Tsonga
- Tswana
- Tulu
- Turkish
- Turkmen
- Ukrainian
- Upper Sorbian
- Urdu
- Uyghur
- Uzbek
- Venda
- Vietnamese
- Waray
- Welsh
- Western Frisian
- Western Mari
- Western Punjabi
- Wolaytta
- Wolof
- Wu Chinese
- Xhosa
- Xiang Chinese
- Yakut
- Yiddish
- Yoruba
- Zhuang
- Zulu