Loading API documentation
Endpoint: wss://fal.run/Kotoba-Technologies/kotoba-tts/v2/tts/ws
Playground: enter some text at https://fal.ai/models/kotoba-technologies/kotoba-tts/v2/tts to get a WAV file.
Overview: Open a WebSocket, send the text with the language and speaker, and receive audio chunks as synthesis proceeds. A set of preset Japanese voices is available.
Use cases
Technical specifications
language to ja.Example input
{"type": "open", "language": "ja", "speaker_id": "<preset id>", "format": "pcm16", "sample_rate": 24000}
{"type": "response.create", "text": "おはようございます。今日は水曜日です。"}Example output
{"type": "session.created", "format": "pcm16", "sample_rate": 24000, "channels": 1, "language": "ja", "speaker_id": "…"}
{"type": "response.created", "response": {"id": "…"}}
{"type": "audio.chunk", "response_id": "…", "audio": "<base64 pcm16>", "isFinal": false}
{"type": "audio.chunk", "response_id": "…", "audio": "<base64 pcm16>", "isFinal": true}Example (Python SDK)
import kotoba
client = kotoba.KotobaClient() # KOTOBA_API_KEY + KOTOBA_TTS_URL from the environment
# One result
audio = client.tts.synthesize("おはようございます。", language="ja")
audio.to_wav("hello.wav")
# Streamed playback
for pcm in client.tts.synthesize_stream("おはようございます。", language="ja"):
speaker.write(pcm)Pricing: $0.015 per 1,000 UTF-8 bytes of input text.
The kotoba-sdk package (PyPI, Python 3.10+, version 0.2.3 or newer) covers all four apps.
It sends the fal key with fal's Authorization: Key scheme automatically for fal.run URLs,
so use the fal key as the API key and point the per-route URLs at the apps.
pip install kotoba-sdk
export KOTOBA_API_KEY=<fal key>
export KOTOBA_ASR_REST_URL=https://fal.run/Kotoba-Technologies/kotoba-stt/v1
export KOTOBA_ASR_URL=wss://fal.run/Kotoba-Technologies/kotoba-streaming-stt/v1/realtime
export KOTOBA_TTS_URL=wss://fal.run/Kotoba-Technologies/kotoba-tts/v2/tts/ws
export KOTOBA_S2ST_URL=wss://fal.run/Kotoba-Technologies/kotoba-sts/v1/realtime_voiceAn app that has been idle may boot a GPU runner on the first request, which can take a few
minutes. Allow for that in the request timeout or retry the first request; the SDK's default
timeouts are 30 seconds for HTTP requests (KotobaClient(timeout=...)) and 15 seconds for the
WebSocket handshake.
Any WebSocket client works with this endpoint. The examples use ws for Node.js and websockets for Python.
npm install wsSet FAL_KEY as an environment variable in your runtime.
export FAL_KEY="YOUR_API_KEY"This endpoint speaks its own message protocol over a WebSocket. Open the connection with any WebSocket client and authenticate the upgrade with the Authorization: Key header. Browsers must not hold the API key: connect through your own server, which adds the header. The message protocol itself is documented in the model's About section.
import WebSocket from "ws";
// Keep the API key on your server; a browser connects through your
// own backend, which adds the header. Use the "ws" package: Node's
// global WebSocket ignores the headers option and the upgrade gets 401.
const ws = new WebSocket("wss://fal.run/kotoba-technologies/kotoba-tts/v2/tts/ws", {
headers: { Authorization: "Key " + process.env.FAL_KEY },
});
ws.on("open", () => {
// Send the app's first message here.
});
ws.on("message", (data, isBinary) => {
if (isBinary) return; // binary frame, e.g. audio
console.log(data.toString()); // the app's messages, shown as text
});
ws.on("error", console.error);The API uses an API Key for authentication. Read it from the FAL_KEY environment variable on your server and send it as the Authorization: Key <FAL_KEY> header on the WebSocket upgrade, as the real-time snippet above does.
When running code on the client-side (e.g. in a browser, mobile app or GUI applications), make sure to not expose your FAL_KEY. Instead, use a server-side proxy to make requests to the API. For more information, check out our server-side integration guide.
Some attributes in the API accept file URLs as input. Whenever that's the case you can pass your own URL or a Base64 data URI.
You can pass a Base64 data URI as a file input. The API will handle the file decoding for you. Keep in mind that for large files, this alternative although convenient can impact the request performance.
You can also pass your own URLs as long as they are publicly accessible. Be aware that some hosts might block cross-site requests, rate-limit, or consider the request as a bot.
We provide a convenient file storage that allows you to upload files and use them in your requests. You can upload files using the client API and use the returned URL in your requests.
import { fal } from "@fal-ai/client";
const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
const url = await fal.storage.upload(file);The client will auto-upload the file for you if you pass a binary object (e.g. File, Data).
Read more about file handling in our file upload guide.