Ir directamente al contenido

API abierta

Open API Documentation

Interact with a Frame device over HTTPS using a simple, token‑based JSON API.

Base URL

https://api.galaxyguide.cn/openapi

Authentication

  • Use a Bearer token in the Authorization header.
  • The token is the device’s API key shown on the Frame’s settings page.
  • Required header:
Authorization: Bearer <API_KEY>
Content-Type: application/json

Rate Limiting

  • Limit: 20 requests per minute per device key.
  • Exceeding the limit returns HTTP 429 with:
{ "message": "Too many requests, please try again later." }

Endpoints

1) Get Device Information

  • URL: /device
  • Method: POST
  • Body: {} or omitted
  • 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/cover IDs.
  • screenWidth, screenHeight, screenRotate: Display geometry.
  • synced: True when device has applied the latest image (local counter equals server counter).
  • 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

  • URL: /upload
  • Method: POST
  • 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 like "data:image/jpeg;base64,").
  • The device’s frame image counter is incremented and the new image becomes active.
  • The name field is optional and defaults to the filename of the uploaded image.
  • Uploaded images are automatically cropped to the device's display area; please ensure the uploaded photo's aspect ratio matches the device's screen ratio.

Success response 200 example:

{ "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) Display Image by ID

  • URL: /displayImageById
  • Method: POST
  • 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}'

4) Display Image by Name

  • URL: /displayImageByName
  • Method: POST
  • 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"}'

Error Handling

  • 404 Not Found: Unknown method in URL.
{ "message": "can not find method <method_name>" }
  • 429 Too Many Requests: Rate limit exceeded.
{ "message": "Too many requests, please try again later." }
  • 500 Internal Server Error:
    • Device not found by the provided key.
    • Or other server error.
{ "message": "can not find robot <apikey>" }

or

{ "message": "<error_message>" }

Payload Size

  • Maximum request payload is 50 MB (server default). Ensure base64 uploads fit within this limit.

@kokonna365