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

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

Uploaded recordings and live microphone input use different contracts
WorkflowInput and deliveryCompletion
Uploaded recording: Batch or FastCompleted WAV; HTTP 202 admission, then durable statusFetch canonical transcript after completed
Streaming an uploaded recordingCompleted WAV; cumulative transcript_chunk SSE revisions, up to 12 hoursReplace provisional text; reconcile the UUID and fetch the final result
Live microphone: StreamingOne 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 secondsValidate 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.

OpenAPI 3.1 specification · Speech API documentation · Pricing

TTS voice-library languages