API 接口速查

目标：掌握 LeLamp 全部 REST API 端点——按模块速查、鉴权方式、可直接复制运行的 curl 示例

一、基础约定

地址与鉴权

首次开机时树莓派处于 AP 模式，地址是 http://192.168.4.1/api/v1；配网成功并切到 Station 模式后才用 lelamp.local。

验证环境

# 先确认 API 可达（应看到 JSON 或至少非空响应）
curl -s http://lelamp.local/api/v1/dashboard/status | head -c 300

二、仪表盘模块（dashboard）

系统状态

curl -s http://lelamp.local/api/v1/dashboard/status

返回：name、online、uptime、version、services（motors/face_tracking/vision/rgb/audio 各自开关状态）、cpu（温度/占用）、memory。

电机控制

5 个电机参数（ID 与范围）：

# 让台灯左右摇头（你应看到：灯头先转右再转左）
curl -X POST http://lelamp.local/api/v1/dashboard/motors/move \
  -H "Content-Type: application/json" \
  -d '{"motor": "base_yaw", "position": 30}'
sleep 1
curl -X POST http://lelamp.local/api/v1/dashboard/motors/move \
  -H "Content-Type: application/json" \
  -d '{"motor": "base_yaw", "position": -30}'

动画管理

内置动画：happy、sad、surprised、greeting、sleepy、wake_up

面部追踪 / 服务开关 / 设置 / 主题

# 追踪状态与开关
curl -s http://lelamp.local/api/v1/dashboard/tracking/status
curl -X POST http://lelamp.local/api/v1/dashboard/tracking/enable \
  -H "Content-Type: application/json" -d '{"enabled": true}'
curl -X POST http://lelamp.local/api/v1/dashboard/tracking/sensitivity \
  -H "Content-Type: application/json" -d '{"sensitivity": 0.8}'

# 服务开关（列表见下）
curl -s http://lelamp.local/api/v1/dashboard/services/
curl -X POST http://lelamp.local/api/v1/dashboard/services/toggle \
  -H "Content-Type: application/json" -d '{"service": "face_tracking", "enabled": true}'

# 设置
curl -s http://lelamp.local/api/v1/dashboard/settings/
curl -X POST http://lelamp.local/api/v1/dashboard/settings/volume \
  -H "Content-Type: application/json" -d '{"type": "speaker", "volume": 70}'
curl -X POST http://lelamp.local/api/v1/dashboard/settings/update \
  -H "Content-Type: application/json" -d '{"key": "audio.volume", "value": 70}'

# 主题
curl -s http://lelamp.local/api/v1/dashboard/theme/
curl -X POST http://lelamp.local/api/v1/dashboard/theme \
  -H "Content-Type: application/json" -d '{"name": "Lelamp"}'

可开关服务：motors、face_tracking、vision、rgb、audio、spotify、music_modifier、breathing_modifier、twitch_modifier、sway_modifier。

三、动画模块

动画相关端点见上表（dashboard/animations/*）。动画文件为 CSV 帧序列，存放在 lelamp/recordings/，自定义格式见 52 自定义扩展。

四、音乐模块

REST 层目前提供 Spotify 凭证管理；播放控制（本地音乐、Spotify 播放等）走工具层（语音 / MCP），见 51 MCP 集成。

# 获取回调地址
curl -s http://lelamp.local/api/v1/spotify/callback-url

# 保存 Spotify 凭证
curl -X POST http://lelamp.local/api/v1/spotify/credentials \
  -H "Content-Type: application/json" \
  -d '{"client_id": "...", "client_secret": "..."}'

五、工作流模块

# 列出工作流 → 你应看到含 focus_session / bedside_alarm / party_it_up 等
curl -s http://lelamp.local/api/v1/workflows/

# 获取详情
curl -s http://lelamp.local/api/v1/workflows/morning_routine

# 触发
curl -X POST http://lelamp.local/api/v1/workflows/morning_routine/trigger

六、视频 / 视觉模块

# 摄像头设备列表与选择
curl -s http://lelamp.local/api/v1/setup/camera/list
curl -X POST http://lelamp.local/api/v1/setup/camera/select \
  -H "Content-Type: application/json" -d '{"device": "/dev/video0"}'

# 摄像头测试（设置向导）
curl -X POST http://lelamp.local/api/v1/setup/camera/test

# 面部追踪（视觉相关服务）
curl -s http://lelamp.local/api/v1/dashboard/tracking/status
curl -X POST http://lelamp.local/api/v1/dashboard/tracking/enable \
  -H "Content-Type: application/json" -d '{"enabled": true}'

七、设置模块（setup）

# WiFi
curl -s http://lelamp.local/api/v1/setup/wifi/scan
curl -X POST http://lelamp.local/api/v1/setup/wifi/connect \
  -H "Content-Type: application/json" -d '{"ssid": "你家WiFi", "password": "密码"}'
curl -s http://lelamp.local/api/v1/setup/wifi/country
curl -X POST http://lelamp.local/api/v1/setup/wifi/country \
  -H "Content-Type: application/json" -d '{"country": "CN"}'
curl -X POST http://lelamp.local/api/v1/setup/wifi/configure-station
curl -X POST http://lelamp.local/api/v1/setup/wifi/enable-ap
curl -s http://lelamp.local/api/v1/setup/wifi/status

# AI 后端（provider: openai / grok / gemini / azure / deepseek）
curl -s http://lelamp.local/api/v1/setup/ai-backend/status
curl -X POST http://lelamp.local/api/v1/setup/ai-backend/configure \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "api_key": "sk-xxx", "model": "gpt-4o"}'

# 环境变量 / 性格 / 位置时区
curl -X POST http://lelamp.local/api/v1/setup/env \
  -H "Content-Type: application/json" -d '{"OPENAI_API_KEY": "sk-xxx"}'
curl -X POST http://lelamp.local/api/v1/setup/personality \
  -H "Content-Type: application/json" \
  -d '{"name": "我的台灯", "voice_style": "friendly", "personality": "helpful"}'
curl -X POST http://lelamp.local/api/v1/setup/location \
  -H "Content-Type: application/json" -d '{"city": "Beijing", "timezone": "Asia/Shanghai"}'

# 音频 / RGB / 校准 / 命名
curl -X POST http://lelamp.local/api/v1/setup/audio/test-speaker
curl -X POST http://lelamp.local/api/v1/setup/rgb/configure \
  -H "Content-Type: application/json" -d '{"led_count": 16, "default_color": "#FF6B35"}'
curl -X POST http://lelamp.local/api/v1/setup/calibration/start
curl -X POST http://lelamp.local/api/v1/setup/device/name \
  -H "Content-Type: application/json" -d '{"name": "我的台灯"}'

# 设置完成状态
curl -s http://lelamp.local/api/v1/setup/status

八、AI Agent 与角色模块

# 唤醒 / 睡眠 / 重启服务
curl -X POST http://lelamp.local/api/v1/agent/wake
curl -X POST http://lelamp.local/api/v1/agent/sleep
curl -X POST http://lelamp.local/api/v1/agent/restart

# 切换角色
curl -X POST http://lelamp.local/api/v1/agent/character \
  -H "Content-Type: application/json" -d '{"character_file": "path/to/character.json"}'

# 设备信息
curl -s http://lelamp.local/api/v1/agent/info

# 角色管理
curl -s http://lelamp.local/api/v1/characters/
curl -X POST http://lelamp.local/api/v1/characters/ \
  -H "Content-Type: application/json" \
  -d '{"character_file": "lelamp/personality/characters/friendly.json"}'

九、系统管理模块

# 开机自启控制
curl -X POST http://lelamp.local/api/v1/system/service/enable
curl -X POST http://lelamp.local/api/v1/system/service/disable
curl -X POST http://lelamp.local/api/v1/system/service/restart

# 网络信息
curl -s http://lelamp.local/api/v1/system/network
curl -s http://lelamp.local/api/v1/system/network/status

# 音频修复（PulseAudio）
curl -X POST http://lelamp.local/api/v1/system/audio/fix-pulse

# 系统信息
curl -s http://lelamp.local/api/v1/system/info

十、认证模块

# 获取认证配置（前端用）
curl -s http://lelamp.local/api/v1/auth/config

# 获取认证状态
curl -s http://lelamp.local/api/v1/auth/status

默认 auth.enabled: false 时以上两个端点仅返回当前配置；若在生产环境开启了认证，所有请求需携带认证头（具体方式随开启时配置而定）。

十一、全流程示例（可验证）

# 1. 开机后（AP 模式 192.168.4.1）扫描 WiFi 并连接
curl -s http://192.168.4.1/api/v1/setup/wifi/scan
curl -X POST http://192.168.4.1/api/v1/setup/wifi/connect \
  -H "Content-Type: application/json" \
  -d '{"ssid": "HomeWiFi", "password": "xxxx"}'

# 2. 切到 Station 模式（之后用 http://lelamp.local 访问）
curl -X POST http://192.168.4.1/api/v1/setup/wifi/configure-station
# → 你应看到：success: true；数秒后树莓派连上 HomeWiFi

# 3. 摇一下头
curl -X POST http://lelamp.local/api/v1/dashboard/motors/move \
  -H "Content-Type: application/json" -d '{"motor": "base_yaw", "position": 30}'
sleep 1
curl -X POST http://lelamp.local/api/v1/dashboard/motors/move \
  -H "Content-Type: application/json" -d '{"motor": "base_yaw", "position": -30}'
# → 你应看到：灯头先右转 30° 再左转 30°

# 4. 开启面部追踪
curl -X POST http://lelamp.local/api/v1/dashboard/tracking/enable \
  -H "Content-Type: application/json" -d '{"enabled": true}'
# → 你应看到：人出现在摄像头前时灯头跟随移动

# 5. 播放开心动画
curl -X POST http://lelamp.local/api/v1/dashboard/animations/play \
  -H "Content-Type: application/json" -d '{"name": "happy"}'
# → 你应看到：台灯做出"开心"动作

常见问题