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 / taskAlias / 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 Loop task from the Content Studio in the Dot. App.

What Image API is for

Image API sends posters, screenshots, dashboards, or a favorite image to your device. It is best when you already have a complete visual and want the device to show that image directly.

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.

About image input

The image field is required. It must be PNG Base64 data or a full online http(s) image URL. PNG Base64 may be bare Base64 or include the data:image/png;base64, prefix; the decoded payload must be no larger than 3MB. Remote image URLs must be anonymously accessible, require no authentication or special Referer, be no longer than 2048 characters, return a response body no larger than 3MB, and return image/* content directly.

Test image URLs for debugging

The following URLs are currently anonymously accessible and return image content that can be used with the Image API:

https://placehold.co/600x400/png
https://httpbin.org/image/png

If you want to verify your own image URL first, run:

curl -I 'https://your-image-url'

In most cases, you should confirm at least:

The HTTP status code is 200
The Content-Type is image/*, such as image/png or image/jpeg

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

{
	"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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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

Required. PNG Base64 image data (bare Base64 or data:image/png;base64, prefix, decoded payload max 3MB) or full http(s) image URL (296px×152px, and remote URLs must be anonymously accessible, no longer than 2048 characters, response body max 3MB, and return image/* directly) (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.

Task alias shown in the device task list. Use it to distinguish multiple contents of the same API type. Accepts a string or number, max 100 characters. Omit it to keep the existing alias, or send an empty string/null to clear it.

Response Schema

The endpoint uses the HTTP status code to indicate the request result. The JSON response body only contains message.

Prop

Type

Human-readable response message. Both success and error responses use this field.

Status Codes

HTTP status	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 to the loop task
`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 / taskAlias / 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 Loop task from the Content Studio in the Dot. App.

What Image API is for

Image API sends posters, screenshots, dashboards, or a favorite image to your device. It is best when you already have a complete visual and want the device to show that image directly.

About API display timing

About image input

Test image URLs for debugging

The following URLs are currently anonymously accessible and return image content that can be used with the Image API:

https://placehold.co/600x400/png
https://httpbin.org/image/png

If you want to verify your own image URL first, run:

curl -I 'https://your-image-url'

In most cases, you should confirm at least:

The HTTP status code is 200
The Content-Type is image/*, such as image/png or image/jpeg

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

{
	"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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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": "{{PNG Base64 image data (max 3MB) or http(s) image URL}}",
    "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

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

The endpoint uses the HTTP status code to indicate the request result. The JSON response body only contains message.

Prop

Type

Human-readable response message. Both success and error responses use this field.

Status Codes

HTTP status	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 to the loop task
`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