Skip to main content

Quick Start Guide

This guide will help you get started with the Eyeson One View REST API in just a few minutes.

What You'll Learn​

  • How to obtain and use an API key
  • Creating your first video meeting
  • Understanding user types and access methods
  • Basic layout customization
  • Working with background and foreground layers

Prerequisites​

  • Basic understanding of REST APIs
  • A tool to make HTTP requests (curl, Postman, etc.)
  • An Eyeson account (or willingness to create one)

How to Obtain an Eyeson API Key​

To start your first meeting, you'll need an API Key and a terminal to run cURL commands.

You'll also learn to work with layouts and layers later.

To use the Eyeson API, you need an API key for authentication and access to Eyeson's video features. Here's how to get one:

Step 1: Register for an Eyeson Account

  1. Visit the Developer Portal
  2. Sign up for an account to access API key management

Step 2: Confirm your Email Address

  • Click the confirmation link in your signup email

Step 3: Access the Developer Portal

  1. Log in to the Eyeson Developer Portal
  2. Go to "Your API Project" or "Manage your projects"

Step 4: Create an API Project

  1. Click "Create New Project"
  2. Enter a name and description
  3. Your API key will be generated automatically

Step 5: Manage Your API Key

  • View, regenerate, or revoke your key anytime in the Project Management section
  • Use the "Manage" section to modify key settings

Step 6: Start Using Your API Key

  • Include the API key in your request headers: 
    Authorization: YOUR_API_KEY

Additional Notes

  • Free tier includes 1,000 minutes monthly for testing
  • Upgrade for additional usage/features
  • Never share your API key publicly

How to Start Your First Meeting​

With your API Key ready, you can create your first meeting room:

cURL to create meeting room
# Create a new Eyeson room with basic configurations
# - Uses standup as room ID
# - Creates user named John Doe
# - Disables SFU mode
# - Enables widescreen format (1280x720)
curl -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -d "id=standup" \
  -d "user[name]=John Doe" \
  -d "options[sfu_mode]=disabled" \
  -d "options[widescreen]=true" \
  "https://api.eyeson.team/rooms"

This creates a meeting room and returns a response. See Create a Room for all available options. The response includes an HTTP status code and JSON payload.

Required parameters:

  • API Key in Authorization header
  • Endpoint: https://api.eyeson.team/rooms
  • Room ID and username in payload
  • Optional settings like SFU mode and screen format
warning

MCU+ (Multipoint Control Unit) functionality, including layouts and layers, requires MCU mode to be active. By default, MCU mode activates automatically when more than two users join a meeting. Setting sfu_mode=disabled ensures MCU features remain accessible during single-user testing and development.

Response to the cURL request
Response Status: 201

{
  "access_key": "YOUR_ACCESS_KEY",
  "ready": false,
  "locked": false,
  "room": {
    "id": "standup",
    "name": "Scrum",
    "ready": true,
    "started_at": "2024-12-09T14:25:02.254Z",
    "shutdown": false,
    "guest_token": "YOUR_GUEST_TOKEN"
  },
  "team": {
    "name": "Scrum"
  },
  "user": {
    "id": "6756fdc1755694e70cb72c80",
    "room_id": "tryout",
    "name": "Bob",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/YOUR_ACCESS_KEY",
    "gui": "https://app.eyeson.team/?YOUR_ACCESS_KEY",
    "guest_join": "https://app.eyeson.team/?guest=YOUR_GUEST_TOKEN",
    "websocket": "https://api.eyeson.team/rt?access_key=YOUR_ACCESS_KEY"
  },
  "options": {
    "show_names": true,
    "show_label": true,
    "exit_url": null,
    "recording_available": true,
    "broadcast_available": true,
    "layout_available": true,
    "layout": "auto",
    "reaction_available": true,
    "suggest_guest_names": true,
    "lock_available": false,
    "kick_available": true,
    "sfu_mode": "disabled",
    "layout_users": null,
    "layout_name": null,
    "layout_map": null,
    "voice_activation": false,
    "custom_fields": {},
    "widescreen": true,
    "background_color": "#121212"
  },
  "playbacks": [],
  "presentation": null,
  "broadcasts": [],
  "recording": null,
  "snapshots": [],
  "waiting_list": [],
  "signaling": {
    "type": "sepp",
    "options": {
      "client_id": "6756fdc1755694e70cb72c80",
      "conf_id": "6756fdbe755694e70cb72c7f",
      "auth_token": "eyJhbGciOiJFUzM4NCJ9.eyJpc3MiOiJleWVzb24tY29tYXBpIiwiY2xpZW50X2lkIjoiNjc1NmZkYzE3NTU2OTRlNzBjYjcyYzgwIiwiZXhwIjoxNzMzNzU3OTA3LCJjb25mX2lkIjoiNjc1NmZkYmU3NTU2OTRlNzBjYjcyYzdmIn0.iGaL9KfAQF2D0p9SxdRodfo5vYfE37S2AV8Kyoz5xgnx7y3T8ToZTE-cct0Cg6YSdQNAjA9PyTE3PGxwcOKqEywkIAp2aEyqgP7Ajbeu-nAUwYcPUrCJjeZ4WxLfno0e",
      "endpoint": "wss://sig.eyeson.com/call",
      "stun_servers": [
        "stun:nuts.eyeson.com:3478"
      ],
      "turn_servers": [
        {
          "urls": [
            "turn:nuts.eyeson.com:3478",
            "turn:nuts.eyeson.com:3478?transport=tcp",
            "turns:nuts.eyeson.com:443?transport=tcp"
          ],
          "username": "1733840707:6756fdc1755694e70cb72c80",
          "password": "r66KgWNa9PQY0ObQDBsHuYRUS4Q="
        }
      ]
    }
  }
}

The response includes four important links:

  1. self: API endpoint for the room
  2. gui: Direct link to join the meeting
  3. guest_join: Shareable link for guests
  4. websocket: WebSocket connection endpoint
danger

The links[gui] is the host link and should be kept a secret as it can be used to start the meeting.

Users, Keys and Tokens​

The API supports three user types:

  1. API Key User
    Required for room management and server-side operations
info

API Key operations should be performed server-side for security, while access key operations are safe client-side

  1. Access Key User
    Used for standard meeting operations and layout control of a running meeting

  2. Guest User
    Temporary participant with limited meeting access via guest token

note

See users for detailed documentation

Layers​

The API supports multiple visual layers:

Working with Layers​

Available layer types:

  1. Background images (z-index: -1)
  2. Participant videos (z-index: 0)
  3. Overlay elements (z-index: 1)

Example:

curl -X POST \
  -d "url=https://docs.eyeson.com/img/overlay_example.png" \
  -d "z-index=1" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layers"

Layouts​

Layouts define the position and arrangement of video elements. The default options[layout] value is "auto", which adjusts based on participant count.

You can modify layouts via API:

cURL to use an existing layout
curl -X POST \
  -d "name=four" \
  -d "users[]=" \
  -d "users[]=$USER_ID" \
  -d "users[]=" \
  -d "users[]=" \
  -d "layout=auto" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

For custom layouts:

cURL to create a custom layout
curl -X POST \
  -d "name=custom-map" \
  -d "map=[[20, 80, 400, 400, \"auto\"],[440, 160, 400, 400, \"contain\"],[860, 240, 400, 400, \"cover\"]]" \
  -d "users[]=" \
  -d "users[]=$USER_ID" \
  -d "users[]=" \
  -d "layout=auto" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

Next Steps​

After mastering the basics:

Common Issues and Solutions​

API Key authorization not working​

Check Authorization header format – Bearer prefix not needed

Can't join meeting​

Verify ACCESS_KEY or GUEST_TOKEN validity

Layout not changing​

Ensure correct ACCESS_KEY and disabled SFU mode. Automatic SFU-to-MCU switching requires 2+ participants if the setting is not on disabled.

When switching the layout using layout=auto, you need to attach atleast one users[]= to the request for it to register properly.

Layers not showing​

Verify that the image URL access is public and SFU mode is disabled.

Images larger than the video resolution will throw an Error 400 BAD REQUEST. Read more about layers.