Control Image Content

API Migration Notice

The legacy endpoint https://dot.mindreset.tech/api/open/image will be retired soon. To reduce migration effort, requests sent to the legacy endpoint will be automatically forwarded to the new API, but this compatibility behavior may be removed in the future.

We strongly recommend completing the following updates as soon as possible:

Update the request URL to the new endpoint: /api/authV2/open/device/:deviceId/image
Send parameters according to this document (e.g. refreshNow / image / link / border / ditherType / ditherKernel / taskKey)
If you rely on legacy response payloads or error codes, adapt your integration to the new API responses

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 you've added the Image API content to the device task from the Content Studio in the Dot. App.

About API display timing

The API's immediate display capability depends on whether the device is currently online. If the device is running on battery and asleep, the content is saved to the server first and displayed after the device wakes automatically. Read Timing to learn more.

The API rate limit is 10 requests 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

POST

/api/authV2/open/device/:deviceId/image

Generated Code

1// Generating...

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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": false,
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0
  }'

Complex image

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Image Dithering

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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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}}".

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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Troubleshooting

Endpoint

/api/authV2/open/device/:deviceId/image

Method

POST

Request Schema

Prop

Type

Whether to display the content immediately (Control display timing)

Default

true

Base64-encoded PNG image data (296px×152px) (Image to render on screen)

http/https link or URL scheme (NFC tap redirect target)

0 = white border, 1 = black border (Screen border color)

Default

Dither type (DIFFUSION, ORDERED, NONE) (Control dithering behavior)

Default

DIFFUSION

Dither algorithm (THRESHOLD, ATKINSON, BURKES, FLOYD_STEINBERG, SIERRA2, STUCKI, JARVIS_JUDICE_NINKE, DIFFUSION_ROW, DIFFUSION_COLUMN, DIFFUSION_2D) (Control dither algorithm)

Default

FLOYD_STEINBERG

When multiple Image API contents exist on the device, use this taskKey to specify which content to update and switch. You can retrieve it via the 'List Device Tasks' API. If omitted, the first Image API content is used.

Response Schema

Prop

Type

Status code

Description

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

API Migration Notice

We strongly recommend completing the following updates as soon as possible:

Update the request URL to the new endpoint: /api/authV2/open/device/:deviceId/image
Send parameters according to this document (e.g. refreshNow / image / link / border / ditherType / ditherKernel / taskKey)
If you rely on legacy response payloads or error codes, adapt your integration to the new API responses

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 you've added the Image API content to the device task from the Content Studio in the Dot. App.

About API display timing

The API rate limit is 10 requests 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

POST

/api/authV2/open/device/:deviceId/image

Generated Code

1// Generating...

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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshNow": false,
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0
  }'

Complex image

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Image Dithering

Enable Dithering

Error Diffusion (default)

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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}}".

Ordered Dithering

curl -X POST \
	  https://dot.mindreset.tech/api/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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/authV2/open/device/{{deviceId}}/image \
  -H 'Authorization: Bearer dot_app_UlSpzXNEXhYZIAFakHLCkMVVBLbsBIWxaRMVaJZGUOYKhDoDRZwLLvLujAIwQxbY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "{{base64-encoded PNG image data}}",
    "link": "https://dot.mindreset.tech",
    "border": 0,
    "ditherType": "NONE"
  }'

Whether to display the content immediately (Control display timing)

Default

true

Base64-encoded PNG image data (296px×152px) (Image to render on screen)

http/https link or URL scheme (NFC tap redirect target)

0 = white border, 1 = black border (Screen border color)

Default

Dither type (DIFFUSION, ORDERED, NONE) (Control dithering behavior)

Default

DIFFUSION

Dither algorithm (THRESHOLD, ATKINSON, BURKES, FLOYD_STEINBERG, SIERRA2, STUCKI, JARVIS_JUDICE_NINKE, DIFFUSION_ROW, DIFFUSION_COLUMN, DIFFUSION_2D) (Control dither algorithm)

Default

FLOYD_STEINBERG

Response Schema

Prop

Type

Status code

Description

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

Control Image Content

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

Control Image Content

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