Doorlock Photos & Video API
Last Updated on : 2023-06-15 05:15:19
Query video views
Applicable lock types
- Wi-Fi lock
API endpoint
GET /v1.0/smart-lock/devices/{device_id}/media-view-times
Request parameter
Parameter Type Parameter type Description Required
device_id String URI The device ID. Yes
Sample request
GET /v1.0/smart-lock/devices/vdevo124546565765/media-view-times
Response parameter
Parameter Type Description
Code Integer The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success Boolean Indicates whether the operation is successful. Valid values:
- true: succeeded.
- false: failed.
t Long The response time.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Integer The number of video views.
Sample response on success
{
"result": 1,
"success": true,
"t": 1634712882506
}
Sample response on failure
{
"success": false,
"code": 500, // The error code. For more information, see Global Error Codes.
"msg": "system error, please contact the admin"
}
Add one video view
Applicable lock types
- Wi-Fi lock
API endpoint
POST /v1.0/smart-lock/devices/{device_id}/media-view-times
Request parameter
Parameter Type Parameter type Description Required
device_id String URI The device ID. Yes
Sample request
POST /v1.0/smart-lock/devices/vdevo124546565765/media-view-times
Response parameter
Parameter Type Description
Code Integer The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success Boolean Indicates whether the operation is successful. Valid values:
- true: succeeded.
- false: failed.
t Long The response time.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Integer The number of video views.
Sample response on success
{
"result": 2,
"success": true,
"t": 1634713143910
}
Sample response on failure
{
"success": false,
"code": 500, // The error code. For more information, see Global Error Codes.
"msg": "system error, please contact the admin"
}
Remote unlocking with photo capturing
-
The following figure shows how remote unlocking with photo capturing works.
-
Remote unlocking with photo capturing in real time
- When a user attempts to unlock a door, the camera lock captures a photo and uploads it to the cloud.
- The cloud stores the media data and sends a relative path to the client.
- The client calls an API to get the full URL of the media.
- The client gets the encrypted media data and decrypts it.
- The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
- The cloud sends a command to the lock accordingly.
-
Remote unlocking with photo capturing in non-real time
- The client calls an API to get the unlocking or alert media in the last 90 seconds.
- The client gets the encrypted media data and decrypts it.
- The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
- The cloud sends a command to the lock accordingly.
The media data is encrypted by using the AES algorithm with CBC mode and PKCS5Padding.
4 16 44 Video content
Placeholder iv Placeholder Video content
The demo shows how decryption works.
package xxxxxxx;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Random;
import javax.crypto.Cipher;
import javax.crypto.CipherInputStream;
import javax.crypto.CipherOutputStream;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class EncryptUtils {
private static final String DEFAULT_ALGORITHM = "AES";
private static final String DEFAULT_FULL_ALGORITHM = "AES/CBC/PKCS5Padding";
// Encryption
public static File encryptFile(String key, File originFile, String destPath) {
FileInputStream in = null;
FileOutputStream out = null;
File destFile = null;
try {
destFile = new File(destPath);
if (originFile.exists() && originFile.isFile()) {
if (!destFile.getParentFile().exists()) {
destFile.getParentFile().mkdirs();
}
destFile.createNewFile();
in = new FileInputStream(originFile);
out = new FileOutputStream(destFile, true);
byte[] iv = getIv();
Cipher cipher = initAESCipher(iv, key, Cipher.ENCRYPT_MODE);
CipherInputStream cipherInputStream = new CipherInputStream(in, cipher);
byte[] cache = new byte[1024];
int nRead;
out.write(new byte[4]);
out.write(iv);
out.write(new byte[4]);
out.write(new byte[40]);
out.flush();
while ((nRead = cipherInputStream.read(cache)) != -1) {
out.write(cache, 0, nRead);
out.flush();
}
cipherInputStream.close();
}
} catch (Exception e) {
e.printStackTrace();
} finally {
try {
if (out != null) {
out.close();
}
if (in != null) {
in.close();
}
} catch (IOException e) {
e.printStackTrace();
}
}
return destFile;
}
// Decryption
public static File decryptFile(String key, InputStream in, File destFile) {
FileOutputStream out = null;
try {
if (!destFile.getParentFile().exists()) {
destFile.getParentFile().mkdirs();
}
destFile.createNewFile();
out = new FileOutputStream(destFile);
byte[] iv = new byte[16];
in.skip(4);
int read = in.read(iv);
if (read != 16) {
throw new IOException("iv length error");
}
in.skip(44);
Cipher cipher = initAESCipher(iv, key, Cipher.DECRYPT_MODE);
CipherOutputStream cipherOutputStream = new CipherOutputStream(out, cipher);
byte[] buffer = new byte[1024];
int r;
while ((r = in.read(buffer)) >= 0) {
cipherOutputStream.write(buffer, 0, r);
}
cipherOutputStream.close();
} catch (Exception e) {
e.printStackTrace();
} finally {
try {
if (in != null) {
in.close();
}
} catch (IOException e) {
e.printStackTrace();
}
try {
if (out != null) {
out.close();
}
} catch (IOException e) {
e.printStackTrace();
}
}
return destFile;
}
private static Cipher initAESCipher(byte[] iv, String sKey, int cipherMode) {
try {
IvParameterSpec zeroIv = new IvParameterSpec(iv);
SecretKeySpec key = new SecretKeySpec(sKey.getBytes(), DEFAULT_ALGORITHM);
Cipher cipher = Cipher.getInstance(DEFAULT_FULL_ALGORITHM);
cipher.init(cipherMode, key, zeroIv);
return cipher;
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
} catch (NoSuchPaddingException e) {
e.printStackTrace();
} catch (InvalidKeyException e) {
e.printStackTrace();
} catch (InvalidAlgorithmParameterException e) {
e.printStackTrace();
}
return null;
}
public static byte[] getIv() {
StringBuilder uid = new StringBuilder();
// Generate a 16-digit strong random number.
Random rd = new SecureRandom();
for (int i = 0; i < 16; i++) {
// Generate a 3-digit random number between zero and two.
int type = rd.nextInt(3);
switch (type) {
case 0:
// Generate a random number between zero and nine.
uid.append(rd.nextInt(10));
break;
case 1:
// ASCII between 65 to 90 are randomly capitalized.
uid.append((char) (rd.nextInt(25) + 65));
break;
case 2:
// ASCII between 97 to 122 are randomly lowercased.
uid.append((char) (rd.nextInt(25) + 97));
break;
default:
break;
}
}
return uid.toString().getBytes();
}
}
Get cover image of last remote unlocking or alert
Applicable lock types
- Wi-Fi lock
- Zigbee lock for hotel use
- Bluetooth lock
API endpoint
GET /v1.0/devices/{device_id}/door-lock/latest/media/url
Request parameter
Parameter Type Parameter type Description Required
device_id String URI The device ID. Yes
file_type Integer URL The file type. Valid values:
- 1: cover images related to remote unlocking.
- 2: cover images related to alerts.
Sample request
GET /v1.0/devices/6cdb36b2e489885fa57lzm/door-lock/latest/media/url?file_type=1
Response parameter
Parameter Type Description
Code Integer The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success Boolean Indicates whether the operation is successful. Valid values:
- true: succeeded.
- false: failed.
t Long The response time.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.
result
Parameter Type Description
file_url String The full URL of a specified cover image.
file_key String The key to decrypt a specified file.
bucket String The full URL of a specified cover image.
file_path String The relative path of a specified file.
Sample response on success
{
"result": {
"bucket": "ty-cn-storage60-1254153901",
"file_key": "u8kstrtjm7qun83q",
"file_path": "/3039e1-30532026.jpg",
"file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com6"
},
"success": true,
"t": 1614147303662
}
Sample response on failure
{
"success": false,
"code": 500, // The error code. For more information, see Global Error Codes.
"msg": "system error, please contact the admin"
}
Get a list of albums
Applicable lock types
- Wi-Fi lock with video talk
API endpoint
GET /v1.0/smart-lock/devices/{device_id}/albums-media
Request parameter
Parameter Type Parameter type Description Required
device_id String URI The device ID. Yes
Sample request
GET /v1.0/smart-lock/devices/vdevo153459260090544/albums-media
Response parameter
Parameter Type Description
Code Integer The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success Boolean Indicates whether the operation is successful. Valid values:
- true: succeeded.
- false: failed.
t Long The response time.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.
result
Parameter Type Description
eventTypes array[int] The types of cover images and videos in a specified album.
albumList List A list of albums.
orderCode Integer The plan used for the current album query. Valid values:
- doorlock_cloud_storage_7day: unlimited cloud storage for 7 days.
- doorlock_cloud_storage_30day: unlimited cloud storage for 30 days.
- cloud_free_storage_3day: free cloud storage for 3 days.
albumList
Parameter Type Description
eventType int The file type.
fileUrl String The URL of a specified cover image.
fileKey String The secret key of a specified cover image.
mediaPath String The URL of a specified video file.
mediaKey String The secret key of a specified video file.
mediaBucket String The repository where the video file is located.
uploadTime long The reporting time in seconds.
Description of eventType
Type value Type Description
0 int Anti-pry alert
1 int Remote unlocking request
2 int Fingerprint attempt failed
3 int Password attempt failed
4 int Card attempt failed
5 int Face recognition failed
6 int Palm print recognition failed
7 int Finger vein recognition failed
8 int Unlock with fingerprint
9 int Unlock with password
10 int Unlock with card
11 int Unlock with face recognition
12 int Unlock with palm print
13 int Unlock with finger vein
14 int Unlock with temporary password
15 int Unlock with dynamic password
16 int Remote unlocking
17 int Report unlocking with temporary password
18 int Report doorbell request
19 int Duress alarm
20 int Low battery alert
21 int Mechanical key attempt
22 int High temperature alert
23 int Doorbell ringing and remote unlocking
24 int Loitering alert
25 int Lock tampering
26 int Unlock with special fingerprint
27 int Unlocking in arm mode
28 int Unlock with remote control
Sample response on success
{
"success": true,
"t": 1542626129429,
"result": {
"album_list": [
{
"event_type": 0,
"file_id": 109167468,
"file_key": "76679d2579c74eb7",
"file_url": "https://ty-cn-storage30-1254153901.cos.tuyacn.com/d76182-35779292-dc706aecd4469145/unify/1630051338.jpeg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1630137629%3B1630141229%26q-key-time%3D1630137629%3B1630141229%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D29b40dd6ed4281b78321ec978ce1e56361fd7b57",
"upload_time": 1630051337
}
],
"event_types": [
0
],
"order_code": "cloud_free_storage_3day"
}
}
Sample response on failure
{
"success": false,
"code": 500, // The error code. For more information, see Global Error Codes.
"msg": "system error, please contact the admin"
}
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback
