Quickstart

The Sanas Console is where you manage everything outside your code — your account, projects, API keys, credit balance, and usage. The Sanas SDK is what runs in your code: you feed it interleaved float32 PCM frames and it returns processed frames — noise-cancelled, speech-enhanced, accent-converted, or translated into another language. This guide takes you all the way through: create an account and API key in the Console, install the SDK, process your first audio stream, then see that activity show up as usage and credit in the Console.

Info Time required: about 10 minutes. You need: a work email address you can receive mail at, and a supported Python interpreter. No credit card — new accounts start with $10.00 in free credit.

What you’ll build

An account — your top-level organization, identified by an Account ID.
A project — a workspace inside the account that owns API keys and reports its own usage.
An API key — the credential your SDK integration authenticates with.
A working integration — the SDK installed and processing your first audio stream.

Part 1 · Set up in the Console

Step 1 — Create your account

Go to console.sanas.ai. You’ll land on the Sanas Console sign-in screen. Select Sign up at the bottom to switch to account creation.

Create your account — Sanas Console signup Enter your work email and select Create account.

Enter the work email you want the account created under

Tip Prefer single sign-on? Sign up with Google creates the same account without a passcode step. The rest of this guide is identical either way.

Step 2 — Verify your email

Sanas signs you in with a one-time passcode instead of a password. Check your inbox for a 6-digit code and enter it, then select Verify.

Verify your email with the 6-digit passcode

Note The code is time-limited. If it lapses, use Resend Passcode — the link becomes available after the countdown finishes. Change lets you correct the address before requesting a new code.

Once verified, your account is created and you’re taken straight into the Console.

Step 3 — Check your free credit

New accounts land on Account & Billing — your prepaid credit wallet. Usage is metered per minute and drawn down from this balance in real time.

Account and Billing page showing a $10.00 available balance, free credit notice, auto-reload setting, monthly spend cap, per-product rate table, and billing history

Account & Billing — the prepaid credit wallet What’s on this page:

Section	What it tells you
Current balance	Credit available right now. New accounts start at $10.00.
Free credit notice	Your promotional credit and its expiry date.
Payment method	Add a card (handled by Stripe) to buy more credit and enable auto-reload.
Auto-reload	Off until a card is on file. Tops the wallet back up automatically.
Monthly spend cap	A safety limit for the account, independent of auto-reload — usage and top-ups pause once you reach it in a calendar month. Editable via the pencil icon.
Usage this month	Per-product rates, minutes consumed, and cost so far.
Billing history	Every credit purchase and top-up, with invoices on Stripe.

Info Free credit is enough to start developing immediately. You only need a card when you want to purchase additional credit.

Step 4 — Create your first project

Select Home in the left sidebar. On a brand-new account, the Create your first project dialog opens automatically.

Create your first project modal showing the parent account, a Project Name field, and a Select Timezone dropdown

The Create your first project dialog on a new account Fill in:

Project Name — string, required. A name you’ll recognize later, such as My First Project.
Select Timezone — string, required, defaults to (UTC) Universal. Utilisation and usage data are aggregated on this timezone and surfaced in the Reports section. Pick the timezone your team reads reports in.

Create your first project modal with a project name entered and timezone set

Project details filled in, ready to create Select Create Project.

Note Timezone affects how usage is bucketed into days in reports. Changing it later re-buckets how data is displayed, so choose deliberately up front.

Step 5 — You’re inside the project

Creating the project drops you straight into it. The left sidebar switches from account scope to project scope — note the Project ID under the project name, and the new project-only entries such as Sub Projects and API Keys.

Project dashboard showing the project name and Project ID in the sidebar, project-scoped navigation, a Create API Key button, an audio minutes chart, and Sanas feature cards

Project home — the sidebar is now scoped to the project

Tip Every project has its own Project ID (visible in the sidebar and under the dashboard heading, with a copy button). Keep it handy — it identifies the project in support conversations and reporting.

Step 6 — Create an API key

From the project dashboard, select Create API Key in the top right.

Create API Key modal with Name, optional Description, and an Expiry dropdown

The Create API Key dialog

Name — string, required. How the key appears in the keys list, for example Production Key.
Description — string, optional. Context — what the key is used by, and who owns it.
Expiry — enum, defaults to 30 days. One of 30 days, 90 days, 1 year, or No expiry.

Create API Key modal filled in with a name, description, and a 90 day expiry

A completed API key form Select Create API Key.

Tip Give each environment and each service its own key. Narrow keys are far easier to rotate or revoke than one shared key wired into everything.

Step 7 — Copy your key and store it somewhere safe

Warning This is the only time the full key is shown. Copy it now and store it in a secrets manager, your CI/CD secret store, or your team’s password manager before you close this dialog. Sanas cannot show it to you again — if you lose it, your only option is to create a replacement key and update every integration that used the old one.

Save Your API Key dialog showing the full key with a copy button and a warning that this is the only time the full key is shown

Save Your API Key — the one-time reveal Use the copy icon to grab the key, paste it into your secret store, then select Done.

Info Never commit an API key to source control, paste it into a ticket or chat, or ship it in client-side code. Load it from an environment variable or secret manager at runtime.

Your key now appears in the project’s API Keys list — permanently masked, showing only its status, expiry, creation date, and last-used timestamp.

API Keys list showing one active key with a masked value, expiry date, created date, and last used column

The API Keys list — the key is masked from here on Use the ⋮ menu on any row to edit or revoke a key. The Last used column is the quickest way to spot keys that are no longer in service and can be retired.

Part 2 · Integrate the SDK

With an API key in hand, switch from the Console to your code. The Python package ships as a self-contained wheel: everything the SDK needs is bundled inside it, so there’s no separate native library to install.

Note The SDK does not open microphones or speakers for you — you bring your own audio (from a file, socket, or media stream). You push frames in with process_frame and read processed frames back.

Step 8 — Download and install the SDK

Select Get SDK at the bottom of the sidebar. Choose your platform and download the SDK package. The same dialog links to the full SDK usage documentation.

Download SDK dialog with a platform selector, the SDK file name and size, a Download SDK button, and a View full documentation link

Get SDK — download the package for your platform

Before you begin — pick the right wheel

You only need a supported CPython interpreter and pip — no extra tooling required. The wheel in your archive targets the Python version named in its filename:

Python version	Wheel tag	Notes
3.10	`cp310-cp310`	version-specific
3.11	`cp311-cp311`	version-specific
3.12, 3.13, 3.14	`cp312-abi3`	one Stable-ABI wheel covers 3.12+

Tip Pick the archive whose <pytag> matches your interpreter (e.g. cp310 for Python 3.10; cp312 for Python 3.12 or newer).

Direct download links by platform

You can also download outside the Console:

OS	Architecture	Python	Download
Linux	x86_64	3.10–3.12+	Download
macOS	Apple Silicon (arm64)	3.10–3.12+	Download
Windows	x86_64	3.10–3.12+	Download

Archive layout

Your archive is laid out like this:

sanas-<version>-<pytag>-<os>-<arch>/
├── examples/                    # runnable examples + shared helpers
├── sanas-<version>-….whl        # the Python wheel (one, matching <pytag>)
└── USAGE.md

Create a virtual environment and install the wheel from inside the extracted archive directory. macOS / Linux

# With built-in python (use the python that matches the wheel tag)
python3.10 -m venv .venv
# ...or with uv (manages the Python version; --seed adds pip)
uv venv .venv --seed --python 3.10
. .venv/bin/activate
pip install --upgrade pip
pip install sanas-*.whl

Windows (PowerShell)

py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install (Get-ChildItem sanas-*.whl).FullName

Step 9 — Verify the installation

python -c "import sanas; print('sanas', sanas.__version__)"

Step 10 — Choose your capability and model

The SDK runs in one of two modes. The setup flow is identical — you always create_sdk → activate_api_key → create_audio_processor and wait for PipelineState.RUNNING — but how you select the mode and what you get back differ:

	Audio Processing	Language Translation (LT)
Selected by	a model key on `AudioAttributes.model_name` (e.g. `SE2.2`, `AT5.2`)	the presence of `lt_config`; `model_name` left empty
What it does	speech enhancement, noise cancellation, accent conversion	translates speech from one language to another
Returns	processed audio frames only	translated audio frames plus transcript segments (via the `lt_config` callback)
Extra config	none	`LanguageTranslationConfig(language_in, language_out, …)`
Latency	low (~tens of ms) — short tail drain	higher (~seconds) — drain with a longer silence window

For audio processing, set model_name to one of the model keys enabled for your account:

Category	Model keys
Agentic Speech Enhancement	`AGENTIC_ST_SE`, `AGENTIC_VI_GT_SE`, `AGENTIC_VI_G_SE`
Accent Translation (AT)	`AT5.2`
Speech Enhancement	`SE1.2`, `SE2.1`, `SE2.2`, `VI_G_SE`

Note This page covers Language Translation inside the Python SDK (selected via lt_config). Sanas also offers a standalone, browser-friendly Language Translation API (JavaScript client) for real-time speech-to-speech in the browser — use that instead of the SDK if you’re building a web app.

Step 11 — Process your first audio stream

Two things to understand before reading the code:

The pipeline initializes asynchronously. After you create a processor, wait for PipelineState.RUNNING (via the audio_pipeline_state_notify callback) before feeding frames.
process_frame is synchronous but expects real-time audio. Feed frames at the rate they would arrive live (one 20 ms frame every 20 ms). The snippets below pace with a monotonic-clock deadline so timing doesn’t drift.

The two sections below show the only difference between the modes: Audio Processing sets a model_name; Language Translation leaves it empty and passes an lt_config instead. Pass the API key you copied in Step 7 as YOUR_API_KEY.

Option A — Audio Processing

Create sdk_example.py and set model_name to one of your enabled model keys.

import array
import threading
import time
import sanas
from examples.wav_utils import read_wav, save_wav  # or copy these helpers

# 1. Create + activate (activation is synchronous and returns an SdkResult).
sdk = sanas.create_sdk(sanas.InitParams(storage_dir="./storage"))
res = sdk.activate_api_key("YOUR_API_KEY")
if not res.success:
    raise RuntimeError(f"activation failed ({res.error_type}): {res.message}")

# 2. Read input audio as interleaved float32.
float32_bytes, sample_rate, channels = read_wav("input.wav")
samples = array.array("f"); samples.frombytes(float32_bytes)

# 3. Get notified when the pipeline is ready. The state callback fires on a
#    background thread, so publish each state under a Condition and let the
#    main thread wait for a terminal state (RUNNING = go, NOT_RUNNING = failed).
cond = threading.Condition()
state = {"value": None}
def on_state(s):
    with cond:
        state["value"] = s
        cond.notify_all()

attrs = sanas.ProcessorAttributes(
    audio_attributes=sanas.AudioAttributes(
        sampling_rate=sample_rate,
        channels=channels,
        model_name="<your-model-key>",  # e.g. "AT5.2", "SE2.2", "VI_G_SE"
        audio_pipeline_state_notify=on_state,
    )
)

# 4. Feed 20 ms frames at real time; process_frame returns the processed frame.
frame_len = sample_rate * channels // 50  # samples in 20 ms
frame_period = 0.020  # seconds per frame
out_bytes = []
_terminal = (sanas.PipelineState.RUNNING, sanas.PipelineState.NOT_RUNNING)
with sdk.create_audio_processor(attrs) as proc:
    with cond:  # wait until the pipeline settles
        cond.wait_for(lambda: state["value"] in _terminal, timeout=30)
        if state["value"] != sanas.PipelineState.RUNNING:
            raise RuntimeError(f"pipeline did not start (state: {state['value']})")

    # `deadline` is the wall-clock time the NEXT frame should be sent.
    deadline = time.monotonic()
    for i in range(0, len(samples) - frame_len + 1, frame_len):
        frame = proc.process_frame(sanas.AudioFrame(samples=samples[i:i + frame_len]))
        if frame.frame_count:
            out_bytes.append(bytes(frame.samples))  # memoryview is transient; copy
        deadline += frame_period
        time.sleep(max(0.0, deadline - time.monotonic()))

    # Drain the buffered tail by pushing silence (still paced at real time).
    silence = array.array("f", bytes(frame_len * 4))
    for _ in range(10):
        frame = proc.process_frame(sanas.AudioFrame(samples=silence))
        if frame.frame_count:
            out_bytes.append(bytes(frame.samples))
        deadline += frame_period
        time.sleep(max(0.0, deadline - time.monotonic()))

save_wav("output.wav", b"".join(out_bytes), sample_rate, channels)

Tip examples/helpers.py provides PipelineWaiter, sleep_until, and feed_and_drain, which wrap steps 3–4 above — prefer them over hand-rolling the loop.

Option B — Language Translation

Language Translation is selected by the presence of lt_config (not by a model key), so leave model_name empty. Translated audio comes back from process_frame; transcripts arrive on the lt_config callback.

import array
import threading
import time
import sanas
from examples.wav_utils import read_wav, save_wav

sdk = sanas.create_sdk(sanas.InitParams(storage_dir="./storage"))
res = sdk.activate_api_key("YOUR_API_KEY")
if not res.success:
    raise RuntimeError(f"activation failed ({res.error_type}): {res.message}")

float32_bytes, sample_rate, channels = read_wav("input.wav")
samples = array.array("f"); samples.frombytes(float32_bytes)

def on_transcript(tf):
    kind = "Translation" if tf.type_ == sanas.TranscriptType.TRANSLATION else "Transcription"
    for seg in tf.transcript_data_.complete:
        print(f"[{kind}] {seg.text}")

cond = threading.Condition()
state = {"value": None}
def on_state(s):
    with cond:
        state["value"] = s
        cond.notify_all()

attrs = sanas.ProcessorAttributes(
    audio_attributes=sanas.AudioAttributes(
        sampling_rate=sample_rate,
        channels=channels,
        model_name="",  # LT is selected by lt_config, not a key
        audio_pipeline_state_notify=on_state,
    ),
    lt_config=sanas.LanguageTranslationConfig(
        language_in="en-US",
        language_out="es-ES",
        conversation_id="",  # optional; links two-party sessions
        callback=on_transcript,
    ),
)

frame_len = sample_rate * channels // 50  # samples in 20 ms
frame_period = 0.020  # seconds per frame
out_bytes = []
_terminal = (sanas.PipelineState.RUNNING, sanas.PipelineState.NOT_RUNNING)
with sdk.create_audio_processor(attrs) as proc:
    with cond:
        cond.wait_for(lambda: state["value"] in _terminal, timeout=30)
        if state["value"] != sanas.PipelineState.RUNNING:
            raise RuntimeError(f"pipeline did not start (state: {state['value']})")

    deadline = time.monotonic()
    for i in range(0, len(samples) - frame_len + 1, frame_len):
        frame = proc.process_frame(sanas.AudioFrame(samples=samples[i:i + frame_len]))
        if frame.frame_count:
            out_bytes.append(bytes(frame.samples))
        deadline += frame_period
        time.sleep(max(0.0, deadline - time.monotonic()))

    # Translation adds several seconds of latency, so keep pushing silence for a
    # few seconds after the input ends to pull back the translated tail.
    silence = array.array("f", bytes(frame_len * 4))
    for _ in range(int(5.0 / frame_period)):  # ~5 s of silence
        frame = proc.process_frame(sanas.AudioFrame(samples=silence))
        if frame.frame_count:
            out_bytes.append(bytes(frame.samples))
        deadline += frame_period
        time.sleep(max(0.0, deadline - time.monotonic()))

save_wav("translated.wav", b"".join(out_bytes), sample_rate, channels)

Note Because translation runs speech-to-text, translation, and text-to-speech end to end, it adds several seconds of latency. Keep the extended silence-drain loop (~5 s) so the translated tail is pulled back after your input ends — this is the main runtime difference from audio processing.

Tip Building for the browser instead of a Python backend? Use the standalone Language Translation API (JavaScript client) rather than the SDK path shown here.

Cloud inference tuning (optional)

When the SDK runs on cloud / remote inference (the default), you can pass a CloudInferencingParams on AudioAttributes.cloud_inferencing_params to tune the remote path. These parameters are only meaningful for cloud inference and are ignored for local inference. The field is optional — omit it to keep the defaults.

Field	Type	Default	Meaning
`use_pcm16`	`bool`	`False`	Negotiate L16 (raw 16-bit linear PCM) at the session sample rate instead of the rate-default codec. Preserves fidelity and avoids server-side transcoding, at the cost of more bandwidth.

cloud_params = sanas.CloudInferencingParams()
cloud_params.use_pcm16 = True  # opt into raw 16-bit linear PCM uplink
attrs = sanas.ProcessorAttributes(
    audio_attributes=sanas.AudioAttributes(
        sampling_rate=sample_rate,
        channels=channels,
        model_name="<your-model-key>",
        cloud_inferencing_params=cloud_params,  # optional; omit for defaults
        audio_pipeline_state_notify=on_state,
    )
)

Note Leave cloud_inferencing_params unset (or use_pcm16=False) unless you specifically need raw PCM uplink — the rate-default codec is the recommended default for most sessions.

Once the SDK is initialized with a valid key and a model, you can start running inference. Every stream you process is metered against the project that owns the key.

Step 12 — Run the examples

The examples/ folder is self-contained (standard-library helpers only, no numpy). With your venv active, set the required environment variables and run an example from inside the extracted archive:

export SANAS_API_KEY="your-key"
export SANAS_STORAGE_DIR=./storage         # SDK data + logs (created if missing)
export SANAS_INPUT_WAV=input.wav           # 16-bit PCM or 32-bit float WAV
python examples/sdk_example.py             # audio processing
python examples/language_translation_example.py   # language translation
python examples/multi_stream_example.py --streams 4   # concurrency benchmark

Note SANAS_STORAGE_DIR is where the SDK keeps its data and writes logs (under storage_dir/logs).

Part 3 · Monitor usage and manage the account

Step 13 — Switch between projects and your account

The Console has two scopes, and knowing how to move between them is the key to reading your data correctly.

Account scope — everything across all projects: total usage, the credit wallet, billing, team, and account settings.
Project scope — one project only: its API keys, sub projects, connected clients, and its own usage.

To switch, select the name card at the top of the sidebar. The account sits at the top of the dropdown, with its projects nested beneath it. Choose the account to go account-wide, or any project to scope down. The same switcher is available from the breadcrumb in the header.

Sidebar switcher expanded showing the account row with the project nested underneath, a project search field, and a Create Project button

The switcher — account on top, projects nested beneath

Tip The dropdown also holds Search Projects… and + Create Project, so this is the fastest way to add projects two and beyond — the automatic first-project dialog only appears once.

You can also browse every project from Projects in the account sidebar, which shows each project’s ID, API key count, connected clients, and creation date.

Projects list showing project name, Project ID, connected clients, API keys, users, and created date, with a Create Project button

The Projects list at account scope

Step 14 — Watch usage and credit move

Once inference is running through the SDK, the Console reflects it in two places.

Usage in the project

Open Usage inside the project to see only what that project’s keys processed — streams processed, audio minutes, and average stream duration, with charts over time. Filter by product and by date range.

Project Usage page showing 12 streams processed, 14 minutes of audio processed, and a 1m 11s average stream duration, above two time-series charts with a single-day spike

Project-scoped usage — 12 streams, 14 minutes of audio

Usage across the account

Now switch to the account using the sidebar switcher and open Usage there. Same metrics, aggregated across every project — this is the number to watch as you add projects.

Account-level Usage page showing aggregated streams processed, audio minutes processed, and average stream duration across all projects

Account-scoped usage, aggregated across all projects

Tip With a single project the two views match. Once you add projects, the account view is the only place the totals line up — a project view can never show you the whole bill.

Credit drawing down

Back on Account & Billing, the same activity shows up as money. Compare this with the fresh wallet in Step 3 — the balance has moved from

10.00** to **

9.76:

Current balance drops as minutes are processed.
Spent this cycle rises to match.
Usage this month breaks the spend out per product, at each product’s per-minute rate — here 14m 12s of audio costing $0.24 in total.

Account and Billing page showing a reduced balance of 9.76, 0.24 spent this cycle, and a usage table breaking 14m 12s of processing down across four products

The wallet after processing — balance down, spend broken out per product Because rates differ sharply per product, minutes alone don’t tell you the cost — the same two minutes cost $0.18 on Language Translation but under a cent on Cloud Speech Enhancement. Use the Cost column, not the Usage column, to see where your credit actually goes.

Info Usage is metered per minute and drawn down in real time, so a burst of inference is visible on both the Usage pages and the wallet shortly after it runs. Reporting is aggregated on the timezone you chose when creating the project.

Note Usage this month is scoped to the current calendar month, so it resets on the 1st while Current balance keeps falling across months. If the balance has dropped but this panel reads $0.00, the processing happened in an earlier period — widen the range on the Usage page to find it.

Warning When credits run out, the wallet status flips to Paused — paid usage stops until you add credits. Add a payment method and turn on auto-reload before you depend on Sanas in production, so a busy day can’t interrupt your service.

Signing back in

Return to console.sanas.ai any time. Enter your email, select Continue, and verify with a fresh passcode — or use Google if that’s how you signed up.

The Sanas Console sign-in screen

Key SDK types

InitParams, create_sdk, Sdk, AudioAttributes, ProcessorAttributes, AudioProcessor, AudioFrame, LanguageTranslationConfig, CloudInferencingParams, PipelineState, SdkResult.

Troubleshooting

The passcode never arrived

Check spam and any corporate mail filtering. Wait for the resend countdown to finish, then select Resend Passcode. Use Change to correct a typo in the address rather than requesting more codes to the wrong inbox.

I closed the dialog before copying my key

The full key is unrecoverable by design. Create a new key, update your integration, and revoke the old one from the ⋮ menu in the API Keys list.

The first-project dialog didn’t appear

It only opens automatically for accounts with no projects. Use Projects → Create Project, or + Create Project in the sidebar switcher.

I don’t see the API Keys entry

You’re at account scope. API keys belong to a project — select a project in the sidebar switcher, then choose API Keys.

`import sanas` fails or the wheel won’t install

Confirm the wheel tag matches your interpreter (cp310 for Python 3.10; cp312-abi3 for 3.12+). Install from inside the extracted archive so pip install sanas-*.whl resolves the bundled wheel, and make sure your venv is activated first.

The pipeline never reaches RUNNING

Activation and model selection are the usual causes. Check that activate_api_key returned success, that model_name is a key enabled for your account (or that lt_config is set for Language Translation), and that you waited on the audio_pipeline_state_notify callback before feeding frames.

My usage still reads zero

Confirm the date-range filter covers when you ran inference, and that you’re looking at the project whose key the SDK is using. Check at account scope to rule out having run against a different project. Usage is aggregated on the project’s configured timezone, so very recent activity may sit in the current day’s bucket.

Processing stopped unexpectedly

Check Account & Billing. If the status pill reads Paused, either credits ran out or the monthly spend cap was reached for the calendar month. Add credits to resume, or raise the cap with the pencil icon next to it.

Next steps

Process multiple streams — scale to multiple concurrent audio streams with a shared SDK instance.
Add your team — invite teammates from Team and give them access to the account or an individual project.
Add a payment method — put a card on file to purchase credit and enable auto-reload before free credit runs out.
Organize with sub projects — split a project into sub projects to separate environments or customers while keeping usage rolled up.

Need help?

Email Support — support@sanas.ai · Response time: 1 business day
Support Portal — raise a support ticket for urgent issues.

​Quickstart

​What you’ll build

​Part 1 · Set up in the Console

​Step 1 — Create your account

​Step 2 — Verify your email

​Step 3 — Check your free credit

​Step 4 — Create your first project

​Step 5 — You’re inside the project

​Step 6 — Create an API key

​Step 7 — Copy your key and store it somewhere safe

​Part 2 · Integrate the SDK

​Step 8 — Download and install the SDK

​Before you begin — pick the right wheel

​Direct download links by platform

​Archive layout

​Step 9 — Verify the installation

​Step 10 — Choose your capability and model

​Step 11 — Process your first audio stream

​Option A — Audio Processing

​Option B — Language Translation

​Cloud inference tuning (optional)

​Step 12 — Run the examples

​Part 3 · Monitor usage and manage the account

​Step 13 — Switch between projects and your account

​Step 14 — Watch usage and credit move

​Usage in the project

​Usage across the account

​Credit drawing down

​Signing back in

​Key SDK types

​Troubleshooting

​The passcode never arrived

​I closed the dialog before copying my key

​The first-project dialog didn’t appear

​I don’t see the API Keys entry

​import sanas fails or the wheel won’t install

​The pipeline never reaches RUNNING

​My usage still reads zero

​Processing stopped unexpectedly

​Next steps

​Need help?