Building an Audio Research Notebook with Venice

Tools like NotebookLM changed what people expect from a pile of research. You add sources, you ask questions and get answers that point back at the material, and then you generate a conversation between two hosts that you can listen to on a walk. This guide builds that, in about two hundred lines of Python, on five Venice endpoints. Nothing is stored outside your machine except the requests themselves, and Venice does not retain those.

Run this notebook in Google Colab

Every step below as an executable notebook, with the overview playing inline. Nothing to install.

How It Works

Five endpoints, each doing one job:

Step	Endpoint	Why
Read a web page	`/augment/scrape`	Returns Markdown, not HTML you have to clean
Read a PDF or document	`/augment/text-parser`	One multipart upload, text back
Index the text	`/embeddings`	Lets you retrieve by meaning rather than keyword
Answer questions	`/chat/completions`	Grounded in retrieved passages, with citations
Speak the overview	`/audio/speech`	Two voices, one per host

The retrieval here is deliberately plain: vectors in a Python list, cosine similarity in a loop. That is the right amount of machinery for a few dozen sources and it keeps the moving parts visible. When you outgrow it, Building a Private RAG Bot covers the same pipeline with a real vector database and a re-ranking pass.

Setting Up

One dependency, and a key from the API settings page.

pip install requests
export VENICE_API_KEY="your-key-here"

Create notebook.py and start with the imports and configuration. The two lists at the bottom are the whole state of the notebook: sources records what you added, and chunks holds the searchable pieces.

import io
import json
import os
import re
import wave
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_API_KEY']}"}

EMBED_MODEL = "text-embedding-bge-m3"
TTS_MODEL = "tts-xai-v1"
HOSTS = {"Ana": "luna", "Marco": "orion"}

sources = []
chunks = []

HOSTS maps a host name to a voice. Both voices come from tts-xai-v1, and that matters: voices belong to models, and sending a voice from one family to a model from another is the most common first mistake with the speech endpoint.

Choosing a Model That Will Not Go Stale

Hardcoding a chat model into a project guarantees the project ages. Venice publishes which model currently holds each role through /models/traits, so you can ask for the current default instead of naming one.

def default_text_model():
    response = requests.get(
        f"{BASE_URL}/models/traits", headers=HEADERS, params={"type": "text"}, timeout=60
    )
    response.raise_for_status()
    return response.json()["data"]["default"]


CHAT_MODEL = default_text_model()


def chat(messages, **options):
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=HEADERS,
        json={"model": CHAT_MODEL, "messages": messages, **options},
        timeout=300,
    )
    response.raise_for_status()
    return response.json()["choices"][0]["message"]["content"]

Other traits are available if this notebook is not the shape you want. most_intelligent buys you a stronger model for the reasoning-heavy summarization, and default_reasoning gives you one that thinks in the open. See Models for the full list.

Adding Sources

A source is either a URL or a file on disk, and Venice has an endpoint for each. Both return plain text, which is the point: the rest of the notebook does not care where a source came from.

def read_url(url):
    response = requests.post(
        f"{BASE_URL}/augment/scrape", headers=HEADERS, json={"url": url}, timeout=180
    )
    response.raise_for_status()
    return response.json()["content"]


def read_file(path):
    with open(path, "rb") as handle:
        response = requests.post(
            f"{BASE_URL}/augment/text-parser",
            headers=HEADERS,
            files={"file": (Path(path).name, handle)},
            timeout=180,
        )
    response.raise_for_status()
    return response.json()["text"]

/augment/scrape returns Markdown rather than raw HTML, so there is no boilerplate stripping to write. /augment/text-parser accepts PDF, Word, Excel, and plain text up to 25 MB, and reports a token count alongside the text. Document Processing covers its options in full.

Chunking and Embedding

Embedding a whole document produces one vector that is an average of everything it says, which is too blunt to retrieve a specific claim. Splitting it produces vectors that each mean something. Split on paragraph boundaries rather than a fixed character count. A chunk that stops mid-sentence retrieves badly, because the embedding is of a fragment.

def split(text, limit=1200):
    """Pack paragraphs into chunks without cutting one in half."""
    packed, current = [], ""
    for para in re.split(r"\n\s*\n", text):
        para = para.strip()
        if not para:
            continue
        if current and len(current) + len(para) + 2 > limit:
            packed.append(current)
            current = para
        else:
            current = f"{current}\n\n{para}" if current else para
    if current:
        packed.append(current)
    return packed


def embed(texts):
    vectors = []
    for start in range(0, len(texts), 64):
        response = requests.post(
            f"{BASE_URL}/embeddings",
            headers=HEADERS,
            json={"model": EMBED_MODEL, "input": texts[start : start + 64]},
            timeout=180,
        )
        response.raise_for_status()
        vectors.extend(row["embedding"] for row in response.json()["data"])
    return vectors

embed batches because the endpoint takes a list, and one request for sixty-four chunks is far cheaper in wall time than sixty-four requests. text-embedding-bge-m3 returns 1024 dimensions and handles multilingual sources well. Adding a source is now read, split, embed, and record. The magnitude of each vector gets stored alongside it, because it never changes and recomputing it inside the similarity loop is wasted work.

def add_source(title, ref):
    text = read_url(ref) if ref.startswith("http") else read_file(ref)
    number = len(sources) + 1
    sources.append({"number": number, "title": title, "ref": ref})

    pieces = split(text)
    for piece, vector in zip(pieces, embed(pieces)):
        magnitude = sum(x * x for x in vector) ** 0.5
        chunks.append(
            {"source": number, "title": title, "text": piece,
             "vector": vector, "magnitude": magnitude}
        )
    print(f"[{number}] {title}: {len(text)} characters, {len(pieces)} chunks")

The number is what makes citation possible later. Every chunk remembers which source it came from, so an answer can point back at it.

Retrieving the Right Passages

Cosine similarity between the question vector and every chunk vector, sorted, top k. For a few thousand chunks this runs faster than the network call that produced the question vector.

def retrieve(question, k=6):
    query = embed([question])[0]
    query_magnitude = sum(x * x for x in query) ** 0.5

    def similarity(chunk):
        dot = sum(a * b for a, b in zip(query, chunk["vector"]))
        return dot / (query_magnitude * chunk["magnitude"])

    return sorted(chunks, key=similarity, reverse=True)[:k]

Answering with Citations

The difference between a grounded answer and a confident guess is entirely in the prompt. Two instructions do the work: answer only from the notes, and say so when the notes fall short. Without the second one a model will quietly fill the gap from memory, which is the failure mode you are trying to design out. Numbering the notes in the prompt gives the model a citation vocabulary. It writes [2], and you can resolve that back to a source.

def ask(question, k=6):
    hits = retrieve(question, k)
    notes = "\n\n".join(f"[{h['source']}] {h['title']}\n{h['text']}" for h in hits)
    answer = chat(
        [
            {"role": "system", "content": (
                "Answer only from the numbered notes. Cite every claim with the bracket number "
                "of the note it came from. If the notes do not answer the question, say so "
                "instead of filling the gap.")},
            {"role": "user", "content": f"Notes:\n\n{notes}\n\nQuestion: {question}"},
        ],
        temperature=0.2,
    )
    cited = sorted({int(n) for n in re.findall(r"\[(\d+)\]", answer)})
    return answer, [s for s in sources if s["number"] in cited]

Parsing the brackets back out is worth the one line. It tells you which sources actually carried the answer, which is how you notice that a source you thought was central never gets cited.

Writing the Overview Script

Here is where the notebook stops being a search box. A summary is something you read; an overview is something you listen to, and the two want different prose. Dialogue works better in audio because the turn-taking does the pacing for you, and a question from one host is a natural way to introduce the next idea. Three constraints matter, and all three come from the audio rather than the text:

No markdown, no URLs. A speech model reads https://docs.venice.ai one character at a time.
Spell out abbreviations. T E E the first time, not tee.
Vary turn length. Evenly sized turns sound like two people reading a list at each other.

Asking for JSON with a schema is what makes the result renderable. Free-form text would need parsing, and speaker labels are exactly the thing a model gets creative about. The enum on speaker means every turn maps to a voice you have.

DIALOGUE_SCHEMA = {
    "type": "json_schema",
    "json_schema": {
        "name": "dialogue",
        "strict": True,
        "schema": {
            "type": "object",
            "additionalProperties": False,
            "required": ["turns"],
            "properties": {
                "turns": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "additionalProperties": False,
                        "required": ["speaker", "text"],
                        "properties": {
                            "speaker": {"type": "string", "enum": list(HOSTS)},
                            "text": {"type": "string"},
                        },
                    },
                }
            },
        },
    },
}


def write_script(turns=16):
    """Ask a chat model for a two-host dialogue grounded in the sources."""
    spread = chunks[:: max(1, len(chunks) // 12)][:12]
    notes = "\n\n".join(f"{c['title']}\n{c['text']}" for c in spread)
    hosts = " and ".join(HOSTS)
    raw = chat(
        [
            {"role": "system", "content": (
                f"You write podcast dialogue for two hosts, {hosts}. Ground every statement in "
                "the supplied notes. Write for the ear: no markdown, no URLs, no bracket "
                "citations, no stage directions. Spell out abbreviations the first time they "
                "appear. Vary the length of turns. Open with a hook and close with a takeaway.")},
            {"role": "user", "content": f"Notes:\n\n{notes}\n\nWrite about {turns} turns."},
        ],
        temperature=0.7,
        response_format=DIALOGUE_SCHEMA,
    )
    return json.loads(raw)["turns"]

The overview covers the sources broadly rather than answering one question, so spread samples chunks across the whole collection instead of retrieving by similarity. Taking every nth chunk is crude and works well: it reaches the end of long documents, which taking the first twelve never would. Treat the turn count as a hint rather than an instruction. Asking for sixteen has produced anywhere from sixteen to twenty-eight here, depending on how much the sources have to say. If you need a hard ceiling, truncate turns before rendering rather than arguing with the prompt.

Rendering Two Voices into One Track

Each turn becomes one speech request, with the voice chosen by who is speaking.

def speak(turn):
    response = requests.post(
        f"{BASE_URL}/audio/speech",
        headers=HEADERS,
        json={"model": TTS_MODEL, "voice": HOSTS[turn["speaker"]],
              "input": turn["text"], "response_format": "wav"},
        timeout=300,
    )
    response.raise_for_status()
    with wave.open(io.BytesIO(response.content)) as clip:
        return clip.getparams(), clip.readframes(clip.getnframes())

Reading the frames out of each clip, rather than saving twenty files and stitching them afterwards, is what keeps the join clean. Concatenating encoded audio such as MP3 does not work reliably, because every file carries its own headers. Decoded frames are just samples, so joining them is appending bytes. Two details make the result sound intentional. The header for the output comes from the first clip rather than from constants, so the sample rate is always right for whichever model you chose. And a quarter second of silence between turns gives the ear a beat to register that the speaker changed. Without it the hosts talk over each other’s endings.

def audio_overview(turns, path="overview.wav", pause_seconds=0.25):
    with ThreadPoolExecutor(max_workers=4) as pool:
        rendered = list(pool.map(speak, turns))

    params = rendered[0][0]
    silence = b"\x00" * int(params.framerate * params.sampwidth * params.nchannels * pause_seconds)
    with wave.open(path, "wb") as out:
        out.setnchannels(params.nchannels)
        out.setsampwidth(params.sampwidth)
        out.setframerate(params.framerate)
        for position, (_, frames) in enumerate(rendered):
            if position:
                out.writeframes(silence)
            out.writeframes(frames)
    return path

pool.map preserves input order, so the turns come back in the order they were written no matter which finishes first. Four workers is a deliberate ceiling rather than a maximum: more concurrency will start returning 429s on lower tiers, and the job is already dominated by the longest single turn.

Running It

if __name__ == "__main__":
    add_source("Venice Privacy", "https://docs.venice.ai/overview/privacy")
    add_source("TEE and E2EE Models", "https://docs.venice.ai/guides/features/tee-e2ee-models")
    add_source("VVV and DIEM", "https://docs.venice.ai/overview/vvv-diem")

    answer, cited = ask("How does Venice keep my prompts private, and what do I give up?")
    print(answer)
    print("\nSources:", ", ".join(f"[{s['number']}] {s['title']}" for s in cited))

    turns = write_script()
    print(f"\nWriting {len(turns)} turns to overview.wav")
    audio_overview(turns)

python notebook.py

[1] Venice Privacy: 7507 characters, 7 chunks
[2] TEE and E2EE Models: 43859 characters, 40 chunks
[3] VVV and DIEM: 9609 characters, 11 chunks

Venice's privacy architecture is built around a proxy foundation. All requests pass
through Venice over HTTPS and are relayed to the model provider without Venice storing
your prompt or response content [1]. On top of that proxy, each model offers one of four
progressively stronger privacy modes [1]...

Sources: [1] Venice Privacy

Writing 23 turns to overview.wav

Ingesting and answering takes a few seconds. The audio is the slow part, and it varies with load: about six minutes of speech takes anywhere from half a minute to three minutes to render.

Making It Yours

The sources are the whole game. Everything downstream is bounded by what you put in. Scraped pages bring their navigation and footers along, which is harmless for answering but shows up in an overview as a host earnestly discussing a documentation index. If that happens, drop chunks below a length threshold or filter obvious furniture before embedding. Swap the voices. HOSTS is two entries in a dictionary. tts-xai-v1 ships twenty-six voices, and other families have their own; GET /models?type=tts lists voices per model. Two voices that contrast clearly are easier to follow than two that are merely different. Clone your own. Voice Cloning turns a short sample into a voice handle you can drop straight into HOSTS. Add a third participant. Nothing in the pipeline assumes two speakers except the schema enum. Adding an interviewer who only asks questions changes the feel considerably. Keep the script. Writing turns to a JSON file next to the audio costs two lines and saves a re-render every time you want to tweak one sentence.

Where to Go Next

Private RAG Bot

The same retrieval pipeline with a real vector database and re-ranking.

Cited Answers with Web Search

Find the sources automatically instead of naming them yourself.

Text-to-Speech

Reference for the speech endpoint, its voices, and streaming.

Document Processing

Everything the text parser accepts, and what it returns.

Run this notebook in Google Colab

​How It Works

​Setting Up

​Choosing a Model That Will Not Go Stale

​Adding Sources

​Chunking and Embedding

​Retrieving the Right Passages

​Answering with Citations

​Writing the Overview Script

​Rendering Two Voices into One Track

​Running It

​Making It Yours

​Where to Go Next