Engine protocols

Your engine image selects the model. Requests use that model over HTTP, gRPC, or WebSocket. These interfaces apply to the standalone licensed deployment. The cloud API and legacy API container have their own contracts.

Protocol	Packaged engine address	Input	Output
HTTP	`http://localhost:8080/`	One JSON request with complete text	Streamed audio bytes
gRPC	`localhost:7463`, service `rime.TextToSpeech`	Complete text or a stream of text chunks	Protobuf audio messages
WebSocket	`ws://localhost:8080/ws`	One-shot or streaming contexts	JSON or protobuf event envelopes

The model image configures the ports above. Use those ports for the quickstart. A bare engine binary defaults to HTTP port 7464 and gRPC port 7463.

Caller authentication

Your gateway must authenticate callers and provide TLS for every exposed protocol. In offline-license mode, the engine authorizes synthesis through the mounted runtime license. HTTP and gRPC callers do not need to send the metering key or license with each request.

WebSocket still requires an Authorization upgrade header or an initial config.authorization message within ten seconds, even in offline-license mode. The engine skips validation of this value when it has a verified offline license. The field is required, but it provides no access control in this mode. For a private engine with a verified offline license, set config.authorization to an empty string. Keep the metering API key on the engine. Your gateway must authenticate callers. An empty value does not authenticate clients in other deployment modes.

HTTP

Send the complete text to POST /. You can also use its alias, POST /invocations. Set Content-Type: application/json and choose an audio format with Accept, such as audio/wav or audio/mpeg.

JSON field	Meaning
`text`	Required text to synthesize
`speaker`	Voice supported by the image, for example `luna`
`language`	BCP-47 language tag, for example `en`; `lang` is an alias
`samplingRate`	Requested output sample rate in Hz, subject to model support
`timeScaleFactor`	Duration multiplier; `1` preserves the generated duration
`splitStrategy`	`sentence` or `none`; incremental input is available through gRPC or WebSocket

Check the response Content-Type before you decode the audio.

For compatibility with existing HTTP clients, the engine also accepts audioFormat in the request body. Valid short values, such as wav or mp3, override Accept. If the field is absent or invalid, the engine uses Accept. Without either a valid body format or an Accept header, the request fails. Use Accept for new clients.

This request writes the WAV response to output.wav:

curl --fail-with-body http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/wav' \
  -d '{"text":"Hello from Rime.","speaker":"luna","language":"en"}' \
  -o output.wav

Read the response as audio bytes. The engine does not use the legacy audioContent.model_output JSON wrapper. Before audio starts, a failure can return an HTTP error. After audio starts, a failure aborts the response body. HTTP 200 alone is not proof that synthesis completed. Word timestamps are currently unavailable over all three standalone engine protocols.

gRPC

The engine exposes rime.TextToSpeech without gRPC reflection, so you need the schema to call it. Ask Rime for rime/text_to_speech.proto and its imports that match your image. Client generation also requires google/protobuf/duration.proto and google/rpc/status.proto, including their imports.

RPC	Behavior
`Synthesize`	Accepts one `SynthesisRequest`; streams `SynthesisResponseStream` messages
`SynthesizeStreaming`	Accepts a stream of `StreamingSynthesisRequest`; streams the same response messages
`NormalizeText`	Returns `normalizedSentences`
`GetSupportedLanguages`	Returns the image’s language tags
`GetSupportedSpeakers`	Lists Coda speakers; Mist returns `UNIMPLEMENTED`

With grpcurl installed and the schema bundle in ./rime-protos, this command sends complete text and prints the streamed response messages:

grpcurl -plaintext \
  -import-path ./rime-protos \
  -proto rime/text_to_speech.proto \
  -d '{"text":"Hello from Rime.","speaker":"luna","language":"en","audioParameters":{"audioFormat":"audio/wav"}}' \
  localhost:7463 rime.TextToSpeech/Synthesize

Keep -plaintext for the private local listener. Use TLS through your gateway. grpcurl prints JSON with base64 audio fields. A generated protobuf client receives those fields as bytes. Append the audio payloads in order to build the audio file. Writing whole protobuf messages would include data outside the audio payload. For incremental input, send one header followed by textChunk messages. Close the request side when you have sent all the text, then keep reading until the response stream completes. This example sends two complete sentences:

grpcurl -plaintext \
  -import-path ./rime-protos \
  -proto rime/text_to_speech.proto -d @ \
  localhost:7463 rime.TextToSpeech/SynthesizeStreaming <<'JSON'
{"header":{"speaker":"luna","language":"en","audioParameters":{"audioFormat":"audio/wav"}}}
{"textChunk":"Hello from Rime. "}
{"textChunk":"This is the second sentence."}
JSON

If your input arrives a token at a time, set header.splitStrategy to SPLIT_STRATEGY_ACCUMULATE_SENTENCE. The engine collects text into sentences before synthesis. The selected image still determines model-specific synthesis behavior. Check the final RPC status. Anything other than OK means synthesis is incomplete. Cancel the RPC to stop generation. The schema defines timestamp fields and a response trailer, but the standalone engine currently sends only audio messages. Setting timestamps.enable has no effect.

WebSocket

Open /ws on the engine’s HTTP port. Offer rime.v1.json for JSON text responses or rime.v1.binary for protobuf binary responses. The engine defaults to JSON if you omit the subprotocol. Both encodings use WebSocketRequest and WebSocketResponse from the gRPC schema bundle. Each frame contains one message envelope. JSON uses camelCase fields and base64 audio values. Binary frames contain protobuf envelopes. With either encoding, extract the audio payload before you write it to an audio file.

Client message	Action
`config`	Set connection credentials or defaults once, before the first `start`
`start` with non-empty `text`	Synthesize the complete text; no `end` needed
`start` with empty `text`	Open a streaming context
`text`	Append input to that streaming context
`end: {}`	Finish input; continue reading until `done`
`cancel: {}`	Cancel the context; expect `cancelled`

Wait for ready before you send start. For each context, the server sends started, zero or more audio messages, then done, cancelled, or error. Match responses by contextId. An error with an empty context ID applies to the connection. You can keep the connection open for later contexts. Save this example as stream.mjs and run it with Node.js 22 or later against a private engine with a verified offline license. It sends an empty authorization value and needs no metering API key. Running node stream.mjs writes output.wav only after the engine sends done:

import { writeFileSync } from "node:fs";

const socket = new WebSocket("ws://localhost:8080/ws", "rime.v1.json");
const chunks = [];
let completed = false;
let errorReported = false;
const send = (message) => socket.send(JSON.stringify(message));

socket.addEventListener("open", () => {
  // A verified offline license permits an empty authorization value.
  send({ config: { authorization: "" } });
});

socket.addEventListener("message", ({ data }) => {
  const message = JSON.parse(data);
  if (message.error) {
    console.error(message.error);
    errorReported = true;
    process.exitCode = 1;
    socket.close();
    return;
  }
  if (message.ready) {
    send({ contextId: "example", start: {
      text: "", speaker: "luna", language: "en",
      audioParameters: { audioFormat: "audio/wav" },
    } });
    send({ contextId: "example", text: "Hello from Rime. " });
    send({ contextId: "example", text: "This is the second sentence." });
    send({ contextId: "example", end: {} });
  }
  if (message.contextId !== "example") return;
  if (message.audio) chunks.push(Buffer.from(message.audio, "base64"));
  if (message.done) {
    writeFileSync("output.wav", Buffer.concat(chunks));
    completed = true;
    socket.close();
  }
  if (message.cancelled) socket.close();
});

socket.addEventListener("error", () => { process.exitCode = 1; });
socket.addEventListener("close", () => {
  if (!completed) {
    if (!errorReported) console.error("Synthesis ended before done");
    process.exitCode = 1;
  }
});

If your input arrives a token at a time, set start.splitStrategy to SPLIT_STRATEGY_ACCUMULATE_SENTENCE. Wait for done to confirm that all audio has arrived. This event does not currently include timestamp spans. Migration from the API container’s WebSocket ports requires changes to your client’s messages. Move synthesis parameters from the old query parameters into start. Replace flush, clear, and eos with the context lifecycle above. Use end to finish input and cancel to stop a context. Decode the audio payload from each envelope. For language support, read the languages in ready and test the voices in your image. The old API container’s port-specific restrictions do not define this protocol.

Routing, health, and failures

Route traffic using HTTP or gRPC health checks. Your gateway must support HTTP/2 gRPC and WebSocket upgrades. Set its timeouts to allow streams to stay open for the duration your application needs. All three protocols share one inference capacity limit. At that limit, or during request drain, the engine refuses new synthesis. It returns gRPC UNAVAILABLE, HTTP 503, or a WebSocket error with kind unavailable. Before you retry, check whether the client already received audio. Retry with backoff only if your application can avoid playing that audio again. See Load balancing for stream routing and shutdown.

Overview

Quickstart

Voice agents

Voices & models

Customizing speech

Streaming & performance

Integrations

On-prem

Account & updates

Caller authentication

HTTP

gRPC

WebSocket

Routing, health, and failures

​Caller authentication

​HTTP

​gRPC

​WebSocket

​Routing, health, and failures

Caller authentication

HTTP

gRPC

WebSocket

Routing, health, and failures