Image

Decode and Scale Image

0calls
2 credits / call

Decoding images on devices with extremely limited RAM and Flash is a heavy task. This endpoint is designed for IoT and embedded development, moving complex image decoding and scaling operations to the cloud, directly outputting binary pixel streams suitable for microcontroller screens.

Overview

This endpoint provides flexible cloud-based image preprocessing capabilities, helping hardware developers skip tedious image processing logic:

  • Direct Streaming Rendering: If you choose to output pure pixel stream (such as RGB565), after receiving network data, the microcontroller can write it directly to video memory without parsing file headers, achieving streaming playback with extremely low memory usage.
  • Perfect Screen Adaptation: No need to write cropping or padding code on the device side. Just pass in the physical resolution of the target screen, the endpoint will automatically complete proportional scaling, centered padding or fill cropping, ensuring the final display image is not distorted.
  • Precise Memory Allocation: In scenarios with dynamic image scaling, the server will inject X-Image-Width and X-Image-Height into HTTP response headers in advance, allowing devices to perform accurate memory allocation before reading actual binary data.

Usage Notes

  • Request Format: Whether uploading local files or passing image links, the request body must use multipart/form-data encoding format.
  • Network Resource Retrieval: When you choose to pass image links, the server will automatically try to retrieve the resource. Please ensure that the image link you provide is directly accessible from the public internet and does not require any form of login authentication.

Query parameters

width
integeroptional

Target width, in pixels. Can be passed alone or together with height. Mutually exclusive with max_width and max_height.

height
integeroptional

Target height, in pixels. Can be passed alone or together with width. Mutually exclusive with max_width and max_height.

max_width
integeroptional

Maximum width, in pixels. Only takes effect when width and height are not passed, will scale proportionally.

max_height
integeroptional

Maximum height, in pixels. Only takes effect when width and height are not passed, will scale proportionally.

format
stringoptional

Output format. Can pass bmp, rgb565 or rgb888, defaults to bmp when not passed.

color_mode
stringoptional

Color mode for BMP output. Only effective when format=bmp, can pass RGB565 or RGB888, defaults to RGB888 when not passed.

fit
stringoptional

Scaling mode. Can pass contain, cover or fill, defaults to contain when not passed. When passing cover or fill, both width and height must be passed.

background
stringoptional

Background color. Can pass black, white or #RRGGBB, defaults to black when not passed.

Request body

Form data containing image source. At least one of file and url must be passed; if both are passed, file takes priority.

file
fileoptional

Image file to process. This endpoint is suitable for directly uploading common formats such as JPG, JPEG, PNG, WebP, BMP, etc.

url
stringoptional

Image link to process. Suitable for use when it's inconvenient to directly upload files.

Response

200 / OK

Processing successful, directly returns image binary data. Returns BMP image data when format=bmp, returns raw binary pixel data when format=rgb565 or rgb888.

Format 1image/bmp
Format 2application/octet-stream

400 / Bad Request

Request parameters are incorrect, or the uploaded file and link are not processable image content.

JSON

413 /

Uploaded image size, fetched image size, source image pixels, or output image pixels exceed the limit.

JSON

500 / Internal Server Error

Server processing failed, such as an error during image encoding.

JSON

502 / Bad Gateway

Image download failed, or the image link did not return recognizable image content.

JSON

503 / Service Unavailable

Too many current image processing tasks, or unable to fetch images temporarily.

JSON

504 / Gateway Timeout

Image fetching timed out.

JSON