KoKonna OpenAPI: Build Your Own Smart Art Frame Integration

A developer's guide to controlling KoKonna e-ink frames via HTTPS

---

Introduction

KoKonna isn't just a beautiful e-ink art frame—it's also a developer-friendly platform. With the KoKonna OpenAPI, you can programmatically control your frame, upload images, and build custom integrations that make your art frame part of your smart home ecosystem.

Whether you want to:

• Build a custom mobile app
• Create automated art curation systems
• Integrate with home automation platforms
• Develop AI-powered art generation pipelines

The KoKonna OpenAPI gives you full control over your frame with a simple, token-based REST API.

---

Getting Started

Base URL

All API requests are made to:

1. https://api.galaxyguide.cn/openapi

Authentication

KoKonna uses Bearer token authentication. Your token is the device's API key, which you can find in your frame's settings page.

Required Headers:

1. Authorization: Bearer <API_KEY>
2. Content-Type: application/json

Getting Your API Key:

1. Open your KoKonna frame settings
2. Navigate to the API section
3. Copy your device's API key

---

Rate Limiting

The API enforces a rate limit of 20 requests per minute per device key.

If you exceed this limit, you'll receive:

1. {
2. "message": "Too many requests, please try again later."
3. }

---

API Endpoints

1. Get Device Information

Retrieve your frame's current status, battery level, screen dimensions, and more.

Endpoint:POST/device

Request Body:{} (empty or omitted)

Example:

1. curl -X POST https://api.galaxyguide.cn/openapi/device \
2. -H "Authorization: Bearer YOUR_API_KEY" \
3. -H "Content-Type: application/json" \
4. -d '{}'

Response:

1. {
2. "firmware": "B100V260412N",
3. "nickname": "Living Room Frame",
4. "lastHeartbeat": "2026-04-13T05:20:15.123Z",
5. "isCharging": false,
6. "batteryLevel": 87,
7. "sdUsedSize": 0,
8. "switchType": "queue",
9. "switchMinute": 60,
10. "imageId": 75612,
11. "coverId": null,
12. "timezone": "Asia/Shanghai",
13. "point": 20,
14. "screenWidth": 800,
15. "screenHeight": 480,
16. "screenRotate": 270,
17. "synced": true,
18. "online": true
19. }

Key Fields:

Field	Description
firmware	Current firmware version
nickname	Device nickname
batteryLevel	Battery percentage (0-100)
isCharging	Whether the device is charging
screenWidth/Height	Physical screen dimensions in pixels
screenRotate	Screen rotation angle (0, 90, 180, 270)
online	Whether the device is currently online
synced	Whether the device has applied the latest image

---

2. Upload Image

Upload a new image to your frame. The image will automatically become the active display.

Endpoint:POST/upload

Request Body:

1. {
2. "base64": "<BASE64_IMAGE_DATA>",
3. "name": "my-artwork.jpg"
4. }

Important Notes:

• base64 is required and must be raw base64 data (nodata:image/jpeg;base64, prefix)
• name is optional and defaults to the uploaded filename
• Maximum payload size: 50 MB
• Images are automatically cropped to match your device's display aspect ratio

Example:

1. # Convert image to base64 and upload
2. IMAGE_BASE64=$(base64 -w 0 my-artwork.jpg)
4. curl -X POST https://api.galaxyguide.cn/openapi/upload \
5. -H "Authorization: Bearer YOUR_API_KEY" \
6. -H "Content-Type: application/json" \
7. -d "{\"base64\":\"$IMAGE_BASE64\",\"name\":\"my-artwork.jpg\"}"

Response:

1. {
2. "id": 789,
3. "counter": 10
4. }

• id: The created image ID
• counter: Updated frame image counter

---

3. Display Image by ID

Switch to a previously uploaded image by its ID.

Endpoint:POST/displayImageById

Request Body:

1. {
2. "imageId": 123
3. }

Example:

1. curl -X POST https://api.galaxyguide.cn/openapi/displayImageById \
2. -H "Authorization: Bearer YOUR_API_KEY" \
3. -H "Content-Type: application/json" \
4. -d '{"imageId":123}'

Response:

1. {
2. "success": true
3. }

---

4. Display Image by Name

Switch to a previously uploaded image by its filename.

Endpoint:POST/displayImageByName

Request Body:

1. {
2. "imageName": "sunset.jpg"
3. }

Example:

1. curl -X POST https://api.galaxyguide.cn/openapi/displayImageByName \
2. -H "Authorization: Bearer YOUR_API_KEY" \
3. -H "Content-Type: application/json" \
4. -d '{"imageName":"sunset.jpg"}'

Response:

1. {
2. "success": true
3. }

---

Code Examples

Python

1. import base64
2. import requests
4. class KoKonnaFrame:
5. def __init__(self, api_key):
6. self.api_key = api_key
7. self.base_url = "https://api.galaxyguide.cn/openapi"
8. self.headers = {
9. "Authorization": f"Bearer {api_key}",
10. "Content-Type": "application/json"
11. }
13. def get_device_info(self):
14. """Get device information"""
15. response = requests.post(
16. f"{self.base_url}/device",
17. headers=self.headers,
18. json={}
19. )
20. return response.json()
22. def upload_image(self, image_path, name=None):
23. """Upload an image to the frame"""
24. with open(image_path, "rb") as f:
25. image_data = base64.b64encode(f.read()).decode('utf-8')
27. payload = {"base64": image_data}
28. if name:
29. payload["name"] = name
31. response = requests.post(
32. f"{self.base_url}/upload",
33. headers=self.headers,
34. json=payload
35. )
36. return response.json()
38. def display_image_by_id(self, image_id):
39. """Display an image by its ID"""
40. response = requests.post(
41. f"{self.base_url}/displayImageById",
42. headers=self.headers,
43. json={"imageId": image_id}
44. )
45. return response.json()
47. def display_image_by_name(self, image_name):
48. """Display an image by its name"""
49. response = requests.post(
50. f"{self.base_url}/displayImageByName",
51. headers=self.headers,
52. json={"imageName": image_name}
53. )
54. return response.json()
56. # Usage
57. frame = KoKonnaFrame("your-api-key-here")
59. # Get device info
60. info = frame.get_device_info()
61. print(f"Battery: {info['batteryLevel']}%")
62. print(f"Online: {info['online']}")
64. # Upload and display an image
65. result = frame.upload_image("artwork.jpg", name="My Artwork")
66. print(f"Uploaded! Image ID: {result['id']}")
68. # Switch to a previous image
69. frame.display_image_by_name("sunset.jpg")

JavaScript / Node.js

1. const fs = require('fs');
2. const axios = require('axios');
4. class KoKonnaFrame {
5. constructor(apiKey) {
6. this.apiKey = apiKey;
7. this.baseURL = 'https://api.galaxyguide.cn/openapi';
8. this.headers = {
9. 'Authorization': `Bearer ${apiKey}`,
10. 'Content-Type': 'application/json'
11. };
12. }
14. async getDeviceInfo() {
15. const response = await axios.post(
16. `${this.baseURL}/device`,
17. {},
18. { headers: this.headers }
19. );
20. return response.data;
21. }
23. async uploadImage(imagePath, name = null) {
24. const imageBuffer = fs.readFileSync(imagePath);
25. const base64 = imageBuffer.toString('base64');
27. const payload = { base64 };
28. if (name) payload.name = name;
30. const response = await axios.post(
31. `${this.baseURL}/upload`,
32. payload,
33. { headers: this.headers }
34. );
35. return response.data;
36. }
38. async displayImageById(imageId) {
39. const response = await axios.post(
40. `${this.baseURL}/displayImageById`,
41. { imageId },
42. { headers: this.headers }
43. );
44. return response.data;
45. }
47. async displayImageByName(imageName) {
48. const response = await axios.post(
49. `${this.baseURL}/displayImageByName`,
50. { imageName },
51. { headers: this.headers }
52. );
53. return response.data;
54. }
55. }
57. // Usage
58. const frame = new KoKonnaFrame('your-api-key-here');
60. // Get device info
61. const info = await frame.getDeviceInfo();
62. console.log(`Battery: ${info.batteryLevel}%`);
64. // Upload image
65. const result = await frame.uploadImage('artwork.jpg', 'My Artwork');
66. console.log(`Uploaded! Image ID: ${result.id}`);

---

Use Cases

1. Automated Weather Art

Display art that matches the weather:

1. import requests
2. from PIL import Image
4. def get_weather_art(weather_condition):
5. # Generate or fetch weather-appropriate art
6. # This could use an AI API, weather APIs, etc.
7. pass
9. def update_frame_with_weather(frame, weather_condition):
10. art_path = get_weather_art(weather_condition)
11. frame.upload_image(art_path, name=f"weather-{weather_condition}.jpg")
13. # Run every morning
14. frame = KoKonnaFrame("your-api-key")
15. update_frame_with_weather(frame, "sunny")

2. Photo Album Slideshow

Create a rotating slideshow from your photo collection:

1. import os
2. import time
3. from pathlib import Path
5. def slideshow(frame, photo_dir, interval_minutes=60):
6. photos = list(Path(photo_dir).glob("*.jpg"))
8. for photo in photos:
9. frame.upload_image(str(photo))
10. time.sleep(interval_minutes * 60)
12. frame = KoKonnaFrame("your-api-key")
13. slideshow(frame, "/path/to/photos")

3. Smart Home Integration

Integrate with Home Assistant or other platforms:

1. # Home Assistant automation example
2. automation:
3. - alias: "Update Frame at Sunrise"
4. trigger:
5. - platform: sun
6. event: sunrise
7. action:
8. - service: rest_command.kokonna_upload
9. data:
10. image: "/config/art/morning.jpg"

4. AI Art Generator

Connect to AI image generation APIs:

1. import openai
3. def generate_and_display(prompt):
4. # Generate image with DALL-E
5. response = openai.Image.create(prompt=prompt, size="1024x1024")
6. image_url = response['data'][0]['url']
8. # Download and upload to frame
9. image_data = requests.get(image_url).content
10. base64_image = base64.b64encode(image_data).decode('utf-8')
12. frame = KoKonnaFrame("your-api-key")
13. # Upload directly with base64
14. # (implementation depends on your upload method)

---

Error Handling

The API returns standard HTTP status codes:

Status Code	Meaning
200	Success
404	Unknown endpoint
429	Rate limit exceeded
500	Server error (device not found, etc.)

Common Errors:

1. // Device not found
2. {
3. "message": "can not find robot <apikey>"
4. }
6. // Rate limit exceeded
7. {
8. "message": "Too many requests, please try again later."
9. }
11. // Image not found
12. {
13. "message": "image not found"
14. }

---

Best Practices

1. Image Sizing

Match your image aspect ratio to your device's screen:

1. from PIL import Image
3. def resize_for_frame(image_path, frame_width, frame_height):
4. img = Image.open(image_path)
6. # Calculate target ratio
7. target_ratio = frame_width / frame_height
8. current_ratio = img.width / img.height
10. # Crop to match
11. if current_ratio > target_ratio:
12. # Image is too wide
13. new_width = int(img.height * target_ratio)
14. left = (img.width - new_width) // 2
15. img = img.crop((left, 0, left + new_width, img.height))
16. else:
17. # Image is too tall
18. new_height = int(img.width / target_ratio)
19. top = (img.height - new_height) // 2
20. img = img.crop((0, top, img.width, top + new_height))
22. # Resize to exact dimensions
23. img = img.resize((frame_width, frame_height), Image.LANCZOS)
24. return img

2. Rate Limit Management

Implement request queuing:

1. import time
2. from collections import deque
4. class RateLimitedClient:
5. def __init__(self, api_key, max_requests=20, per_minutes=1):
6. self.frame = KoKonnaFrame(api_key)
7. self.requests = deque()
8. self.max_requests = max_requests
9. self.per_minutes = per_minutes
11. def _wait_if_needed(self):
12. now = time.time()
13. # Remove old requests
14. while self.requests and self.requests[0] < now - self.per_minutes * 60:
15. self.requests.popleft()
17. # Wait if at limit
18. if len(self.requests) >= self.max_requests:
19. sleep_time = self.requests[0] + self.per_minutes * 60 - now
20. time.sleep(sleep_time)
22. self.requests.append(now)

3. Battery Optimization

Check device status before uploads:

1. def smart_upload(frame, image_path):
2. info = frame.get_device_info()
4. if not info['online']:
5. print("Device is offline, skipping upload")
6. return False
8. if info['batteryLevel'] < 20 and not info['isCharging']:
9. print("Battery low, skipping upload")
10. return False
12. return frame.upload_image(image_path)

---

Conclusion

The KoKonna OpenAPI provides a simple yet powerful way to integrate your e-ink art frame into any workflow or application. With just a few API calls, you can:

• Monitor your frame's status
• Upload and display custom artwork
• Build automated art curation systems
• Create smart home integrations

Whether you're a hobbyist building a personal project or a developer creating commercial integrations, the KoKonna OpenAPI gives you the tools to make your art frame truly smart.

---

Resources

• API Documentation: kokonna.art/pages/openapi
• KoKonna Website: kokonna.art
• Support: support@kokonna.art

---

Have questions or built something cool? We'd love to hear from you! Reach out at support@kokonna.art or tag us on Instagram @KoKonna365.