Image API

Quick Guide

Prerequisites

Make sure you have retrieved and saved your API key in the Dot. App;
Make sure you own at least one device and have obtained its device serial number;
Make sure your device is connected to power;
Make sure your device is connected to the network;
Make sure the device has added the Image API content.

API requests are not limited by the app’s minimum 5‑minute device interval. The API rate limit is 1 request per second. With the API, you can control device behavior and responses more flexibly.

Placeholders wrapped in ‘{{variable}}’ indicate values you must replace. Fill them with your actual values and remove the ‘{{}}’ braces.

Request Examples

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer {{API_KEY}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": {{show content immediately}},
    "deviceId": "{{device serial number}}",
    "image": "{{base64-encoded PNG image data}}",
    "link": "{{NFC tap redirect link}}",
    "border": {{edge color index}},
    "ditherType": "{{dither type}}",
    "ditherKernel": "{{dither algorithm}}"
  }'

import requests

url = "https://dot.mindreset.tech/api/open/image"
headers = {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json"
}
data = {
    "refreshNow": {{show content immediately}},
    "deviceId": "{{device serial number}}",
    "image": "{{base64-encoded PNG image data}}",
    "link": "{{NFC tap redirect link}}",
    "border": {{edge color index}},
    "ditherType": "{{dither type}}",
    "ditherKernel": "{{dither algorithm}}"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())

fetch("https://dot.mindreset.tech/api/open/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    refreshNow: {{show content immediately}},
    deviceId: "{{device serial number}}",
    image: "{{base64-encoded PNG image data}}",
    link: "{{NFC tap redirect link}}",
    border: {{edge color index}},
    ditherType: "{{dither type}}",
    ditherKernel: "{{dither algorithm}}"
  })
}).then(res => res.json()).then(console.log);

type ApiResponse = {
  code: number;
  message: string;
  result?: any;
};

fetch("https://dot.mindreset.tech/api/open/image", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    refreshNow: {{show content immediately}},
    deviceId: "{{device serial number}}",
    image: "{{base64-encoded PNG image data}}",
    link: "{{NFC tap redirect link}}",
    border: {{edge color index}},
    ditherType: "{{dither type}}",
    ditherKernel: "{{dither algorithm}}"
  })
})
  .then(res => res.json() as Promise<ApiResponse>)
  .then(data => {
    console.log(data);
  });

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://dot.mindreset.tech/api/open/image"
  payload := map[string]interface{}{
    "refreshNow": {{show content immediately}},
    "deviceId": "{{device serial number}}",
    "image": "{{base64-encoded PNG image data}}",
    "link": "{{NFC tap redirect link}}",
    "border": {{edge color index}},
    "ditherType": "{{dither type}}",
    "ditherKernel": "{{dither algorithm}}",
  }
  body, _ := json.Marshal(payload)
  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer {{API_KEY}}")
  req.Header.Set("Content-Type", "application/json")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
  respBody, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(respBody))
}

use reqwest::blocking::Client;
use serde_json::json;

fn main() {
    let client = Client::new();
    let url = "https://dot.mindreset.tech/api/open/image";
    let res = client.post(url)
        .header("Authorization", "Bearer {{API_KEY}}")
        .header("Content-Type", "application/json")
        .json(&json!({
            "refreshNow": {{show content immediately}},
            "deviceId": "{{device serial number}}",
            "image": "{{base64-encoded PNG image data}}",
            "link": "{{NFC tap redirect link}}",
            "border": {{edge color index}},
            "ditherType": "{{dither type}}",
            "ditherKernel": "{{dither algorithm}}"
        }))
        .send()
        .unwrap()
        .text()
        .unwrap();
    println!("{}", res);
}

Response Example

{
	"code": 200,
	"message": "Device Image API content switched",
	"result": {
		"message": "Device ABCD1234ABCD Image API content switched"
	}
}

Reference Usage

Simple image without immediate display

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": false,
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0
  }'

Complex image

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 1
  }'

Text image

Use common image tools (e.g., Figma, Sketch, Adobe Photoshop) to convert text to PNG, then convert it to base64 data.

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Image dithering uses specific algorithms to reduce visual noise caused by color quantization, making images appear smoother. Common algorithms include Floyd–Steinberg, Atkinson, and Sierra. On e‑ink displays, dithering can further optimize black-and-white rendering so gray-level transitions look more natural.

When using the Image API, if you do not pass the ditherType parameter, the default is the error-diffusion Floyd–Steinberg algorithm. You can also disable it or adjust the dithering type and algorithm via parameters.

Enable Dithering

Error Diffusion (default)

Error diffusion distributes each pixel’s quantization error to neighboring pixels to reduce visual noise. It handles high-contrast areas effectively, yielding rich details and smooth gray transitions. Visually, it tends to look natural with no obvious grid and smooth gradients.

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "DIFFUSION"
  }'

Supported Error-Diffusion Kernels

Different error-diffusion kernels produce different visual results. Pass the algorithm via "ditherKernel": "{{dither algorithm}}".

FLOYD_STEINBERG

ATKINSON

BURKES

SIERRA2

STUCKI

JARVIS_JUDICE_NINKE

DIFFUSION_ROW

DIFFUSION_COLUMN

DIFFUSION_2D

Ordered Dithering

Ordered dithering applies a fixed, periodic threshold matrix to image pixels, unlike error diffusion which propagates the error dynamically. It helps reduce large color patches and banding, creating a visually uniform dot pattern. Due to periodicity, ordered dithered images often show a noticeable regular grid.

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "ORDERED"
  }'

Disable Dithering

If you primarily display text images via the Image API, we recommend disabling dithering to achieve sharper text.

curl -X POST \
  https://dot.mindreset.tech/api/open/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "ABCD1234ABCD",
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Field	Type	Required	Default	Description	Purpose
`refreshNow`	`bool`	No	`true`	Whether to display the content immediately	Control display timing
`deviceId`	`string`	Yes		Device serial number	Identify the device
`image`	`string`	Yes		Base64‑encoded PNG image data (296px×152px)	Image to render on screen
`link`	`string`	No		http/https link or URL scheme	NFC tap redirect target
`border`	`number`	No	`0`	`0` = white border, `1` = black border	Screen border color
`ditherType`	`string`	No	`DIFFUSION`	Dither type (`DIFFUSION`, `ORDERED`, `NONE`)	Control dithering behavior
`ditherKernel`	`string`	No	`FLOYD_STEINBERG`	Dither algorithm (`THRESHOLD`, `ATKINSON`, `BURKES`, `FLOYD_STEINBERG`, `SIERRA2`, `STUCKI`, `JARVIS_JUDICE_NINKE`, `DIFFUSION_ROW`, `DIFFUSION_COLUMN`, `DIFFUSION2_D`)	Control dither algorithm

Response Schema

Field	Type	Description
`code`	`number`	Status code
`message`	`string`	Description
`result`	`object`	Processing data

Status Codes

code	Meaning	Description
`200`	Success	Image API content switched / Data updated but content not switched
`400`	Invalid parameters	Missing or invalid device ID Invalid image format Invalid border (must be 0 or 1) Invalid dither type Invalid dither algorithm
`403`	Forbidden	You do not have permission to operate this device
`404`	Not found	Device not found or not registered Image API content not added
`500`	Device response failure	Failed to switch Image API content

Image API

Quick Guide

Prerequisites

Request Examples

Response Example

Reference Usage

Image Dithering

Enable Dithering

Error Diffusion (default)

Supported Error-Diffusion Kernels

Ordered Dithering

Disable Dithering

Troubleshooting

Endpoint

Method

Request Schema

Response Schema

Status Codes

Contents