Start here
Guides for building with AraPulse, ordered by task. Endpoint-by-endpoint detail lives in the API reference.
From nothing to a live companion
Four steps, in the order that fails fastest — each one proves something before you build on it.
Create an account and a key
Sign up, open the dashboard and create an API key. Use a test key while you are developing — it is scoped separately from live traffic so you cannot accidentally spend production quota.
Make something speak
The fastest proof the integration works is a synthesis call: post text, get a WAV. No character, no session, no state. If that returns audio, your credentials and networking are correct.
Build a character
Generate a face or upload a reference, set the personality, and lock the appearance so it stays consistent. Clone a voice and bind it to that character.
Open a live session
Create a session server-side, mint a short-lived token, and hand that token to the browser. Your secret key stays on your server.
Her, on your page — via one token
The whole embed story is a credential hand-off: your server holds the key, the browser holds a token that expires on its own.
- Create the session server-side. The call that opens the WebRTC room authenticates with your secret key, so it can never come from a browser.
- Mint the token. A short-lived
st_token, listable and revocable from your server if you need to end it early. - Hand the browser the token, never the key. Everything the client does — chat turns, the live room — runs on that token alone.
- She publishes into the room. Delivery is WebRTC over LiveKit, and extra viewer tokens can be issued for the same room.
# 1 — Your server mints a short-lived browser token.
curl -X POST https://api.arapulse.com/api/v1/sessions/token \
-H "Authorization: Bearer sk_live_..."
# 2 — The browser talks with the token. The key stayed home.
curl https://api.arapulse.com/api/v1/avatars/abc/chat \
-H "Authorization: Bearer st_..."By what you are trying to do
Authentication and keys
Secret keys versus short-lived session tokens, which belongs where, and why a secret key must never be shipped to a browser.
In the API reference →Rate limits and quotas
How per-key limits and daily quotas are enforced, what a 429 means, and how to attribute usage across an organisation.
In the API reference →Live companion sessions
The turn pipeline, what each stage runs on, session length limits per plan, and how animation degrades when an engine is unavailable.
Read the overview →Voice cloning
What the engine needs from a reference clip, what is shipped through the dashboard, and which API path is still incomplete.
Read the overview →Speech synthesis
Three endpoints — complete file, chunked stream, and audio with word timings — and when each is the right one.
Read the overview →Transcription
Multipart and raw audio, the upstream health check, and why the stream endpoint is not incremental.
Read the overview →Embedding in your product
Server-side session creation, browser tokens, and delivering a companion over WebRTC into your own page.
Read the overview →Operating responsibly
Which compliance obligations are yours and which are ours, stated plainly — including the controls that are not built.
Read the split →
Task to endpoint
The call behind each common task. Full request and response detail is in the reference section each row links to.
| You want | Call | Reference |
|---|---|---|
| A complete spoken WAV | POST /api/v1/text-to-speech | Speech → |
| Audio with word timings | POST /api/v1/text-to-speech/with-timestamps | Speech → |
| A transcript | POST /api/v1/speech-to-text | Speech → |
| A cloned voice | POST /api/v1/voices | Voices → |
| A character | POST /api/v1/characters | Characters → |
| A live session | POST /api/v1/avatars | Live sessions → |
| A browser token | POST /api/v1/sessions/token | Keys and tokens → |
| Service health | GET /api/v1/status | Public → |
Gaps we are not pretending to have filled
These would each be their own guide. They are listed rather than linked, because a documentation index full of dead links is worse than a short one.
- Webhook consumption. The signing scheme is implemented and the events emit — the verification recipe lives in the API reference. A worked end-to-end guide is still unwritten.
- Self-hosted deployment. Running the whole stack in your own infrastructure is an Enterprise conversation today rather than a published runbook — talk to us and we will walk you through it directly.
- Client SDKs. There is no official SDK yet. The API is plain REST and works with any HTTP client; the examples in the reference use curl for that reason.
- Migrating from a hosted voice provider. Worth writing, not written.
If a guide you need is missing, ask. The gap list above is ordered by what people have actually run into, and it moves when someone tells us they are stuck.