Getting started
Get from zero to your first live video stream in under 5 minutes.
Get from zero to your first live video stream in under 5 minutes.
Using a coding agent? Connect it to Synento over MCP and it can do all of this for you, including proving the video works. See Connect your agent.
Prerequisites
- A Synento account (sign up free: 10,000 participant-minutes a month, no card)
- A server-side key: an
sk_live_API key from the dashboard, or anrk_live_restricted key (one project; enough for Options A and B, while the CLI in Option C takes ansk_live_key)
Option A: Use the SDK (recommended)
1. Install the packages
npm install @synento/node # server-side: create sessions, mint tokens
npm install @synento/client # browser: publish and receive live audio/videoReact applications can use @synento/react for hooks and
components, and @synento/player for embedded
replay.
2. Mint connection tokens on your server
Your API key is a server-side secret. It never goes to the browser. Instead, your backend creates a session for each call and exposes one small route that mints a short-lived connection token for the user asking to join it.
// app/api/synento/route.ts (Next.js App Router)
import { createSynentoClient, resolveWsUrl } from "@synento/node";
// An empty config reads SYNENTO_API_KEY and SYNENTO_API_URL from the environment.
const synento = createSynentoClient({});
export const dynamic = "force-dynamic"; // or the route is cached and serves a stale token
export async function POST(request: Request) {
// Authenticate your own user here before minting a token for them.
const { sessionId, userId } = await request.json();
const token = await synento.createConnectionToken(sessionId, { userId });
return Response.json({
token: token.accessToken,
wsUrl: resolveWsUrl({
apiBaseUrl: process.env.SYNENTO_API_URL ?? "https://api.synento.com",
requestOrigin: request.headers.get("origin"),
sessionId,
userId,
}),
});
}The session itself is created once per call, wherever your app decides a call exists, with the same client:
const session = await synento.createSession({ name: "Morning standup" });
// session.id is the sessionId the browsers send to the route aboveUse resolveWsUrl rather than assembling the URL yourself. It handles the
loopback-hostname case that otherwise makes local development fail in a way
that produces no error at all, just a call that never connects.
3. Join from the browser
import { SynentoRoom } from "@synento/client";
const sessionId = "…"; // the session id your server created
const room = new SynentoRoom({
userId: "alice",
// Re-invoked on every reconnect, so tokens rotate automatically.
getToken: async () => {
const res = await fetch("/api/synento", {
body: JSON.stringify({ sessionId, userId: "alice" }),
method: "POST",
});
return res.json(); // { wsUrl, token }
},
});
room.on("participantsChanged", (ids) => console.log("in the room:", ids));
// Run this from your Join button's click handler. Browsers only start sound
// inside a tap, so unlock first, before anything is awaited.
void room.unlockAudio();
// If the browser still refuses, offer a button that calls unlockAudio() again.
room.on("audioStateChanged", (state) => console.log("sound:", state)); // "playing" | "blocked"
// Whether your own mic reaches the call. Safari captures it only once sound
// was started from a click; on "blocked", the same button fixes it.
room.on("micStateChanged", (state) => console.log("mic:", state)); // "sending" | "muted" | "blocked" | …
await room.connect();
// Publish. The second argument is optional — pass your local preview element
// if you have one. A stream with no video tracks publishes audio only.
const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
await room.publishCamera(stream, previewVideoEl);Media travels as binary frames, not JSON. @synento/client handles the
framing, decoding and reconnection. Do not open a raw WebSocket and try to
JSON.parse messages off it.
Recording needs no code. The session's durable streams are the recording, so there is no start-recording call and no recording flag.
Video is HD by default. Cameras go out at up to 720p, 30 fps, in their own
shape. To show someone, call room.attachParticipant(id, canvas); the canvas
takes the size of their picture, so size it with CSS and choose object-fit: contain (whole picture) or cover (fill the tile). See
Video and audio quality to change the
resolution or bitrate.
4. See it running
demo.synento.com is a two-way call built on exactly these packages. Open it in two tabs and join the same session to see both sides.
Your own calls are recorded the moment they happen: open one under
Recordings in the dashboard to replay it, or read
GET /v1/sessions/{sessionId}/manifest to check that each participant's camera
(cam) and microphone (mic) tracks hold data.
Option B: Use HTTP API directly (cURL)
Every key belongs to one project, and sessions are created in that project. The project your account starts with is enough for this walkthrough.
1. Create a session
curl -X POST https://api.synento.com/v1/sessions \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"name": "Demo Session"}'The response's data.id is the session id used below.
2. Get a connection token
curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
-H "Authorization: Bearer sk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{"user_id": "viewer-1"}'The response's data.access_token is valid for an hour (expires_in is in
seconds). user_id is required: letters, digits, - and _.
3. Connect to WebSocket streaming
Once you have the access_token from step 2, open a WebSocket. Prefer sending
the token as a subprotocol, so it stays out of URLs and access logs:
wss://api.synento.com/ws?session={sessionId}&user_id=viewer-1
Sec-WebSocket-Protocol: synento.v1, synento.token.{accessToken}The query-string form (&access_token=...) is still accepted, but logs the
token.
What travels over that socket is binary, in a self-describing frame format,
not JSON. Unless you are implementing a client from scratch, use
@synento/client, which handles framing, codec
negotiation, decoding, backpressure and reconnection.
Option C: Use the CLI
# Login with your API key
npx @synento/cli login sk_live_xxxxx
# Create a session in your key's project (the project ID is shown in the dashboard)
npx @synento/cli create-session "Demo Session" -p {projectId}-p must be the project the key belongs to; a key cannot create sessions in
another project.
Option D: Let your coding agent do it
Connect your agent to Synento's MCP server and ask it to add video to your app:
claude mcp add --transport http synento https://api.synento.com/mcpOnce you approve it, the agent can mint a restricted key for your .env, write
the server route and the browser code above, and then check the recording with
verify_session to confirm camera and microphone actually arrived. See
Connect your agent for other clients and what you approve.
For agents has the same configs for Cursor,
VS Code and Codex, and prompts you can paste.
AI interview recorder is a complete small
app for the recorded 1:1 prompt.
Next steps
- Read Core concepts to understand the architecture
- Browse the full API reference
- Try the copy-paste examples in examples/, including the AI interview recorder
- Set up webhooks for event-driven workflows: Webhooks guide
Environment variables
| Variable | Description | Default |
|---|---|---|
SYNENTO_API_KEY | Secret key. Server-side only. Never expose it to a browser. | - |
SYNENTO_API_URL | Base URL of the Synento API. | https://api.synento.com |
SYNENTO_PROJECT_ID | Project to act on. Only needed for a credential that spans more than one project; a key identifies its own. | - |
All three are read automatically by createSynentoClient({}) for any option you
leave out.
Troubleshooting
WebSocket opens, then closes immediately
The server refuses a connection by closing it (code 1008) just after it
opens, not by failing the handshake. Check that:
- the token has not expired (tokens last an hour by default;
@synento/clientmints a new one on every reconnect) - the
sessionanduser_idin the URL match the ones the token was minted for SYNENTO_API_URL, if you set it, points at the same API that minted the token
Codes 4001 (call full), 4002 (account limit) and 4003 (replay allowance
used) are plan limits; @synento/client reports them instead of reconnecting.
"401 Unauthorized" on API calls
- Verify your key starts with
sk_live_(orrk_live_for a restricted key) - Check the header is
Authorization: Bearer <key>: the wordBearer, one space, then the key
Nothing to replay
- Read
GET /v1/sessions/{sessionId}/manifest: a participant whose media arrived hascam/mictracks with a non-nullstart_ts. An emptyparticipantslist means no media reached Synento. - The dashboard's Recordings list shows sessions that have ended.