How to Use Cloud API
To use the Cloud API, you must obtain a Service Provider ID and an API Key.
This section explains how to obtain them.
Cloud API is only available in the US and EU.
Japan only provides the Control & Monitoring API.
Obtaining Service Provider ID and API Key
Before you can start using the Cloud API, certain information must be pre-registered on Sony’s server. Please submit the following details to your Sony representative using secure methods, such as password-protected emails or closed-space chat platforms:
- Webhook URL
It must be an HTTPS URL with an official server certificate. Once provisioning is complete, the Token is sent to the specified Webhook URL. - APKs to be installed on the monitor
You can install up to three APKs. - Monitor configuration settings list
Click here for the setting specifications.
Tips
When using Sony’s Device Provisioning Tool or Remote Device Manager, APK applications and monitor settings lists are not required. The availability of these tools varies by region, so please confirm at the time of application.
Once Sony receives and validates the information you provided, it will be registered on the dedicated server. Your Sony representative will then provide you with the following Cloud API access credentials:
- Service Provider ID
An ID assigned when using the Cloud API. - API Key
A Key required to access the Cloud API. - API Base URL
The base URL of the endpoint.
Implementation Steps
After connecting the computer and monitor to the Internet, follow the steps below.
Japan does not support Provisioning API. Please see the Control & Monitoring API procedure here.
1. Preparing Registration Information
Gather the following information required for the registration process:
Monitor MAC Address
This information is located on the carton (packaging box) label.
Creating User Data
Optional supplementary information to identify the monitor, such as the tenant name at the installation location.
Cloud API Access Credentials
Credentials provided by your Sony representative after dedicated server registration.
2. Obtaining Device ID
Include the Service Provider ID and API Key in the HTTP header and send a request to the API endpoint to connect to the dedicated server. When you request the MAC address and User data to the “Register a device” API, a Device ID is generated.
curl -i ^
https://[Cloud API endpoint]/kitting/v1/devices^
-H 'Content-Type: application/json’^
-H 'X-API-Key:~’^
-d '{"mac":"AA-BB-CC-DD-EE-FF", "userData":“~" }’^3. Connect the monitor to the LAN
Connect using wired LAN.
Note
If the monitor has already been used, execute [Factory Set] in the Monitor settings.
Procedure: [Settings]→[System]→[About]→[Reset]→Factory data reset]
The monitor will restart automatically.
4. Dedicated Server Authentication with One Time Code
When the monitor starts, a One-Time Code (6-digit code and 2D barcode) is displayed after a few seconds.
The One-Time Code is valid for approximately 30 minutes.
Send the 6-digit code to the dedicated server using the “Input an one time code” API.
5. Automatically Starting the Monitor Setup
Once the dedicated server authenticates the One-Time Code, the monitor setup automatically begins based on the previously provided information. This process may take tens of minutes.
6. Setup Completion Notification to Webhook URL
Once setup is complete, a Token will be posted to the Webhook URL you provided previously. The Token is valid for approximately one hour.
7. Verifying Setup Completion
Send the Token using “Get Device events” to confirm the Device ID and User data of the monitor that has completed setup.
Tips
To use Sony’s original applications such as a Device Provisioning Tool or a Remote Device Manager without using the Provisioning API, complete the following steps before implementing the Control & Monitoring API.
Setup Completion Notification and Confirmation
After the monitor automatically completes setup, a Token will be posted to the Webhook URL you provided to Sony. Send the Token using “Get Device events” to confirm the Device ID and User data of monitors that have completed setup.
1. Setup Completion Notification to Webhook URL
※Skip this step if using Provisioning API to avoid duplication.
Once setup is complete, a Token will be posted to the Webhook URL you provided previously. The Token is valid for approximately one hour.
2. Confirming Monitor Device ID and User Data
※Skip this step if using Provisioning API to avoid duplication.
Send the Token using “Get Device events” to confirm the Device ID and User data of the monitor.
3. Creating Access Key
Use “Create Access Key” to generate an Access Key for group management of monitors.
4. Executing Control & Monitoring API
Use “Associate the device with the access key” to associate each Device ID with an Access Key.
5. Executing Device Management
Specify the device using its Device ID and Access Key, then execute any supported Cloud API to monitor and control the device.
Rotating the Application Display Orientation Using “set screen rotate”
Use set screen rotate in the Control & Monitoring API to rotate the application display orientation.
Execute “set screen rotate”
Note:
- Rotation of SurfaceView is not supported. Use TextureView for video playback instead.
- Note that the following models do not support screen rotation using “set screen rotate”:
- BZ40J (100-inch)
- BZ53L/50L/30L (98-inch)
Images Captured with “take a screenshot” and Image Capture Considerations
1. Images Available for Capture
Images that can be captured using take a screenshot depend on the playback application and input source.
Usage on BZ40J (100-inch) / BZ53L / BZ50L / BZ30L (98-inch)
[Settings] is set to anything other than [Game] or [Graphics], video content below 4K resolution or decimated video (downsampled video) will be displayed only in the upper left quarter of the screen.
Images Available for Capture Using “take a screenshot”
Screen State: [Home] Screen Display
Actual Screen
Screenshot Captured Image
*Resolution 1920×1080
Preventing Playback Pauses During Screenshot Capture
screenshot?plane=video
Captured Image (Video Plane)
［Not Supported］
Screen State: Settings Screen Display
Actual Screen
Screenshot Captured Image
*Resolution 1920×1080
Preventing Playback Pauses During Screenshot Capture
screenshot?plane=video
Captured Image (Video Plane)
［Not Supported］
Screen State: Playback Application – Without Tunnel Mode
Actual Screen
Screenshot Captured Image
*Resolution 1920×1080
Preventing Playback Pauses During Screenshot Capture
screenshot?plane=video
Captured Image (Video Plane)
［Not Supported］
Screen State: Playback Application – With Tunnel Mode
Actual Screen
Screenshot Captured Image
*Resolution 320×180
BZ40J (100-inch) / BZ53L / BZ50L / BZ30L (98-inch)
UI capture not available
Others
Preventing Playback Pauses During Screenshot capture
screenshot?plane=video
Captured Image (Video Plane)
BZ40J (100-inch) / BZ53L / BZ50L / BZ30L (98-inch)
UI capture not available
Others
Preventing Playback Pauses During Screenshot capture
Screen State: HDMI Input Source *Supported with main unit firmware PKG 6.7612 or later
Actual Screen
Screenshot Captured Image
*Resolution 320×180
BZ40J (100-inch) / BZ53L / BZ50L / BZ30L (98-inch)
UI cannot be captured
Others
Preventing Playback Pauses During Screenshot capture
screenshot?plane=video
Captured Image (Video Plane)
BZ40J (100-inch) / BZ53L / BZ50L / BZ30L (98-inch)
UI cannot be captured
Others
Preventing Playback Pauses During Screenshot capture
2. Preventing Playback Pauses During Screenshot capture
“take a screenshot” calls the Android callback functions onPause() and onResume(). Therefore, if the playback application pauses the video in onPause(), playback will stop for approximately 0.1 to 0.5 seconds during screenshot capture.
For this reason, we recommend implementing video pause processing in onStop() instead of onPause(). This allows screenshots to be taken without interrupting playback during screenshot capture.
Example for Java
@Override
protected void onStop() {
super.onStop();
if (videoView.isPlaying()) {
videoView.pause();Display Behavior and Call Frequency When Using Control & Monitoring API
When using the following Control & Monitoring API functions with the monitor screen on, a “Please Wait” dialog may appear and the monitor may become unresponsive for several seconds to tens of seconds.
Target Control & Monitoring APIs
/devices/{deviceId}/apk-install/requests
/devices/{deviceId}/apk-uninstall/requests
/devices/{deviceId}/pro-mode/requests
/devices/{deviceId}/reboot/requests
/devices/{deviceId}/settings-export/requests
/devices/{deviceId}/settings-import/requests
/{deviceId}/system-software-update/requests
This occurs because the monitor performs internal processing during API operations, temporarily restricting user interaction. Normal operation resumes once processing is complete. We recommend limiting Cloud API calls to no more than 50 per second. Excessive calls may cause errors due to server overload. If an error occurs, wait briefly before retrying the request.