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.

If you don't have an API Key, follow the instructions in the next section
If you already have an API Key, skip to How to start your first meeting

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

Visit the Developer Portal
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: Create an API Project

Go to the Developer Portal
Click "Create New Project"
Enter a name and description
Your API key will be generated automatically

Step 4: 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 5: Start Using Your API Key

Include the API key in your request headers:

Authorization: YOUR_API_KEY

note

Free tier includes 500 minutes for developing and testing
To upgrade for additional usage, contact us.
Never share your API key publicly! If you did you can regenerate it.

How to Start Your First Meeting

This diagram illustrates the hierarchical relationship between core Eyeson concepts and how a video meeting is created and structured.

Required parameters

API Key in Authorization header
Endpoint: https://api.eyeson.team/rooms
user[name] to create a user

Custom Options Example

id in this case it unique for this room
SFU mode is disabled, to show the MCU mode strenghts
Video format is set to widescreen=true, a more modern ratio

info

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.

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

cURL to create meeting room
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.

Example response to the cURL request
Response Status: 201

{
  "access_key": "HY4OGEJeoufkVO5mdJMwlbvc",
  "ready": false,
  "locked": false,
  "room": {
    "id": "standup",
    "name": "demo",
    "ready": true,
    "started_at": "2024-12-09T14:25:02.254Z",
    "shutdown": false,
    "guest_token": "yIgliEpQkf1W9wqoEjNlLpCp"
  },
  "team": {
    "name": "demo"
  },
  "user": {
    "id": "6756fdc1755694e70cb72c80",
    "room_id": "standup",
    "name": "John Doe",
    "avatar": null,
    "guest": false,
    "blocked": false,
    "ready": false
  },
  "links": {
    "self": "https://api.eyeson.team/rooms/HY4OGEJeoufkVO5mdJMwlbvc",
    "gui": "https://app.eyeson.team/?HY4OGEJeoufkVO5mdJMwlbvc",
    "guest_join": "https://app.eyeson.team/?guest=yIgliEpQkf1W9wqoEjNlLpCp",
    "websocket": "https://api.eyeson.team/rt?access_key=HY4OGEJeoufkVO5mdJMwlbvc"
  },
  "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": [],
  "image_sources": [],
  "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="
        }
      ]
    }
  }
}

note

The response includes four important links:

self: API endpoint for the room
gui: Direct link to join the meeting
guest_join: Shareable link for guests
websocket: WebSocket connection endpoint

warning

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:

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

Access Key User
Used for standard meeting operations and layout control of a running meeting
Guest User
Temporary participant with limited meeting access via guest token

info

See users for detailed documentation

Layers

The API supports multiple visual layers:

Working with layers

When adding visual information to the session, you can select the following layers:

Background images (z-index: -1)
Overlay images (z-index: 1)

A concrete example for this kind of request:

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 "layout=auto" \
  -d "name=four" \
  -d "users[]=" \
  -d "users[]=$USER_ID" \
  -d "users[]=" \
  -d "users[]=" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

info

Empty slots are filled with active participnats.

For custom layouts:

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

info

Empty slots are not filled with activite participants. The map content has to fit the selected resolution.

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.

When setting a layout with a custom map, you need to append the same amount of users[]= as the map slots.

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.

What You'll Learn​

Prerequisites​

How to Obtain an Eyeson API Key​

Step 1: Register for an Eyeson Account​

Step 2: Confirm your Email Address​

Step 3: Create an API Project​

Step 4: Manage Your API Key​

Step 5: Start Using Your API Key​

How to Start Your First Meeting​

Required parameters​

Custom Options Example​

Users, Keys and Tokens​

Layers​

Working with layers​

Layouts​

Next Steps​

Common Issues and Solutions​

API Key authorization not working​

Can't join meeting​

Layout not changing​

Layers not showing​

What You'll Learn

Prerequisites

How to Obtain an Eyeson API Key

Step 1: Register for an Eyeson Account

Step 2: Confirm your Email Address

Step 3: Create an API Project

Step 4: Manage Your API Key

Step 5: Start Using Your API Key

How to Start Your First Meeting

Required parameters

Custom Options Example

Users, Keys and Tokens

Layers

Working with layers

Layouts

Next Steps

Common Issues and Solutions

API Key authorization not working

Can't join meeting

Layout not changing

Layers not showing