Quick Start

1. Create an account and get your API key

1. Create a developer account and verify your email. Your free trial minutes are added when you verify.
2. In your developer dashboard, create a project. A test and a production environment are created for you.
3. Create an API key with the scopes rooms:read, rooms:write and voice:token:create. Copy it immediately: the full key is shown only once.
4. Keep the key on your backend only (in a secret manager or an environment variable). Never put it in a mobile app, a website or a public repository.

2. Buy voice minutes

Open Buy minutes in your dashboard, choose a package and pay the invoice. The minutes are added to your balance once we verify the payment. One minute is one connected participant for one minute, and unused minutes never expire.

Your dashboard always shows the balance. When it reaches zero, new voice sessions are refused until you buy more.

3. Create a group and a room from your backend

Every request carries your key in the X-Specular-Key header. Base URL: https://specular.live/api/developer/v1

# 1) create a group
curl -X POST 'https://specular.live/api/developer/v1/groups' \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H 'X-Specular-Key: sp_test_REPLACE_WITH_SERVER_KEY' \
  -d '{"name":"My community"}'

# 2) create a room inside it (use the group uuid from step 1)
curl -X POST 'https://specular.live/api/developer/v1/groups/GROUP_UUID/rooms' \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H 'X-Specular-Key: sp_test_REPLACE_WITH_SERVER_KEY' \
  -d '{"name":"Support room"}'

You can also create groups and rooms by hand in the dashboard under Voice groups & rooms. Every group and room gets a permanent UUID.

4. Ask for a voice session (on your backend)

When one of your users wants to join a room, your backend requests a short-lived session and returns it to your app.

curl -X POST 'https://specular.live/api/developer/v1/voice/sessions' \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H 'X-Specular-Key: sp_test_REPLACE_WITH_SERVER_KEY' \
  -d '{
    "group_uuid": "GROUP_UUID",
    "room_uuid": "ROOM_UUID",
    "participant_id": "your-internal-user-123",
    "display_name": "Sara",
    "can_publish": true
  }'

The answer holds the tokens your app needs. Send only these to the app, never your API key:

{
  "session_id": "01...",
  "websocket_room_id": "dev.ENVIRONMENT_ID.ROOM_UUID",
  "expires_in_seconds": 900,
  "websocket_url": "wss://specular.live/voice-ws/developer/...",
  "websocket_token": "SHORT_LIVED_TOKEN",
  "media_url": "wss://specular.live/livekit",
  "media_token": "SHORT_LIVED_TOKEN"
}

Your participant_id is your own user id. It is hashed before it reaches our media servers.

5. Connect your Flutter app

dependencies:
  splive: ^2.0.1

import 'package:splive/splive.dart';

final sdk = SpliveSdk();

// 'session' is the JSON your backend returned in step 4.
await sdk.connectRoomSocket(
  websocketUrl: session['websocket_url'],
  roomId: session['websocket_room_id'],
  token: session['websocket_token'],
);

await sdk.connect(SpliveSessionConfig(
  serverUrl: session['media_url'],
  accessToken: session['media_token'],
  roomId: session['websocket_room_id'],
  userId: currentUserId,
  displayName: currentDisplayName,
));

await sdk.enableMicrophone();

When the user leaves, or the room closes, disconnect both connections:

await sdk.disconnectRoomSocket();
await sdk.disconnect();

Session tokens are short-lived (15 minutes by default). Ask your backend for a new one when it expires.

Errors you may see

• 401 the key is missing, wrong, expired or revoked.
• 403 the key does not have the voice:token:create scope.
• 402 developer_prepaid_balance_exhausted your minutes are used up. Buy more.
• 402 developer_subscription_required the account has no minutes yet. Verify your email to get the trial, or buy a package.
• 404 developer_group_not_found the group does not belong to this key's environment.
• 409 developer_room_not_open the room does not belong to that group or is closed.
• 429 developer_concurrency_limit_reached too many people are connected at once for this environment. Retry shortly.
• 503 developer_gateway_disabled voice sessions are not open on this platform yet.
• 503 developer_capacity_reached the platform is at capacity. Retry shortly.
• 502 developer_voice_gateway_unavailable temporary problem on our side. Retry after a few seconds.

Usage is measured by our servers from real connection events, so it cannot be changed from a client app.