首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >图片信息提取 API 接口文档(数据鱼API)

图片信息提取 API 接口文档(数据鱼API)

原创
作者头像
用户12862874
发布于 2026-11-21 22:00:38
发布于 2026-11-21 22:00:38
60
举报

接口简介

「图片信息提取」是数据鱼API平台提供的图片元信息读取接口,实际插件标识为 imgopt,Base 路径 /api/imgopt,共 4 个路由。它接收一张图片的 Base64 内容,返回宽、高、MIME 类型、通道数、位深与解码后的字节数,适合上传前校验与素材盘点。

先说明一个关键差异:本接口只做信息提取,不压缩、不缩放、不转格式、不清理元数据。插件名与常见「image-compress」叫法容易让人误以为能减小体积,但 stats 返回的 features 只有 info_extraction,没有任何输出图片或质量参数。如果目标是压缩图片,需要另找工具,不能按本文端点实现。

接口本身很轻:info 是唯一业务端点,支持 GET 与 POST;ping 用于探活,stats 返回支持格式与能力清单。所有解析都基于图片头部,不读取 EXIF 中的拍摄地点、设备与时间。

端点总览

方法

路径

说明

鉴权

GET

/api/imgopt/ping

健康检查,返回版本

文档标称免鉴权

GET

/api/imgopt/stats

返回能力与支持格式

需要

POST

/api/imgopt/info

解析 Base64 图片,返回尺寸与格式信息

需要

GET

/api/imgopt/info

与 POST 相同的解析能力,参数走查询串

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,未携带返回 4011,无效返回 4013。响应统一为 {code, msg, data},code 为 0 表示成功。4001 为缺少 data,4002 为参数或输入不合法,4003 为取值不在支持列表,4004 为查询目标未收录,4040 为路由不存在,4050 为方法不允许;5000 与 5001 为服务内部错误,5031 与 5032 表示上游依赖不可用。

POST 支持 JSON body 或表单,字段名与查询参数一致。图片 Base64 往往很长,POST 明显比 GET 合适;GET 把整段 Base64 放进 URL,容易触达代理与服务器的 URL 长度上限,也会把图片内容写进访问日志。

需要注意,文档把 ping 标为免鉴权,但同目录的鉴权中间件对所有非 OPTIONS 请求统一校验 Key。为兼容不同部署,调用 ping 时也带上 Key 更稳妥。

核心端点详解

图片信息解析(POST /info)

用途:把 Base64 图片解析为宽高、MIME 与体积等基础信息。

参数

类型

必填

说明

data

string

是

图片的 Base64 字符串,不是文件路径,也不是普通 URL

返回字段

类型

说明

width

int

图片宽度,单位像素

height

int

图片高度,单位像素

mime

string

图片 MIME 类型,如 image/jpeg

channels

int/null

颜色通道数,部分格式可能为 null

bits

int/null

每通道位深,部分格式可能为 null

size_bytes

int

Base64 解码后的原始字节数

data 必须是纯 Base64。浏览器 FileReader 的 readAsDataURL 会生成 data:image/png;base64, 前缀,直接提交通常会被判为非法 Base64;上传前应截掉逗号前的头部,只保留编码正文。Base64 长度约为原始字节数的 4/3,size_bytes 返回的是解码后大小,不是字符串长度。

示例中的响应只覆盖成功路径。invalid base64 在文档的自动化探测记录中返回 4002;当前实现也可能以 code=0 携带 data.error 的形式返回解析失败,因此调用方不能只看 HTTP 200,还要同时检查 code 与 data.error。图片格式不在支持列表、头部损坏或数据截断时,同样可能进入失败分支。

代码语言:javascript
复制
POST /api/imgopt/info?api_key=YOUR_KEY
Content-Type: application/json

{"data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..."}

其余端点要点

  • GET /info:与 POST 使用同一个处理函数,参数同样叫 data,只是从查询串读取。仅适合极小图片或调试,生产环境优先 POST。
  • GET /stats:无参数,返回 features 与 supported。当前 features 只有 info_extraction,supported 为 JPG、PNG、GIF、WebP 四种;它反映声明能力,不代表其他格式一定解析失败。
  • GET /ping:无参数,成功时 msg 为 pong,data 只有 version=1.0。文档称免鉴权,但实际部署可能统一校验 Key。
  • 没有压缩、裁剪、旋转、格式转换、EXIF 读取或元数据清理端点,端点清单中的 4 条路由已全部列出。

数据与限制

  • 能力范围:只读图片头部,返回 6 个字段;不返回文件名、文件大小以外的存储信息,也不返回拍摄设备、GPS、拍摄时间等 EXIF 字段。
  • 支持格式:stats 声明 JPG、PNG、GIF、WebP;实际解析依赖 PHP 的图像信息函数,其他格式可能被识别,但不应作为接口承诺。
  • 输入形态:仅接受 Base64 字符串,不接受 multipart 文件上传、图片 URL 或本地路径;服务端不会替调用方下载远程图片。
  • 体积限制:文档没有给出 Base64 长度、解码后大小或像素上限;限制通常来自 PHP 的 post_max_size、内存与执行时间,大图应在客户端先压缩再提交。
  • 字段完整性:channels 与 bits 在 GIF、WebP 等格式上可能缺失,返回 null;调用方应允许这两个字段为空。
  • MIME 判定:mime 来自图片头部,不看扩展名;这能识别伪装扩展名,但不能证明图片内容安全,仍需做解码与病毒扫描。
  • 无状态:接口不保存图片,也不返回可访问的图片地址;解析结果只包含本次请求的元信息。
  • 该接口属于数据鱼API平台开发工具类接口,定位是图片基础信息读取,不是图片处理或压缩服务。

典型使用场景

  • 上传前校验:读取宽高与 MIME,拦截尺寸过小、格式不符或扩展名造假的图片。
  • 素材盘点:对已有 Base64 资源批量提取尺寸、格式与字节数,生成图片清单。
  • CMS 或后台:在编辑器中提示图片实际分辨率,避免把 200 像素宽的图放到大图位。
  • 接口联调:用一张 1×1 的 PNG 快速验证 Base64 编码、鉴权与返回结构是否正确。

注意事项

  • 本接口不压缩图片。若业务目标是减小体积,应使用带 quality、max_width 或 format 参数的压缩服务;把 info 当作压缩接口会得到只有元信息、没有新图片的结果。
  • Base64 会让传输体积增加约三分之一,大图还会放大内存占用;不要在前端把几十 MB 的原图直接编码后提交,应先限制尺寸与格式。
  • 不要把 Base64 或完整响应写入日志、错误上报与埋点;图片可能包含人脸、证件、定位等敏感内容,接口不读 EXIF 不代表内容不敏感。
  • 接口不会清理 EXIF。若图片要公开发布,应在调用方完成元数据剥离,避免 GPS、设备型号与拍摄时间泄露。
  • 图片解析成功不代表文件安全。MIME 与尺寸都来自头部,可能被构造;对外提供上传能力时仍要做解码、重编码与安全检查。
  • GET /info 会把超长 Base64 放进 URL,容易超过代理与服务器限制并留下日志,除调试外应使用 POST。
  • 文档对非法输入的错误路径描述不一致,接入时应同时处理 4001、4002、code=0 但 data.error 非空以及 HTTP 非 200 的情况。
  • 数据鱼API不提供图片托管与 CDN 地址,解析完成后原图仍需由业务侧自行存储与授权访问。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 图片信息解析(POST /info)
  • 其余端点要点
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档