# Giggy Speech API — Developer Reference

Giggy provides text-to-speech and speech-to-text APIs for developers building voice-enabled products. STT supports both uploaded recordings and live microphone audio over WebSocket.

Canonical documentation:
https://giggy.ai/docs/speech-api

Machine-readable API specification:
https://api.giggy.ai/v1/openapi.json

Current pricing:
https://giggy.ai/pricing

## Pricing and limits

Batch uses zero credits, subject to request, queue and rate limits. Paid TTS Fast rounds up to 10 credits per 20 Unicode code points; Streaming rounds up to 10 credits per 10 code points. At the Pro, Studio or Scale denomination, 1,000,000 TTS characters cost $5 Fast or $10 Streaming before per-request rounding. Each paid TTS request has a 10-credit minimum. Full submitted text, including spaces and punctuation, counts toward billing. The same character rates apply across supported languages; TTS is not billed by UTF-8 bytes or generated audio duration. Any audio-hour equivalent must state its character-per-hour assumption and varies by language, voice and speaking speed. Homepage and authenticated Playground previews retain their free preview exemption; paid requests and copied API examples use normal selected-mode pricing.

$10 buys 1,000,000 Pro credits, not 100,000. Pro, Studio and Scale provide 100,000 credits per $1. Starter: $3 for 261,300 credits; Creator: $6 for 552,600. STT Fast costs 4,000 credits per input audio hour ($0.04 with Pro/Studio/Scale); Streaming costs 8,000 ($0.08). Starter and Creator cost more per credit. STT charges ceil(validated audio milliseconds * hourly credits / 3600000) per request, so many short requests can cost more than aggregate estimates.

Voice Design and Voice Clone each cost 1,000 credits ($0.01 at the standard denomination); Vocal Separation costs 50,000 credits per input audio hour ($0.50). Credits are shared across services. Purchased credits expire one calendar year after purchase. Optional automatic recharge makes additional purchases. Personal monthly free grants top up to 10,000 rather than accumulate another 10,000; signup-month grants are not duplicated. Workspaces receive no Personal free grants.

Giggy Grants requires approval and qualifying purchases. It matches those purchases 1:1 up to a $10,000 lifetime allowance; matching credits are not cash and expire with the corresponding purchase.

## Speech to text

POST https://api.giggy.ai/v1/audio/transcriptions
Authentication: xi-api-key: $GIGGY_API_KEY

For completed recordings upload raw WAV with Content-Type: audio/wav. PCM16, mono, 16 kHz; minimum 0.5 seconds. Query mode=batch|fast|streaming (default fast), optional language and optional client_request_id UUID. Batch accepts up to 25 minutes, Fast and uploaded-recording Streaming up to 12 hours. Binary uploads accept 1,382,400,000 audio bytes plus 1 MiB headers/metadata; complete within 30 minutes without a 60-second idle gap. Legacy JSON source_audio_data_url requests are limited to 40 MiB and use options in the body.

Batch/Fast return HTTP 202 generation metadata. Poll GET /v1/generations/{generationUuid}; fetch the completed generation.result.url for transcript JSON containing text, languages, audio_duration_ms and model metadata. Uploaded-recording Streaming returns HTTP 200 text/event-stream with cumulative transcript_chunk text; replace previous text because early results can be revised.

Live STT default: connect from your server to wss://api.giggy.ai/v1/audio/transcriptions with Authorization: Bearer $GIGGY_API_KEY or xi-api-key in the WebSocket upgrade headers. Send {"type":"start","format":"raw","encoding":"LINEAR16","sampleRateHz":16000,"interimResults":true,"options":{"endpointing":"external"}}; optionally add language="en", or omit it for detection. Wait for generation_created and ready. Send headerless binary PCM16 LE mono on that same socket, then {"type":"stop"} after the real tail. Read transcription snapshots with replace=true, sequence, generation UUID and attempt; require is_final=true plus input_complete before publishing final text. Verify canonical completion and saved text/duration. Do not open an HTTPS request per audio frame. Jambonz may use sampleRateHz=8000 LINEAR16, converted continuously to canonical 16 kHz. Without external endpointing, the existing energy threshold and 650 ms silence rule delimit turns. Test background noise and quiet speech; unsupported hints reject explicitly.

Paid API live audio: 0.5 seconds to 12 hours; browser previews and the downloadable replay are capped at 30 seconds. Paid admission reserves 96,000 credits and refunds unused allocation on accepted-duration settlement. Start promptly after ready; input/idle watchdogs apply. Eight live contexts per controller; capacity/rate/credit limits may reject admission. A disconnect cancels unfinished owned work; never reconnect or replay ambiguous audio automatically. Existing HTTPS/SSE live clients remain supported explicitly, while uploaded-recording Streaming continues to use SSE. Keep each session on its admitting origin during deployment draining. Guide and runnable reference: https://giggy.ai/docs/speech-api#api-stt-low-latency and https://giggy.ai/examples/live-stt.zip.

## Dubbing availability

POST /v1/audio/dubbing is a V17 development feature requiring separate production qualification. It accepts single-speaker WAV PCM16 mono 16 kHz, 3–60 seconds, maximum 3 MiB, target_language and optional input_text/output_text. No alignment, background preservation or lip sync. Do not infer production availability from development documentation.

## Native REST API

Endpoint:

POST https://api.giggy.ai/v1/text-to-speech

Authentication:

xi-api-key: $GIGGY_API_KEY

Giggy supports three generation modes:

batch
fast
streaming

Batch generation uses zero credits.

TTS Batch accepts up to 1,250 characters per request; Fast and Streaming up to 20,000. Native REST and MCP default to Fast when mode is omitted. Batch/Fast return completed MP3; Streaming returns progressive PCM16 LE mono 24 kHz. See OpenAPI for transport-specific fields.

Fast and Streaming use the applicable credit-backed generation rules described in the current Giggy pricing documentation.

Use a voice UUID returned by Giggy voice discovery.

For exact request and response fields, validation limits, and supported output formats, consult:

https://api.giggy.ai/v1/openapi.json

## OpenAI-compatible TTS

Endpoint:

POST https://api.giggy.ai/v1/audio/speech

Authentication:

Authorization: Bearer $GIGGY_API_KEY

Use model:

giggyspeech

Supply a Giggy voice UUID.

The compatibility endpoint supports speech clients and voice-agent frameworks that can configure a custom OpenAI-compatible API base URL.

This compatibility path uses the applicable paid speech generation rules.

## Voice discovery

Public voices:

GET https://api.giggy.ai/v1/voices

Integration voice catalog:

GET https://api.giggy.ai/v1/integrations/voices

Custom voices owned by the authenticated API-key scope:

GET https://api.giggy.ai/v1/my-voices

## MCP

Remote MCP endpoint:

https://giggy.ai/mcp

Transport:

Streamable HTTP

Existing speech tools:

list_voices
list_my_voices
generate_speech
get_speech_generation

The production tools/list check on October 13, 2026 also returned transcribe_audio(source_audio_data_url, mode, optional language, optional idempotency_key). Read its current tool schema before invocation. The MCP transcribe_audio tool accepts completed WAV recordings and returns generation metadata; it does not accept live microphone input or return transcript SSE. For live microphone STT, use the WebSocket API described above. For MCP recordings, poll get_speech_generation and fetch the signed transcript URL. This discovery check establishes tool availability, not a new end-to-end MCP transcription qualification.

Recommended workflow:

1. Call list_voices or list_my_voices.
2. Select an authorized voice UUID.
3. Call generate_speech.
4. Save generation.generation_uuid.
5. Poll get_speech_generation while queued or processing.
6. On completion, use generation.result.url.

MCP returns generation metadata rather than live PCM audio bytes.

For progressive audio transport, use the native Streaming REST API.

## Voice-agent framework compatibility

LiveKit:

Giggy's OpenAI-compatible endpoint can be used with compatible LiveKit TTS configurations.

Pipecat:

A custom TTSService adapter can supply Giggy UUID voice identifiers where the framework's built-in OpenAI service restricts available voices.

Vapi:

Giggy supports a custom TTS webhook.

These are compatibility integrations. They do not imply native official provider listings.

## Sources of truth

Choose the reference for the surface you are implementing; a REST field does not automatically become an SDK option or MCP argument.

- REST request and response fields: https://api.giggy.ai/v1/openapi.json and https://giggy.ai/docs/api-reference.
- SDK method names, arguments, return types and deadlines: the installed package and its matching method reference, https://github.com/giggy-ai/giggy-python#transcription-method-reference or https://github.com/giggy-ai/giggy-js#transcription-method-reference. Server duration limits do not extend client deadlines.
- MCP arguments and input bounds: the connected tools/list schema. REST raw-WAV limits and privacy fields are not automatically exposed through MCP.
- Workflow and lifecycle explanation: https://giggy.ai/docs/speech-api. This AI-readable file summarizes those contracts; it does not add capabilities.

For HTTP failures use https://giggy.ai/docs/api-reference#api-errors. Before reporting an integration problem, retain the installed package version, chosen mode/transport, sanitized status/error and generation UUID when known. Check that generation on the admitting origin before considering another submission. Never include keys, signed result URLs, audio or transcript content in a diagnostic report.

Do not infer undocumented API features.

## Verified package compatibility

Registry metadata checked November 3, 2026; these are published versions, not claims that a microphone, hosted plugin, or customer deployment has been qualified. Check the linked package reference before upgrading an existing integration.

| Package | Published version | Runtime and workflow |
| --- | --- | --- |
| [Python `giggy`](https://pypi.org/pypi/giggy/0.2.1/json) | `0.2.1` | Python 3.10+; TTS, recorded STT and WebSocket live methods. Applications own capture and use the installed client's deadlines. |
| [JavaScript `@giggy-ai/sdk`](https://registry.npmjs.org/@giggy-ai%2fsdk/0.2.1) | `0.2.1` | Node.js 22+; TTS, recorded STT and WebSocket live methods. Keep the key server-side. |
| [`pipecat-giggy`](https://pypi.org/pypi/pipecat-giggy/0.3.3/json) | `0.3.3` | Python 3.11+, Pipecat 1.12.0; paid TTS/live STT, PCM16 mono 16 kHz input, 0.5–30 seconds per captured utterance including real pre-roll. Applications own transport and upstream VAD. |
| [`n8n-nodes-giggy`](https://registry.npmjs.org/n8n-nodes-giggy/0.1.1) | `0.1.1` | Self-hosted Batch/Fast TTS and voice discovery; this is not a live-STT transport or proof of n8n Cloud approval. |

Pinned SDK setup: `python -m pip install giggy==0.2.1` or `npm install @giggy-ai/sdk@0.2.1`. Pipecat setup: `python -m pip install pipecat-giggy==0.3.3`. Do not install or run examples merely because an agent reads this document. Package installation is separate from billing authorization.

The direct paid live API can accept up to 12 hours, but that does not extend the Pipecat adapter's per-utterance bounds, a browser preview's 30-second bound, or an installed SDK/example deadline. Older Pipecat 0.2.0 uses its earlier transport; the explicitly labelled 0.3.0/0.3.1 notes in the live guide are historical, not the current install recommendation. A newer release number alone does not establish compatibility with a particular application.

## Choose and verify an integration task

Read the current API reference and the installed package's method documentation before writing code. An MCP connection is needed to execute MCP tools, not to write a direct REST, SDK or WebSocket integration. Never substitute one transport silently after a failure.

| Task | Supported path and cost | Completion check |
| --- | --- | --- |
| First TTS sample: [Python](https://github.com/giggy-ai/giggy-python#generate-speech) / [Node](https://github.com/giggy-ai/giggy-js#generate-your-first-mp3) | Select a returned authorized voice UUID and explicitly choose free queued Batch. Respect request/queue limits. | REST completed delivery and SDK speech.create return audio bytes, not a JSON result URL. Save those bytes using the selected format. For asynchronous REST, request Prefer: respond-async; for MCP retain the returned UUID, poll to completed, then retrieve the audio result URL. |
| [First recorded transcript](https://giggy.ai/docs/speech-api#api-stt-developer-path) | Prepare the documented completed WAV input; explicitly choose free Batch in an SDK, REST or MCP. MCP input must follow its connected tool schema. | SDK transcribe returns a transcript object; read its text field. Raw REST/MCP returns admission metadata and requires durable status and signed transcript retrieval. Never assume a local path is readable remotely. |
| [Live microphone STT](https://giggy.ai/docs/speech-api#api-stt-low-latency) | Application capture to one server-owned WebSocket with real PCM; paid Streaming. Use the live guide and the installed SDK's live contract. MCP cannot transport this audio. | Wait for readiness, send ordered audio and explicit stop, validate final/input completion, and verify saved text/duration. Do not append cumulative revisions. |
| [Pipecat voice integration](https://giggy.ai/docs/speech-api#api-pipecat) | Install the pinned adapter, select the appropriate live or explicit-boundary service, and retain application-owned transport/VAD. Paid Streaming. | Preserve turn identities and order, drain final verification, and surface late errors. A WAV replay is not a hardware microphone qualification. |
| [MCP recorded transcription](https://giggy.ai/docs/speech-api#api-mcp) | Configure a supported client with its own API key, inspect transcribe_audio's schema, submit once and poll the same generation. Choose Batch unless paid mode is explicitly authorized. | Retrieve the canonical transcript after completion; do not replay an ambiguous submission or invent text. |

Result formats and failure checks:

- TTS SDK speech.create returns bytes; do not parse them as JSON. Native asynchronous TTS uses Prefer: respond-async, which the SDK create helpers do not expose as an option. Use the documented REST path deliberately when you need asynchronous admission; do not invent an SDK parameter.
- Recording SDK transcribe returns the final transcript object; recording REST/MCP returns admission metadata. Recorded SSE and SDK stream return cumulative revisions that require final reconciliation. Live WebSocket events and an SDK live iterator have different envelopes; follow the installed method, not a mixture of both contracts.
- The 0.2.1 Python live helper defaults to timeout=150 seconds; Node live defaults to timeoutMs=150000. These are client deadlines, not the direct server's maximum audio duration. Review capture length and the installed helper's timeout/signal support before choosing it for a long session.
- On 401/403 check the key, owning space and client configuration without exposing credentials. On admission 429 respect Retry-After; do not replay an ambiguously admitted request. Invalid WAV/PCM requires correcting the input format, not silently changing mode or provider. If a completed result URL expires, refresh owned metadata; retained metadata does not guarantee the content still exists.

Reusable code-only prompts:

- "Write a Giggy Batch TTS integration with a real voice ID and explicit Batch mode. For SDK completed delivery save the audio bytes; for MCP poll the UUID and retrieve its completed result URL. Check current docs; do not run generation."
- "Write a Giggy Batch transcription integration for an authorized WAV, with explicit Batch mode, final-text retrieval and bounded error handling. Do not upload audio or run requests."
- "Implement Giggy live microphone STT over the documented WebSocket protocol. Separate microphone capture from the server-side secret, respect readiness/stop/final verification, and show where paid usage begins. Write code only."
- "Adapt my Pipecat pipeline to the documented Giggy package version without changing my LLM, transport or VAD timing. Explain per-utterance bounds and final verification. Do not run the paid example."
- "Review my Giggy MCP client configuration with placeholders, identify missing setup and show the expected five tools. Do not reveal credentials or call generation tools."
- "Diagnose this sanitized Giggy error using the known generation UUID, installed package version and documented status/result lifecycle. Do not resubmit audio or switch providers."

## Agent installation and authentication

Use https://github.com/giggy-ai/giggy-mcp#install-for-ai-coding-agents for the existing skill and client configurations. Codex uses its environment-backed bearer token configuration; Claude Code, Cursor, VS Code and other supported clients have separate configuration examples. A successful skill install is not proof that MCP is connected, and a prepared plugin ZIP is not proof of marketplace approval.

The documented API-key path uses each user's own key from a server environment or client secret store. Do not paste keys into chat or checked-in configuration. Browser OAuth is a distinct flow: only describe it as working when the hosted endpoint and selected client have been verified together. Source OAuth code and historical portal sign-in are not that verification. Consult the repository's dated directory-status document rather than claiming an approval that has not been recorded.

First validate configuration and tool availability with read-only discovery. A free plan, an available key, or a package installation does not authorize paid Fast/Streaming inference. Respect the user's stated budget and any existing authorization; code-only and offline validation must not create live sessions.

## SDK workflows and learning

Official published SDKs: https://github.com/giggy-ai/giggy-python (Python giggy 0.2.1) and https://github.com/giggy-ai/giggy-js (Node @giggy-ai/sdk 0.2.1). Node 0.1.0 is TTS only. Requires Python 3.10+ or Node.js 22+. Keep keys server-side.

Developer tool chooser: https://giggy.ai/docs/speech-api#api-developer-tools. Pipecat: https://github.com/giggy-ai/pipecat-giggy (published 0.3.3, Python 3.11+, Pipecat 1.12.0, TTS/live STT; application-owned transport and VAD). n8n: https://github.com/giggy-ai/n8n-nodes-giggy (published 0.1.1, self-hosted Batch/Fast TTS and voice discovery; Cloud verification not established). MCP/agent skill: https://github.com/giggy-ai/giggy-mcp (TTS/recorded STT, not live microphone transport; plugin approvals separate). The existing REST Postman collection covers TTS and completed-recording STT; it is not a live microphone transport. Native Giggy LiveKit provider publication is not verified by this guide. Use the documented OpenAI-compatible LiveKit TTS example and configure STT separately.

transcriptions.transcribe submits a WAV once, polls durable status and fetches final transcript JSON with no credential forwarded to the artifact host. Defaults to free Batch and a 30-minute workflow deadline. Python timeout is seconds; Node timeoutMs is milliseconds. Node combines that deadline with the caller AbortSignal. Python stops waiting at its deadline while an in-flight blocking request may finish later. A recording deadline is not generation cancellation.

submit/get/result provide explicit lifecycle control. stream yields parsed cumulative uploaded-WAV events. live plus send_live_frame (Python) or sendLiveFrame (Node) expose paid ordered PCM input. Existing events: generation_created, microphone_ready, transcript_chunk, generation_updated. Exported SDK event types describe these payloads. Unknown named events are explicit contract errors. Closing an unfinished live stream cancels; closing uploaded-WAV SSE does not. Do not assume the public TTS cancellation route handles STT recordings.

After interruption retain and inspect the known UUID. No UUID means upload acceptance may be ambiguous; inspect History before resubmitting. No automatic retries or alternate providers are used. A completed generation with no result URL may have expired/deleted content. Refresh status with the owning key; do not log signed URLs or input tokens.

Complete recording and exported-call tutorials: https://github.com/giggy-ai/giggy-examples/tree/main/python/basic-tts#transcribe-a-recording and https://github.com/giggy-ai/giggy-examples/tree/main/node/basic-tts#transcribe-a-recording. Both existing executables support Batch/Fast/uploaded Streaming and final transcript output. Framework STT guide: https://github.com/giggy-ai/giggy-examples#stt-in-voice-agent-frameworks. Giggy's maintained Pipecat STT/TTS adapter is pipecat-giggy 0.3.3; upstream listings and LiveKit/Vapi STT availability must be checked separately.

AssemblyAI recording migration: convert media/URLs locally to PCM16 mono 16-kHz WAV; map transcribe to transcriptions.transcribe and final text. Speaker labels, word times, confidence, chapters, sentiment, redaction and keyterm options have no equivalent Giggy fields. Live sessions use the WebSocket protocol above; the reference replay has its own 30-second bound, separate from the paid API ceiling.

Giggy Academy: https://giggy.ai/academy/voice-ai-essentials — thirteen free voice AI lessons with optional activities, saved progress and completion certificates. Activities do not assess proficiency. Its production availability requires the existing Academy product schema and coordinated feature flags.

Legacy compatibility: https://giggy.ai/v1 remains supported for existing integrations with the same API keys, request formats, billing and generation history. Keep each operation on its admitting origin. Live STT uses wss://api.giggy.ai/v1/audio/transcriptions.

## Partner integrations

Guide: https://giggy.ai/docs/speech-api#api-partner-integrations
LiveKit: https://giggy.ai/docs/speech-api#api-livekit — OpenAI-compatible TTS with base_url=https://api.giggy.ai/v1, model=giggyspeech, voice UUID and PCM output. Supply your own STT/VAD/transport. Native Giggy provider publication is not verified by this guide; the supported example here uses OpenAI-compatible TTS.
Pipecat: https://giggy.ai/docs/speech-api#api-pipecat — Giggy-maintained pipecat-giggy TTS/live STT adapter. Released pipecat-giggy 0.3.3 uses V25 one-socket WebSocket STT with decode preparation, final input acknowledgements and fenced transcripts; tested Pipecat 1.12.0. Drain the lifecycle for durable saved-result verification. Earlier 0.2.0 retains its prior transport.
Jambonz: https://giggy.ai/docs/speech-api#api-jambonz — custom STT provider at wss://api.giggy.ai/v1/audio/transcriptions; Authorization: Bearer Giggy API key; start, binary mono 8 kHz LINEAR16, stop; transcription messages on the same socket. Giggy converts continuously to 16 kHz. Jambonz-style protocol tested; native media-server calls remain separate qualification. No Jambonz streaming TTS claim. Official contract: https://docs.jambonz.org/guides/features/custom-stt-providers.
These are compatibility integrations, not upstream listings or commercial partnership claims. Keep credentials server-side. Existing adapters and legacy API origin remain functional.