From 32afa784b93a9434866523c269de8fdb0f97e348 Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:06:12 -0700 Subject: [PATCH 1/8] docs: add Telnyx integration page --- developer-guide/integrations/telnyx.mdx | 93 +++++++++++++++++++++++++ docs.json | 24 ++----- 2 files changed, 99 insertions(+), 18 deletions(-) create mode 100644 developer-guide/integrations/telnyx.mdx diff --git a/developer-guide/integrations/telnyx.mdx b/developer-guide/integrations/telnyx.mdx new file mode 100644 index 0000000..c36840b --- /dev/null +++ b/developer-guide/integrations/telnyx.mdx @@ -0,0 +1,93 @@ +--- +title: "Telnyx" +description: "Use Fish Audio voices for real-time and in-call text-to-speech with Telnyx" +icon: "phone" +--- + +[Telnyx](https://telnyx.com) is a carrier-owned global communications platform providing infrastructure for real-time agents — voice AI, SIP trunking, programmable voice, and messaging. Fish Audio is available on Telnyx as a hosted text-to-speech provider: you synthesize Fish Audio voices directly through the Telnyx API and play them in live phone calls via Call Control and TeXML, with no Fish Audio API key required. + +## Prerequisites + +- A [Telnyx account](https://telnyx.com/sign-up) with an API key + +## Voices + +Telnyx exposes a curated shortlist of voices from the [Fish Audio Voice Library](https://fish.audio/discovery) rather than accepting arbitrary voice IDs. Voices use the format `FishAudio..`, where the model is `s2.1-pro` (latest, default), `s2-pro`, or `s1`: + +```text +FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a +``` + +All curated voices are cross-lingual — any voice can speak any language present in the input text. On S2 models, you can also control delivery with inline emotion tags like `[happy]` or `[whispering]` — see [emotion control](/developer-guide/best-practices/emotion-control) for the full syntax. + +See the [Telnyx Fish Audio provider page](https://developers.telnyx.com/docs/voice/tts/providers/fishaudio) for the current voice roster, supported audio formats, and sample rates. + +## WebSocket streaming + +Stream text in and receive base64-encoded audio chunks in real time: + +```python +import asyncio +import json +import base64 +import websockets + +async def tts_stream(): + url = "wss://api.telnyx.com/v2/text-to-speech/speech?voice=FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a" + headers = {"Authorization": "Bearer YOUR_TELNYX_API_KEY"} + + async with websockets.connect(url, extra_headers=headers) as ws: + # 1. Handshake + await ws.send(json.dumps({"text": " "})) + + # 2. Send text + await ws.send(json.dumps({"text": "Hello from Fish Audio on Telnyx."})) + + # 3. Signal end of input + await ws.send(json.dumps({"text": ""})) + + # 4. Collect audio + audio_chunks = [] + async for message in ws: + data = json.loads(message) + + if data.get("error"): + print(f"Error: {data['error']}") + break + + if data.get("audio"): + audio_chunks.append(base64.b64decode(data["audio"])) + + if data.get("isFinal"): + break + + with open("output.mp3", "wb") as f: + for chunk in audio_chunks: + f.write(chunk) + +asyncio.run(tts_stream()) +``` + +## REST API + +Synthesize a complete utterance with a single HTTP request: + +```bash +curl --request POST \ + --url https://api.telnyx.com/v2/text-to-speech \ + --header 'Authorization: Bearer YOUR_TELNYX_API_KEY' \ + --header 'Content-Type: application/json' \ + --data '{ + "text": "Hello from Fish Audio on Telnyx.", + "voice": "FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a" + }' +``` + +The response streams back audio bytes. Set `output_type` to `base64_output` or `audio_id` for JSON responses instead. + +## Resources + +- [Telnyx Fish Audio provider reference](https://developers.telnyx.com/docs/voice/tts/providers/fishaudio) +- [Telnyx WebSocket streaming examples](https://developers.telnyx.com/docs/voice/tts/websocket-streaming/examples) +- [Telnyx REST API examples](https://developers.telnyx.com/docs/voice/tts/rest-api/examples) +- [Fish Audio Voice Library](https://fish.audio/discovery) diff --git a/docs.json b/docs.json index 5a77d63..bffea32 100644 --- a/docs.json +++ b/docs.json @@ -54,10 +54,7 @@ }, { "group": "Platform (Web App)", - "pages": [ - "overview/platform", - "overview/mcp" - ] + "pages": ["overview/platform", "overview/mcp"] }, { "group": "Models & Pricing", @@ -135,7 +132,8 @@ "pages": [ "developer-guide/integrations/pipecat", "developer-guide/integrations/livekit", - "developer-guide/integrations/n8n" + "developer-guide/integrations/n8n", + "developer-guide/integrations/telnyx" ] }, { @@ -202,9 +200,7 @@ { "group": "Voice Design", "icon": "wand-magic-sparkles", - "pages": [ - "api-reference/endpoint/openapi-v1/voice-design" - ] + "pages": ["api-reference/endpoint/openapi-v1/voice-design"] } ] }, @@ -234,9 +230,7 @@ { "group": "JavaScript SDK", "icon": "js", - "pages": [ - "api-reference/sdk/javascript/api-reference" - ] + "pages": ["api-reference/sdk/javascript/api-reference"] } ] } @@ -269,13 +263,7 @@ "drilldown": true }, "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity" - ] + "options": ["copy", "view", "chatgpt", "claude", "perplexity"] }, "fonts": { "family": "Onest" From ddad63257af5d6c5594f856c799683473d98f0ac Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:09:27 -0700 Subject: [PATCH 2/8] docs: use Telnyx logo mark as integration page icon --- developer-guide/integrations/telnyx.mdx | 2 +- images/telnyx-logo.svg | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 images/telnyx-logo.svg diff --git a/developer-guide/integrations/telnyx.mdx b/developer-guide/integrations/telnyx.mdx index c36840b..bbb9e70 100644 --- a/developer-guide/integrations/telnyx.mdx +++ b/developer-guide/integrations/telnyx.mdx @@ -1,7 +1,7 @@ --- title: "Telnyx" description: "Use Fish Audio voices for real-time and in-call text-to-speech with Telnyx" -icon: "phone" +icon: "/images/telnyx-logo.svg" --- [Telnyx](https://telnyx.com) is a carrier-owned global communications platform providing infrastructure for real-time agents — voice AI, SIP trunking, programmable voice, and messaging. Fish Audio is available on Telnyx as a hosted text-to-speech provider: you synthesize Fish Audio voices directly through the Telnyx API and play them in live phone calls via Call Control and TeXML, with no Fish Audio API key required. diff --git a/images/telnyx-logo.svg b/images/telnyx-logo.svg new file mode 100644 index 0000000..71a5ad0 --- /dev/null +++ b/images/telnyx-logo.svg @@ -0,0 +1 @@ + From 548892a8ca09e4a7d5b4e5c36172129e370d11dd Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:11:40 -0700 Subject: [PATCH 3/8] docs: use Telnyx brand green for integration icon --- images/telnyx-logo.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/images/telnyx-logo.svg b/images/telnyx-logo.svg index 71a5ad0..8ad393a 100644 --- a/images/telnyx-logo.svg +++ b/images/telnyx-logo.svg @@ -1 +1 @@ - + From e863c06891b5cf47b8373344c0cd1d9df362661b Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:15:30 -0700 Subject: [PATCH 4/8] docs: make Pipecat sidebar icon visible in dark mode --- developer-guide/integrations/pipecat.mdx | 2 +- images/pipecat-logo.svg | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 images/pipecat-logo.svg diff --git a/developer-guide/integrations/pipecat.mdx b/developer-guide/integrations/pipecat.mdx index 7fab0ec..6f01c5e 100644 --- a/developer-guide/integrations/pipecat.mdx +++ b/developer-guide/integrations/pipecat.mdx @@ -1,7 +1,7 @@ --- title: "Pipecat" description: "Build voice AI agents with Fish Audio and Pipecat" -icon: "/images/pipecat-logo.png" +icon: "/images/pipecat-logo.svg" --- import { AudioTranscript } from '/snippets/audio-transcript.jsx'; diff --git a/images/pipecat-logo.svg b/images/pipecat-logo.svg new file mode 100644 index 0000000..0794722 --- /dev/null +++ b/images/pipecat-logo.svg @@ -0,0 +1 @@ + From 31459358c2a30dea0c738ca40481d55ab61d5423 Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:22:17 -0700 Subject: [PATCH 5/8] docs: fix Telnyx snippets after live API testing --- developer-guide/integrations/telnyx.mdx | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/developer-guide/integrations/telnyx.mdx b/developer-guide/integrations/telnyx.mdx index bbb9e70..2a4d25b 100644 --- a/developer-guide/integrations/telnyx.mdx +++ b/developer-guide/integrations/telnyx.mdx @@ -36,9 +36,12 @@ async def tts_stream(): url = "wss://api.telnyx.com/v2/text-to-speech/speech?voice=FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a" headers = {"Authorization": "Bearer YOUR_TELNYX_API_KEY"} - async with websockets.connect(url, extra_headers=headers) as ws: + async with websockets.connect(url, additional_headers=headers) as ws: # 1. Handshake - await ws.send(json.dumps({"text": " "})) + await ws.send(json.dumps({ + "text": " ", + "voice_settings": {"format": "mp3", "sample_rate": 44100} + })) # 2. Send text await ws.send(json.dumps({"text": "Hello from Fish Audio on Telnyx."})) @@ -68,13 +71,15 @@ async def tts_stream(): asyncio.run(tts_stream()) ``` +The handshake requests MP3 output via `voice_settings`; without it, audio is delivered as raw PCM at 24 kHz. + ## REST API Synthesize a complete utterance with a single HTTP request: ```bash curl --request POST \ - --url https://api.telnyx.com/v2/text-to-speech \ + --url https://api.telnyx.com/v2/text-to-speech/speech \ --header 'Authorization: Bearer YOUR_TELNYX_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ From b24f88d129f8f0036fa811e3aa12bf3bd364006a Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:28:55 -0700 Subject: [PATCH 6/8] docs: restore docs.json formatting, keep only nav addition --- docs.json | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/docs.json b/docs.json index bffea32..3634568 100644 --- a/docs.json +++ b/docs.json @@ -54,7 +54,10 @@ }, { "group": "Platform (Web App)", - "pages": ["overview/platform", "overview/mcp"] + "pages": [ + "overview/platform", + "overview/mcp" + ] }, { "group": "Models & Pricing", @@ -200,7 +203,9 @@ { "group": "Voice Design", "icon": "wand-magic-sparkles", - "pages": ["api-reference/endpoint/openapi-v1/voice-design"] + "pages": [ + "api-reference/endpoint/openapi-v1/voice-design" + ] } ] }, @@ -230,7 +235,9 @@ { "group": "JavaScript SDK", "icon": "js", - "pages": ["api-reference/sdk/javascript/api-reference"] + "pages": [ + "api-reference/sdk/javascript/api-reference" + ] } ] } @@ -263,7 +270,13 @@ "drilldown": true }, "contextual": { - "options": ["copy", "view", "chatgpt", "claude", "perplexity"] + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity" + ] }, "fonts": { "family": "Onest" From 0466eec13eb4295c42265a398d75887cd4dd5d95 Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:32:19 -0700 Subject: [PATCH 7/8] chore: update OpenAPI schema --- api-reference/openapi.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 9cf16bc..ecd5c21 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -369,6 +369,10 @@ "title": "Credit", "type": "string" }, + "cumulative_top_up": { + "title": "Cumulative Top Up", + "type": "string" + }, "created_at": { "format": "date-time", "title": "Created At", @@ -400,6 +404,7 @@ "_id", "user_id", "credit", + "cumulative_top_up", "created_at", "updated_at", "has_phone_sha256" From 002c4f5b789563a85a3e47bc10c36084f069f643 Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Thu, 23 Jul 2026 14:37:40 -0700 Subject: [PATCH 8/8] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20webs?= =?UTF-8?q?ockets=20prereq,=20explicit=20MP3=20output=20in=20REST=20exampl?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- developer-guide/integrations/telnyx.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/developer-guide/integrations/telnyx.mdx b/developer-guide/integrations/telnyx.mdx index 2a4d25b..883e9cf 100644 --- a/developer-guide/integrations/telnyx.mdx +++ b/developer-guide/integrations/telnyx.mdx @@ -9,6 +9,7 @@ icon: "/images/telnyx-logo.svg" ## Prerequisites - A [Telnyx account](https://telnyx.com/sign-up) with an API key +- Python 3.9 or higher with `websockets` 14+ (`pip install websockets`) for the streaming example ## Voices @@ -84,8 +85,10 @@ curl --request POST \ --header 'Content-Type: application/json' \ --data '{ "text": "Hello from Fish Audio on Telnyx.", - "voice": "FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a" - }' + "voice": "FishAudio.s2.1-pro.933563129e564b19a115bedd57b7406a", + "voice_settings": {"format": "mp3", "sample_rate": 44100} + }' \ + --output output.mp3 ``` The response streams back audio bytes. Set `output_type` to `base64_output` or `audio_id` for JSON responses instead.