Open API Documentation

1) Get Device Information

Response 200 Example

{
  "firmware": "B100V050610",
  "nickname": "KoKonna",
  "lastHeartbeat": "2025-06-16T06:56:25.782Z",
  "isCharging": false,
  "batteryLevel": 100,
  "sdUsedSize": 0,
  "switchType": "queue",
  "switchMinute": 60,
  "imageId": 423,
  "coverId": null,
  "timezone": "America/Adak",
  "point": 30,
  "screenWidth": 800,
  "screenHeight": 480,
  "screenRotate": 270,
  "synced": false,
  "online": false
}

Field Notes

• firmware: Current firmware version.
• nickname: Device nickname.
• lastHeartbeat: ISO8601 timestamp of last heartbeat.
• isCharging, batteryLevel: Current power state.
• sdUsedSize: Used SD card size in bytes.
• switchType: Image change strategy (queue or random).
• switchMinute: Minutes between automatic switches when enabled.
• imageId, coverId: Current image or cover IDs.
• screenWidth, screenHeight, screenRotate: Display geometry.
• synced: True when the device has applied the latest image.
• online: Online status.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/device \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

2) Upload Image

Request Body

{
  "base64": "/9j/4AAQSkZJRgABAQEAAAAAAAD...",
  "name": "photo.jpg"
}

Rules and Behavior

• base64 is required and must be raw base64 image data. Do not include a data URL prefix such as data:image/jpeg;base64,.
• The device frame image counter is incremented and the new image becomes active.
• The name field is optional and defaults to the original filename.
• Uploaded images are automatically cropped to the device display area, so match the image ratio to the screen ratio when possible.

Success Response 200

{ "id": 789, "counter": 10 }

• id: Created image ID.
• counter: Updated frame image counter.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/upload \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"base64":"<BASE64_DATA>","name":"photo.jpg"}'

3) List Images

Success Response 200 Example

{
  "total": 2,
  "list": [
    {
      "id": 789,
      "name": "photo.jpg",
      "fileId": "abc123.jpg",
      "size": 182736,
      "type": "image/jpeg",
      "width": 800,
      "height": 480,
      "createdAt": "2026-05-14T08:00:00.000Z",
      "updatedAt": "2026-05-14T08:00:00.000Z",
      "current": true
    },
    {
      "id": 788,
      "name": "landscape.jpg",
      "fileId": "def456.jpg",
      "size": 164233,
      "type": "image/jpeg",
      "width": 800,
      "height": 480,
      "createdAt": "2026-05-13T08:00:00.000Z",
      "updatedAt": "2026-05-13T08:00:00.000Z",
      "current": false
    }
  ]
}

Field Notes

• total: Number of images belonging to the device.
• list: Images ordered by ID descending.
• current: True when the image is currently active on the device.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/listImages \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

4) Delete Image

Request Body

{ "imageId": 123 }

Rules and Behavior

• imageId is required and must belong to the device.
• The image file and database record are deleted together.
• The device frame image counter is incremented after deletion.
• If the deleted image is currently active, the server automatically switches to the next available image.
• If no images remain after deletion, the current image becomes null.

Success Response 200 Example

{
  "success": true,
  "id": 123,
  "imageId": 122,
  "counter": 11
}

Field Notes

• id: Deleted image ID.
• imageId: Current active image ID after deletion, or null if none remain.
• counter: Updated frame image counter.

Errors

• 500 with { "message": "imageId is empty" } if imageId is missing or invalid.
• 500 with { "message": "image not found" } if the image does not exist for the device.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/deleteImage \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

5) Get Image by API Key and Image ID

Path Parameters

• apikey: Device API key shown on the Frame settings page.
• imageId: Image ID returned by upload or list APIs.

Authentication

This endpoint passes the API key in the URL path, so the Authorization header is not required.

Behavior

• Returns the original stored image file for the specified device image.
• The image must belong to the device identified by apikey.
• Response content type is derived from the stored file extension, typically image/jpeg.

Success Response 200

Binary image stream.

Errors

• 404 with { "message": "image not found" } if the image ID is invalid, missing, or does not belong to the device.
• 500 with { "message": "can not find robot <apikey>" } if the API key does not match any device.

Example (curl)

curl -L "https://api.galaxyguide.cn/openapi/image/<API_KEY>/123" \
  -o image.jpg

6) Display Image by ID

Request Body

{ "imageId": 123 }

Success Response 200

{ "success": true }

Errors

• 500 with { "message": "image not found" } if the image does not exist for the device.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/displayImageById \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

7) Display Image by Name

Request Body

{ "imageName": "photo.jpg" }

Success Response 200

{ "success": true }

Errors

• 500 with { "message": "image not found" } if the image name is not found for the device.

Example (curl)

curl -X POST https://api.galaxyguide.cn/openapi/displayImageByName \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageName":"photo.jpg"}'