API 参考文档

概述与快速开始

产品概述

涂鸦面向终端用户的开放能力，覆盖 3,000+ 智能硬件品类，200+ 国家和地区。通过本 API，您可以实现：

• 查询家庭、房间、设备列表及状态
• 下发控制指令（开关、亮度、温度、模式等）
• 实时订阅设备属性变化与上下线事件
• 查询天气信息
• 发送短信、语音电话、邮件、App 推送通知
• 查询设备用电量等统计数据
• IPC 摄像头云端截图与短视频录制

获取 API Key

API Key 格式为 sk-<PREFIX><rest>，前缀两个字母决定数据中心区域。

中国大陆用户：https://tuyasmart.com/
国际用户：https://tuya.ai/

认证与数据中心

认证方式

所有 REST API 请求均通过 HTTP Header 携带 API Key 认证：

Authorization: Bearer {API_KEY}

示例：
curl -H "Authorization: Bearer sk-AYxxx..." \
     https://openapi.tuyacn.com/v1.0/end-user/homes/all

数据中心映射

API Key 中 sk- 后的前两个字符自动对应数据中心：

• AY → 中国数据中心 → openapi.tuyacn.com
• AZ → 美西数据中心 → openapi.tuyaus.com
• EU → 中欧数据中心 → openapi.tuyaeu.com
• IN → 印度数据中心 → openapi.tuyain.com
• UE → 美东数据中心 → openapi-ueaz.tuyaus.com
• WE → 西欧数据中心 → openapi-weaz.tuyaeu.com
• SG → 新加坡数据中心 → openapi-sg.iotbing.com

家庭与空间管理

获取当前用户的所有家庭列表，包含家庭 ID、名称、角色、地理位置等信息。

响应示例

{
  "success": true,
  "result": {
    "homes": [
      {
        "home_id": "123456",
        "name": "My Apartment",
        "role": "admin",
        "create_time": 1593661208,
        "latitude": {"Value": "30.3"},
        "longitude": {"Value": "120.07"}
      }
    ]
  }
}

字段说明

Field	Type	Description
home_id	String	家庭 ID
name	String	家庭名称
role	String	用户角色：owner / admin / member
create_time	Long	创建时间（Unix 时间戳，秒）
latitude/longitude	Object	家庭地理位置（可选），可用于天气查询

获取指定家庭下所有房间的列表，包含房间 ID 和名称。

请求参数

Name	Type	Required	Description
home_id	String	是	家庭 ID（Path 参数）

响应示例

{
  "success": true,
  "result": {
    "rooms": [
      { "room_id": "123123", "name": "Living Room" }
    ]
  }
}

设备查询

一次性返回当前用户所有设备，无分页。包含设备 ID、名称、品类、在线状态等。

响应示例

{
  "success": true,
  "result": {
    "devices": [
      {
        "device_id": "0620068884f3eb414579",
        "name": "Living Room Light",
        "category": "dj",
        "category_name": "Light Source",
        "online": true
      }
    ],
    "total": 3
  }
}

字段说明

Field	Type	Description
device_id	String	设备 ID
name	String	设备名称
category	String	品类代码
category_name	String	品类名称
online	Boolean	是否在线

获取指定家庭下的所有设备列表。

请求参数

Name	Type	Required	Description
home_id	String	是	家庭 ID（Path 参数）

获取指定房间下的所有设备列表。

请求参数

Name	Type	Required	Description
room_id	String	是	房间 ID（Path 参数）

获取设备完整信息，包含当前所有属性状态（properties 字段为键值对）。设备未找到时 result 为 null。

请求参数

Name	Type	Required	Description
device_id	String	是	设备 ID（Path 参数）

响应示例

{
  "success": true,
  "result": {
    "device_id": "0620068884f3eb414579",
    "name": "Living Room Light",
    "online": true,
    "firmware_version": "1.0.0",
    "firmware_update_available": false,
    "properties": {
      "switch_led": true,
      "bright_value": 100,
      "work_mode": "colour"
    }
  }
}

字段说明

Field	Type	Description
online	Boolean	是否在线
firmware_update_available	Boolean	是否有固件更新
properties	Map	设备当前属性键值对，Key 为属性码（dp code）

设备控制

物模型描述设备支持哪些功能属性，控制设备前建议先查询。注意：result.model 字段是 JSON 字符串，需二次 JSON.parse 解析。

请求参数

Name	Type	Required	Description
device_id	String	是	设备 ID（Path 参数）

响应示例

{
  "services": [{
    "properties": [
      {
        "code": "switch_led",
        "name": "Switch",
        "accessMode": "rw",
        "typeSpec": { "type": "bool" }
      },
      {
        "code": "bright_value",
        "name": "Brightness",
        "accessMode": "rw",
        "typeSpec": { "type": "value", "min": 10, "max": 1000, "step": 1 }
      }
    ]
  }]
}

字段说明

Field	Type	Description
code	String	属性码，下发控制时作为 Key 使用
accessMode	String	ro 只读 / wr 只写 / rw 读写
typeSpec.type	String	bool / value / enum / string
typeSpec.min/max	Number	数值类型的取值范围（仅 value 类型）
typeSpec.range	Array	枚举取值列表（仅 enum 类型）

向设备发送控制命令。注意：properties 字段必须是 JSON 字符串（而非对象），需要对属性对象进行二次序列化。

常用属性码：switch_led（灯开关）/ bright_value（亮度 10-1000）/ temp_value（色温）/ switch（空调开关）/ temp_set（设定温度 16-30）/ mode（工作模式）/ switch_1（插座开关）

请求参数

Name	Type	Required	Description
device_id	String	是	设备 ID（Path 参数）
properties	String	是	属性键值对序列化后的 JSON 字符串

响应示例

// Request body
{
  "properties": "{\"switch_led\": true, \"bright_value\": 500}"
}

// Success response
{ "success": true, "t": 1710234567890, "result": {} }

设备管理

修改设备的显示名称。

请求参数

Name	Type	Required	Description
device_id	String	是	设备 ID（Path 参数）
name	String	是	新的设备名称（请求体）

响应示例

// Request body
{ "name": "Bedside Lamp" }

天气查询

获取指定经纬度的当前及逐小时天气预报。响应数据 Key 格式为 {属性码}.{时间索引}，索引 0 为当前，1 为 1 小时后，以此类推。

请求参数

Name	Type	Required	Description
lat	String	是	纬度（Query 参数）
lon	String	是	经度（Query 参数）
codes	String	是	天气属性 JSON 数组字符串，如 ["w.temp","w.humidity","w.hour.7"]

响应示例

GET /v1.0/end-user/services/weather/recent
  ?codes=["w.temp","w.humidity","w.condition","w.hour.7"]
  &lat=39.9042&lon=116.4074

// Response
{
  "result": {
    "data": {
      "w.temp.0": 7,
      "w.temp.1": 6,
      "w.humidity.0": 44,
      "w.condition.0": "no precipitation"
    },
    "expiration": 15
  }
}

字段说明

Field	Type	Description
w.temp	Number	温度
w.humidity	Number	湿度
w.condition	String	天气描述（英文）
w.pressure	Number	气压
w.realFeel	Number	体感温度
w.uvi	Number	紫外线指数
w.windDir	String	风向
w.windSpeed	Number	风速
w.hour.N	String	时间粒度，N 为小时数（如 w.hour.7 返回未来 7 小时数据）

消息通知

说明

所有通知 API 均为自发送模式，只能向当前登录用户发送。

频率限制：
• 短信/语音：同一手机号 24 小时内不超过 15 条，50 秒内相同内容不超过 2 条
• 邮件：同一邮箱 24 小时内不超过 30 封，50 秒内相同内容不超过 2 封

向当前登录用户的手机号发送短信。频率限制：24 小时内 ≤15 条，50 秒内相同内容 ≤2 条。

请求参数

Name	Type	Required	Description
message	String	是	短信内容（请求体）

响应示例

{ "message": "Security alert: door sensor detected abnormal opening" }

向当前登录用户的手机号发起语音播报电话。频率限制同短信。

请求参数

Name	Type	Required	Description
message	String	是	语音播报内容（请求体）

响应示例

{ "message": "Security alert: abnormal activity detected" }

向当前登录用户的邮箱发送邮件。频率限制：24 小时内 ≤30 封。

请求参数

Name	Type	Required	Description
subject	String	是	邮件主题（请求体）
content	String	是	邮件正文（请求体）

响应示例

{ "subject": "Device Offline Alert", "content": "Your living room AC went offline" }

向当前登录用户的涂鸦 App 发送推送通知。

请求参数

Name	Type	Required	Description
subject	String	是	推送标题（请求体）
content	String	是	推送内容（请求体）

响应示例

{ "subject": "Security Alert", "content": "Camera detected motion at entrance" }

数据统计

Field	Type	Description
dp_code	String	数据点代码，如 ele_usage（用电量）
statistic_type	String	统计方式：SUM / COUNT / MAX / MIN

Name	Type	Required	Description
dev_id	String	是	设备 ID
dp_code	String	是	数据点代码
statistic_type	String	是	统计类型（SUM/COUNT/MAX/MIN）
start_time	String	是	开始时间，格式 yyyyMMddHH，如 2024010110
end_time	String	是	结束时间，格式 yyyyMMddHH（与 start_time 差值 ≤24h）

IPC 云端抓拍

流程说明

IPC 抓拍分两步：
1. Allocate（分配）— 触发摄像头抓拍，获取云存储位置信息
2. Resolve（解析）— 轮询等待抓拍完成，获取可访问的图片/视频 URL

Python SDK 提供封装好的一步调用方法，自动处理等待和重试。

触发摄像头进行云端截图或短视频录制。

请求参数

Name	Type	Required	Description
device_id	String	是	摄像头设备 ID（Path 参数）
capture_json	String	是	抓拍配置 JSON 字符串，含 capture_type（PIC/VIDEO）、pic_count（1-5）、video_duration_seconds（1-60）

响应示例

{
  "capture_json": "{\"device_id\":\"your_device_id\",\"capture_type\":\"PIC\",\"pic_count\":1}"
}

轮询获取抓拍结果 URL。若 status 为 NOT_READY，需等待后重试（建议每 2 秒轮询一次）。

请求参数

Name	Type	Required	Description
device_id	String	是	摄像头设备 ID（Path 参数）

响应示例

// Success (PIC)
{
  "status": "READY",
  "decrypt_image_url": "https://..."
}
// Success (VIDEO)
{
  "status": "READY",
  "decrypt_video_url": "https://...",
  "decrypt_cover_url": "https://..."
}
// Still processing
{ "status": "NOT_READY" }

实时消息订阅 (WebSocket)

重要限制

WebSocket 客户端必须运行在服务端，禁止在浏览器或移动端直接连接，避免 API Key 泄露。如需向前端推送实时数据，应由服务端订阅后通过 SSE、自定义 WebSocket 或轮询的方式中转。

消息格式

所有 WebSocket 消息均为 JSON，包含 eventType 和 data 两个顶层字段。

属性变化事件：
{
  "eventType": "devicePropertyChange",
  "data": {
    "devId": "36040531cc50e35ee60d",
    "status": [
      { "code": "led_switch", "value": true, "time": 1773668532000 }
    ]
  }
}

上下线事件：
{
  "eventType": "onlineStatusChange",
  "data": {
    "devId": "6c8b3a57470efd4d9cun7h",
    "status": "online",
    "time": 1773668467323
  }
}

WebSocket URI

• AY → wss://wsmsgs.tuyacn.com
• AZ → wss://wsmsgs.iot-wus.com
• EU → wss://wsmsgs.iot-eu.com
• IN → wss://wsmsgs.iot-ap.com
• UE → wss://wsmsgs.iot-eus.com
• WE → wss://wsmsgs.iot-weu.com
• SG → wss://wsmsgs.iot-sea.com

错误处理

通用错误码

• 1010 — Token 无效或已过期 → 更新 API Key
• 1108 — API 路径错误 → 检查请求路径
• 10001 — 请求参数错误 → 验证参数格式
• 10010 — 用户不存在 → 检查 API Key
• 10011 — 用户未绑定联系方式 → 在涂鸦 App 绑定手机/邮箱
• 40000901 — 设备不存在 → 检查 device_id
• 40000903 — 设备物模型不存在 → 该设备可能不支持物模型查询
• 429 — 请求频率超限 → 指数退避后重试
• 500 — 服务端错误 → 稍后重试

通知错误码

• 20001 — 手机号无效
• 20002 — 短信超过 24 小时限额（15 条）
• 20003 — 50 秒内相同内容重复超限
• 30001 — 邮箱地址无效
• 30002 — 邮件超过 24 小时限额（30 封）
• 40002 — 语音电话超过 24 小时限额（15 次）

业务异常处理

• 设备 result 为 null → 提示设备不存在
• 设备 online 为 false → 提示设备离线，不要下发控制指令
• 属性 accessMode 为 ro → 该属性只读，不支持控制
• 属性值超出范围 → 提示有效范围，请求用户重新输入
• 多个设备匹配同一名称 → 列出所有匹配项，请求用户确认

概述与快速开始

产品概述

获取 API Key

认证与数据中心

认证方式

数据中心映射

家庭与空间管理

响应示例

字段说明

请求参数

响应示例

设备查询

响应示例

字段说明

请求参数

请求参数

请求参数

响应示例

字段说明

设备控制

请求参数

响应示例

字段说明

请求参数

响应示例

设备管理

请求参数

响应示例

天气查询

请求参数

响应示例

字段说明

消息通知

说明

请求参数

响应示例

请求参数

响应示例

请求参数

响应示例

请求参数

响应示例

数据统计

推荐工作流

响应示例

字段说明

请求参数

响应示例

IPC 云端抓拍

流程说明

请求参数

响应示例

请求参数

响应示例

实时消息订阅 (WebSocket)

重要限制

消息格式

WebSocket URI

错误处理

通用错误码

通知错误码

业务异常处理