Documentation and tools for the Bambu Lab Cloud API based on network traffic analysis
Documentation and tooling for communicating with Bambu Lab 3D printers via their Cloud API, MQTT protocol, and local connections.
My goal with this project was to create a proxy for handling read only data from my printer farm, but decided to expand it into a more complete library. I won't be targetting all of the functionality for testing, as I will primarily focus on read operations.
- API Documentation - Complete endpoint reference with examples
- Python Library - Unified client for Cloud API, MQTT, local FTP, and video streams
- Authentication with 2FA - Automatic login with email verification code support
- MQTT Support - Real-time printer monitoring and control
- File Upload - Cloud API and local FTP upload support
- Video Streaming - RTSP (X1 series) and JPEG frame streaming (A1/P1 series)
- Compatibility Layer - Restore legacy local API without developer mode
- Proxy Servers - Safe API gateways (strict read-only and full modes)
- Testing Suite - Comprehensive unit tests for all functionality
- G-code Reference - Command documentation for printer models
Live JPEG frame streaming from P1S printer camera
# Interactive login with 2FA support
python cli_tools/login.py
# Or non-interactive
python cli_tools/login.py --username [email protected] --password yourpassThe tool will:
- Submit your credentials to Bambu Lab
- Request email verification code
- Prompt you to enter the code from your email
- Save the token to
~/.bambu_tokenfor future use
Test all functionality with the comprehensive test suite:
cd tests
cp test_config.json.example test_config.json
# Edit test_config.json with your credentials
python3 test_comprehensive.pyTest Coverage:
- Cloud API (20 endpoints tested)
- MQTT real-time monitoring
- Video streaming credentials
- File upload to cloud
- AMS filament data
- Device management
Recent Test Results: 20/20 tests passing
- All Cloud API endpoints working
- MQTT live data streaming confirmed
- File upload to S3 verified
- TUTK video credentials obtained
Complete API documentation split into focused modules:
- API_INDEX.md - Master index and quick start guide
- API_AUTHENTICATION.md - Authentication methods and security
- API_DEVICES.md - Device management and print jobs
- API_USERS.md - User profiles and accounts
- API_FILES_PRINTING.md - Cloud file upload and printing
- API_MQTT.md - Real-time MQTT protocol
- API_AMS_FILAMENT.md - AMS and filament data
- API_CAMERA.md - Camera and video streaming
- API_REFERENCE.md - Error codes and conventions
The bambulab/ package provides a unified Python interface for Bambu Lab Cloud API access.
# Install from PyPI (includes all features)
pip install bambu-lab-cloud-api
# Or install latest from GitHub
pip install git+https://github.com/coelacant1/Bambu-Lab-Cloud-API.gitv1.0.4+ includes everything by default:
- Cloud API client
- MQTT support
- Camera streaming
- Proxy servers with rate limiting
- CLI tools
See INSTALL.md for detailed installation instructions.
from bambulab import BambuAuthenticator, BambuClient
# Authenticate with 2FA support
auth = BambuAuthenticator()
token = auth.login("[email protected]", "your-password")
# ^ Will prompt for email verification code
# Or use saved token (auto-refresh if needed)
token = auth.get_or_create_token(
username="[email protected]",
password="your-password"
)
# Use token with client
client = BambuClient(token=token)from bambulab import BambuClient
client = BambuClient(token="your_token")
devices = client.get_devices()
for device in devices:
print(f"{device['name']}: {device['print_status']}")
# Upload file to cloud
result = client.upload_file("model.3mf")
print(f"Uploaded: {result['file_url']}")from bambulab import MQTTClient
def on_message(device_id, data):
print(f"Progress: {data['print']['mc_percent']}%")
mqtt = MQTTClient("uid", "token", "device_serial", on_message=on_message)
mqtt.connect(blocking=True)from bambulab import LocalFTPClient
client = LocalFTPClient("192.168.1.100", "access_code")
client.connect()
result = client.upload_file("model.3mf")
client.disconnect()
print(f"Uploaded to: {result['remote_path']}")from bambulab import JPEGFrameStream, RTSPStream
# For A1/P1 series (JPEG frames)
with JPEGFrameStream("192.168.1.100", "access_code") as stream:
frame = stream.get_frame()
with open('snapshot.jpg', 'wb') as f:
f.write(frame)
# For X1 series (RTSP)
stream = RTSPStream("192.168.1.100", "access_code")
url = stream.get_stream_url() # Use with VLC, ffmpegSee bambulab/README.md for complete library documentation.
Restores legacy local API functionality without developer mode. Bridges Home Assistant, Octoprint, and other tools to the Cloud API.
cd servers
cp compatibility_config.json.example compatibility_config.json
# Edit with your credentials
python3 compatibility.pyFeatures:
- Mimics legacy local API endpoints
- Works without developer mode
- Real-time MQTT bridge
- Multi-device support
- Port 8080 by default
This requires additional testing, I only lightly tested this.
API gateway with two modes for different security requirements:
Strict Mode (port 5001) - Read-only, maximum safety:
python3 proxy.py strictFull Mode (port 5003) - Complete 1:1 proxy:
python3 proxy.py fullFeatures:
- Custom token authentication
- Request filtering by mode
- Health monitoring endpoints
Command-line utilities for quick printer access:
| Tool | Purpose |
|---|---|
bambu-query |
Query printer information and status |
bambu-monitor |
Real-time MQTT monitoring |
bambu-camera |
View live camera feed |
After installation, use directly:
bambu-query YOUR_TOKEN --devices
bambu-monitor YOUR_UID YOUR_TOKEN YOUR_DEVICE_ID
bambu-camera YOUR_TOKEN --ip 192.168.1.100See cli_tools/README.md for detailed usage.
Based on comprehensive testing (see test output):
- Device Management - List devices, get info, firmware versions
- User Profile - Account information, owned printer models
- AMS/Filament - Filament data from AMS units
- Camera Credentials - TTCode for P2P video streaming (TUTK protocol)
- File Upload - Cloud file upload via S3 signed URLs
- File Management - List and manage cloud files
- Connection - Stable MQTT connection to printers
- Live Status - Real-time temperature, progress, state updates
- Full Data - Complete printer state including:
- Temperatures (nozzle, bed, chamber)
- Print progress and layer info
- Fan speeds and print speeds
- AMS status and filament data
- Error codes (HMS)
- Network info (WiFi signal)
- TUTK Protocol - P2P video credentials for local streaming
- TTCode Generation - Authentication for camera access
- Multi-Model Support - P1/A1 (JPEG), X1 (RTSP)
- Local FTP Upload - Implemented, requires local network testing
- Compatibility Layer - Lightly tested, works with legacy tools
- Print job submission via API
- Device control commands (pause, resume, stop)
- Some write operations (device settings)
Integrate with Home Assistant via the compatibility layer:
cd servers
python3 compatibility.pyHome Assistant configuration:
rest:
- resource: http://localhost:8080/api/v1/status?device_id=YOUR_DEVICE_ID
scan_interval: 10
sensor:
- name: "Bambu Print Progress"
value_template: "{{ value_json.print.mc_percent }}"for device in api.get_devices():
status = api.get_print_status(device['dev_id'])
print(f"{device['name']}: {status['progress']}%")def on_status(device_id, data):
if data['print']['mc_percent'] == 100:
send_notification("Print complete!")
mqtt = MQTTClient(uid, token, device_id, on_message=on_status)
mqtt.connect(blocking=True)
Live JPEG frame streaming from P1S printer camera
The comprehensive test suite provides detailed information about all API endpoints and printer data:
Comprehensive test output showing Cloud API tests with device info, firmware versions, and all data fields
MQTT monitoring with real-time printer data including temperatures, fan speeds, and print progress
Complete MQTT data streams showing all available fields from printer status updates
Camera credentials and video streaming configuration with TTCode authentication
File upload testing and cloud storage integration results
This project is not affiliated with or endorsed by Bambu Lab. It is an effort to document their API.
- Use at your own risk
- Respect Bambu Lab's Terms of Service
- Don't abuse API rate limits
- Be responsible with printer control
The API may change without notice. This documentation represents the API as of October 2025 based on testing with firmware versions 01.08.02.00 and 01.09.00.00.
Tested Configurations:
- Printer Models: P1P, P1S
- Firmware: 01.08.02.00, 01.09.00.00
- Python: 3.9-3.13
- Test Suite: 20/20 passing (Full testing with 3.13)
Documents API endpoints to ensure backwards compatibility and interoperability; the necessary information was determined through network traffic analysis of the official client communicating with publicly accessible servers, which complies with fair use principles.
This analysis:
- Documents publicly accessible API endpoints
- Enables community integrations and home automation
- Complies with fair use for interoperability
- Uses only your own credentials for testing
Does NOT:
- Bypass security measures
- Violate terms of service
- Redistribute proprietary code
- Enable unauthorized access
Contributions are welcome. Please:
- Fork the repository
- Create a feature branch
- Test your changes
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the GNU Affero General Public License v3.0 - see LICENSE for details.