UapiProUApiPro
图像

解码并缩放图片

0次调用
2 积分/次

在 RAM 和 Flash 极其有限的设备上解码图片是一项繁重的任务。这个接口专为 IoT 和嵌入式开发设计，将复杂的图像解码和缩放操作转移到云端，直接输出适用于单片机屏幕的二进制像素流。

功能概述

此接口提供了灵活的云端图像预处理能力，帮助硬件开发者跳过繁琐的图像处理逻辑：

  • 直接推流渲染：如果选择输出纯像素流（如 RGB565），单片机收到网络数据后无需解析文件头，可直接将其写入显存，实现极低内存占用的边下边播。
  • 完美适配屏幕：无需在设备端编写裁剪或补边代码。只需传入目标屏幕的物理分辨率，接口会自动完成等比缩放、居中补色或铺满裁剪，确保最终显示画面不变形。
  • 精准内存分配：在动态缩放图片的场景下，服务端会在 HTTP 响应头中提前注入 X-Image-Width 和 X-Image-Height，方便设备在读取真实的二进制数据前进行准确的内存分配。

使用须知

  • 请求格式：无论是上传本地文件还是传递图片链接，请求体都必须使用 multipart/form-data 编码格式。
  • 网络资源获取：当您选择传递图片链接时，服务端会自动尝试获取该资源。请确保您提供的图片链接是公网直接可访问的，且不需要任何形式的登录鉴权。

查询参数

width
integer可选

目标宽度，单位是像素。可以单独传，也可以和 height 一起传。与 max_width、max_height 互斥。

height
integer可选

目标高度，单位是像素。可以单独传，也可以和 width 一起传。与 max_width、max_height 互斥。

max_width
integer可选

最大宽度，单位是像素。只有在不传 width、height 时才生效，会按原比例缩放。

max_height
integer可选

最大高度，单位是像素。只有在不传 width、height 时才生效，会按原比例缩放。

format
string可选

输出格式。可以传 bmp、rgb565 或 rgb888，不传时默认是 bmp。

color_mode
string可选

BMP 输出的颜色模式。只有在 format=bmp 时才生效，可以传 RGB565 或 RGB888，不传时默认是 RGB888。

fit
string可选

缩放模式。可以传 contain、cover 或 fill，不传时默认是 contain。当传 cover 或 fill 时，width 和 height 都要传。

background
string可选

背景色。可以传 black、white 或 #RRGGBB，不传时默认是 black。

请求体

包含图片来源的表单数据。file 和 url 至少传一个；如果同时传，优先使用 file。

file
file可选

要处理的图片文件。这个接口适合直接上传 JPG、JPEG、PNG、WebP、BMP 等常见格式。

url
string可选

要处理的图片链接。适合不方便直接上传文件时使用。

响应

200 / 请求成功

处理成功，直接返回图片二进制数据。format=bmp 时返回 BMP 图片数据，format=rgb565 或 rgb888 时返回原始二进制像素数据。

格式 1image/bmp
图片响应说明
Response · Image/BMP
这是什么

接口返回的是图片的二进制数据流，而非 JSON 对象。客户端在接收到响应后，需要将其作为图片文件进行解析和处理。

前端展示方案

在浏览器环境中，最标准的做法是将响应体读取为 Blob 对象，并通过 URL.createObjectURL 生成一个临时的本地访问地址，最后将其赋值给 <img> 标签。为了避免内存泄漏，建议在图片加载完成后释放该 URL。

TYPESCRIPT
Node.js 服务端保存方案

如果是在 Node.js 环境中调用该接口，可以将响应转换为 ArrayBuffer，再转为 Buffer 并写入本地文件系统。

TYPESCRIPT
格式 2application/octet-stream
纯像素二进制流响应说明
Response · Binary
这是什么

当请求参数指定 format=rgb565 或 format=rgb888 时，接口将返回纯像素的二进制数据流。

与常见的 PNG 或 JPEG 图片不同，这种纯像素流没有任何文件头信息，例如尺寸、调色板、压缩字典等。它是专为 RAM 和 Flash 资源极其有限的 IoT 设备，例如 ESP32、Arduino 等单片机设计的，设备在接收到网络数据包后，无需进行任何解码操作，即可直接将数据按字节写入屏幕的显存（Framebuffer）中，实现极低内存占用的“边下边播”。

由于纯像素流本身不包含尺寸信息，服务端会在 HTTP 响应头（Headers）中提前注入图片的真实物理分辨率。客户端在读取实际的 Body 数据前，可以通过读取 Header 提前进行精准的内存分配：

  • X-Image-Width: 处理后的实际图片宽度（像素）
  • X-Image-Height: 处理后的实际图片高度（像素）
方案一：前端 Web 调试与可视化预览 (Canvas)

由于浏览器无法通过 <img> 标签直接渲染无文件头的纯像素流，如果您需要在 Web 前端管理控制台中调试或预览该接口返回的 RGB565 数据，需要使用 ArrayBuffer 手动解析像素，并绘制到 <canvas> 画布上。

TYPESCRIPT
方案二：Node.js 服务端落盘与测试

如果您在 Node.js 环境中调用该接口进行自动化测试或数据转存，可以将流直接保存为 .raw 或 .bin 文件，供后续烧录到硬件或使用专业图像查看器，例如 IrfanView，进行分析。

TYPESCRIPT
方案三：IoT 设备端处理逻辑（概念伪代码）

在真实的单片机，例如 ESP32，应用场景中，通常不需要将整个文件缓冲到内存中，而是通过 HTTP Client 分块读取流数据，并直接通过 SPI/I2C 总线推送到屏幕。

CPP

400 / 错误的请求

请求参数不正确，或者传入的文件和链接都不是可处理的图片内容。

JSON

413 / 请求实体太大

上传图片体积、拉取到的图片体积、源图片像素，或者输出图片像素超过限制。

JSON

500 / 服务器内部错误

服务器处理失败，例如图片编码阶段发生错误。

JSON

502 / 网关错误

图片下载失败，或者图片链接返回的不是可识别的图片内容。

JSON

503 / 服务不可用

当前图片处理任务过多，或者暂时无法获取图片。

JSON

504 / 网关超时

获取图片超时。

JSON
上一篇图片转 Base64
下一篇SVG转图片