Rabel API (beta)

Send the words from your speech-to-text. Bell sends its guesses at each turn's words before the speaker finishes, then the end of the turn.

Bell is a model behind Rabel's API that learns each of your agents' own callers. It runs on Rabel's servers: there is nothing to host and no GPU. It answers in about 30 to 40 ms, while the caller is still talking, so it adds nothing to your pipeline's wait. One key holds up to 50 conversations at once.

The Rabel API is in beta. The launch price: the first 10,000 minutes are free, then $5 for every 10,000 minutes. An account opened at the launch price keeps it for 12 months from sign-up.

Base address: https://api.rabellabs.com

Get an API key

Sign up with your email:

curl -X POST https://api.rabellabs.com/v1/signup   -H "Content-Type: application/json"   -d '{"email": "you@example.com"}'

It answers status 202, and one email comes with a link. Open the link: it answers {"email": "...", "key": "rabel_..."}. The key is shown once; keep it. The link works once and expires in 24 hours. Signing up again with the same email gives a new key and turns the old one off; your use stays with your email.

Or continue with Google: the Continue with Google button on the sign up page opens GET /v1/login/google in your browser. After Google's sign-in, an email with no account goes to the account page, which shows the key once, as the email's link does; an email that has an account is signed in instead. Your Google account's email is your account's email; nothing else of the Google account is kept.

Set RABEL_API_KEY as an environment variable, or put your key in place of YOUR_API_KEY in the snippets below.

The snippets

Each one downloads the sample turn's words (/v1/sample.json), sends them to Bell at their times as a speech-to-text sends them, and prints Bell's guesses and the end of the turn.

TypeScript (Node 22), node snippet.ts:

const API = "https://api.rabellabs.com";
const KEY = process.env.RABEL_API_KEY ?? "YOUR_API_KEY";

const sample = await (await fetch(`${API}/v1/sample.json`)).json();
const ids = new Set();

const ws = new WebSocket(`${API.replace("https", "wss")}/v1/conversation`);
ws.onopen = () => {
  ws.send(JSON.stringify({ key: KEY }));
  console.log("Connecting to Bell...");
};
ws.onmessage = async (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "guess") { ids.add(m.id); console.log("guess:", m.text); }
  if (m.type === "end_of_turn") {
    console.log("end of turn:", m.text, ids.has(m.guess_id) ? `(matched guess ${m.guess_id})` : "(no guess matched)");
    ws.close();
  }
  if (m.type === "error") console.log("error:", m.message);
  if (m.type === "ready") {
    let t = 0;
    for (const w of sample.words) { // the turn's words so far, each time your speech-to-text has new words
      await new Promise((r) => setTimeout(r, w.ms - t));
      t = w.ms;
      ws.send(JSON.stringify({ type: "heard", text: w.text }));
    }
    await new Promise((r) => setTimeout(r, 200));
    ws.send(JSON.stringify({ type: "end_of_turn", text: sample.final })); // its final words
  }
};

Python, pip install websockets, then python snippet.py:

import asyncio, json, os, urllib.request
import websockets

API = "https://api.rabellabs.com"
KEY = os.environ.get("RABEL_API_KEY", "YOUR_API_KEY")

async def main():
    sample = json.load(urllib.request.urlopen(urllib.request.Request(API + "/v1/sample.json", headers={"User-Agent": "rabel-api-snippet"})))
    async with websockets.connect(API.replace("https", "wss") + "/v1/conversation") as ws:
        await ws.send(json.dumps({"key": KEY}))
        print("Connecting to Bell...", flush=True)
        ids = set()

        async def send():
            t = 0
            for w in sample["words"]:  # the turn's words so far, each time your speech-to-text has new words
                await asyncio.sleep((w["ms"] - t) / 1000)
                t = w["ms"]
                await ws.send(json.dumps({"type": "heard", "text": w["text"]}))
            await asyncio.sleep(0.2)
            await ws.send(json.dumps({"type": "end_of_turn", "text": sample["final"]}))  # its final words

        async for msg in ws:
            m = json.loads(msg)
            if m["type"] == "ready":
                sender = asyncio.create_task(send())
            elif m["type"] == "guess":
                ids.add(m["id"])
                print("guess:", m["text"])
            elif m["type"] == "end_of_turn":
                print("end of turn:", m["text"], f"(matched guess {m['guess_id']})" if m["guess_id"] in ids else "(no guess matched)")
                break
            elif m["type"] == "error":
                print("error:", m["message"])

asyncio.run(main())

The same two files are in snippets/. More examples, with a speech-to-text of your own, starting a reply on Bell's guess, handling errors and a Pipecat agent, are in examples/EXAMPLES.md.

Your speech-to-text

Keep the speech-to-text you use, and send Bell its words. Bell needs them while the speaker is talking: the partial words, as they come.

heard is your speech-to-text's interim (partial) transcript, and end_of_turn is its final transcript.

The end of the turn stays your speech-to-text's: send end_of_turn when it says the speaker has finished.

Bell has been run with Deepgram's speech-to-text: its streaming speech-to-text, and Deepgram Flux in the Pipecat example (see examples/EXAMPLES.md).

A conversation

Open a WebSocket to /v1/conversation. Send the key first, either as the header Authorization: Bearer <key> or in the first text message (within 10 seconds).

The first message is the hello. Only key is required, and only when the header does not carry it:

{"type": "hello", "v": 2, "key": "<key>", "agent": "front-desk", "min_chance": 0.7, "learn": true}

A first message {"key": "<key>"} with no type is a hello with every field left out (the snippets above send that). With the key in the header and no hello within half a second, the conversation starts on the defaults; a hello sent later, before the first heard, is answered with a second ready.

The API answers with ready at once. Send words only after ready.

Messages in

All are JSON text messages. The API takes text only.

A conversation can hold several turns. To end it, close the socket once the last end_of_turn has come back. Fields the API does not know are ignored.

Messages out

All are JSON text messages.

guess and end_of_turn carry their turn's number as turn, from 0.

Learning

When a conversation closes, Bell learns from it for its agent: each turn's heard messages in order, and its final words. A turn is always guessed before it is learned from, and a conversation never learns from itself. A turn cut off by the close teaches nothing. Nothing is learned for demo-bank, or when the hello says "learn": false.

The sample

GET /v1/sample.json is a sample turn's words as a speech-to-text sends them: {"words": [{"ms", "text"}], "final"}. Each entry of words is the turn's words so far at ms milliseconds from the start; final is the turn's final words.

Your account and your use

To see your account without your key, sign in by email: POST /v1/login with {"email": "you@example.com"} answers status 202, and one email comes with a link that signs you in to your account page. The link works once and expires in 24 hours. It opens your account, your use, codes and buying credit for an hour; it cannot open a conversation. GET /v1/login/confirm?token=... answers {"email", "session", "expires_in_s"}; send the session as Authorization: Bearer <session> to the calls below.

Or sign in with Google: GET /v1/login/google, opened in your browser (the Continue with Google button on the log in page), signs you in to the same account page when your Google account's email has an account. The sign-in has to come back from Google within 10 minutes, in the browser that started it; a sign-in cancelled at Google or not finished goes back to the log in page.

To replace a lost key, sign in and make a new one: POST /v1/keys with the header Authorization: Bearer <session> answers {"key", "key_last4", "key_created"}. The key is shown only in this answer; your old key stops working at once. Signing up again with the same email also gives a new key.

Use is metered in seconds open: the time a conversation is open, from ready until the socket closes, by the second. It is not the time of the speech in it.

Your agents

All with the header Authorization: Bearer <key> (or a session).

{"calls": [{"turns": [{"heard": ["i would like", "i would like to reset"], "final": "I would like to reset my password."}]}]}

Each turn carries its heard messages, your speech-to-text's interim words in the order it sent them, and its final words. It answers {"agent", "calls_learned", "turns_learned", "calls_heard"}. At most 1,000 calls a request. A turn with no heard list, or a call whose heard lists are all empty, answers 400 needs_heard: teaching from final words alone is not offered yet.

Every account can use demo-bank; a DELETE or a POST to it answers 409 read_only_agent. An agent your account does not have answers 404 unknown_agent.

Limits and errors

On the WebSocket an error is the message {"type": "error", "status", "error", "message", "retry_after_s"}. The socket closes after it, except after a bad_message for a text message, when the conversation stays open. Over HTTP it is the status with {"error", "message"}.

status error when retry_after_s
401 bad_key The key is wrong. 0
402 no_seconds The free seconds and the credit of this key are used up. 0
429 key_at_once This key already has 50 conversations open. 1
529 out_of_capacity Out of capacity, contact us for more usage. 60
408 no_message No message for 3,600 s. The conversation is closed. 0
400 bad_message A binary frame: the API takes text, the words of your speech-to-text, not audio. The socket closes. 0
400 bad_message A hello with a bad agent, min_chance or learn. The socket closes. 0
400 bad_message A text message other than heard or end_of_turn with a text, or ping, or a text over 4,096 characters. The conversation stays open. 0
400 needs_heard POST /v1/agents/{agent}/calls: a turn without its heard messages.
403 not_your_agent GET /v1/agents/demo-bank/phrases: demo-bank's phrases are Rabel's.
404 unknown_agent /v1/agents/{agent}: your account has no such agent.
409 read_only_agent DELETE or POST to demo-bank.

POST /v1/signup answers 400 bad_email when the body has no email, and 429 too_many_signups after too many signups from one address in an hour. GET /v1/confirm answers 400 bad_link for a link that is wrong, used or expired.