首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · 图片信息提取接口接入指南

数据鱼API · 图片信息提取接口接入指南

原创
作者头像
用户12862874
发布于 2026-11-20 21:59:47
发布于 2026-11-20 21:59:47
200
举报

接口简介

「图片信息提取」是数据鱼API平台提供的图片元信息解析接口,Base 路径 /api/imgopt,共 4 个端点。调用方把图片内容以 Base64 形式提交,接口在服务端解码并返回该图片的格式与基本信息,适合在上传校验、素材入库与批量盘点环节做轻量的图片识别。

接口的能力定位是「取信息」而非「改图片」:/stats 的 features 只列出 info_extraction,没有压缩、裁剪、转码类能力;supported 列出 JPG、PNG、GIF、WebP 四种格式。业务端点 /info 同时提供 GET 与 POST,参数只有 data 一个,承载 Base64 编码后的图片内容。

与按图片地址取色的接口不同,这里要求调用方自己完成读取与编码,服务端不发起外部下载。这种方式不依赖图片的公网可达性,私有图片、临时文件都能处理,代价是请求体随图片体积膨胀,且 GET 方式的长度限制会把大图挡在门外。数据鱼API为此保留了 POST 通道,批量与较大图片应优先走 POST。

文档没有给出 /info 的成功响应样例与字段清单,只记录了失败时的行为:输入不是合法 Base64 时返回 HTTP 400 与 code=4002,msg 为「参数或输入不合法: Invalid base64」。因此返回结构需要在接入阶段以真实图片实测确认。

端点总览

方法

路径

说明

鉴权

GET

/api/imgopt/ping

健康检查,返回服务版本

免鉴权

GET

/api/imgopt/stats

服务与数据统计,返回能力与支持格式

需要

GET

/api/imgopt/info

以 query 传 Base64 图片,返回图片信息

需要

POST

/api/imgopt/info

以 JSON 或表单传 Base64 图片,返回图片信息

需要

通用约定

鉴权使用全站统一 Key,可通过 X-API-Key 请求头或 ?api_key= 查询参数传递,/ping 免鉴权。未携带 Key 返回 4011,Key 无效返回 4013。GET 与 POST 的参数名完全一致,POST 支持 JSON body 与表单两种编码。

响应统一为 {"code":0,"msg":"success","data":{...}}。参数缺失为 4001,格式或取值非法为 4002,取值不在支持列表为 4003,目标未收录为 4004,路由不存在为 4040,方法不允许为 4050,服务内部错误为 5000/5001,上游依赖不可用为 5031/5032,且不以伪造数据代替失败。数据鱼API在该接口上的客户端错误主要集中在 4002,即 Base64 解码失败。

核心端点详解

图片信息解析

/info 接收 Base64 编码的图片数据,返回解析结果。GET 与 POST 的业务能力相同,差别只在参数承载位置与长度上限。

参数

类型

必填

默认

说明

data

string

视业务

无

图片内容的 Base64 编码字符串

api_key

string

是

无

全站统一 Key,也可放请求头

data 在参数表中被标为 string、必填性「视业务」,示例值为一个 JSON 字符串,实际语义要结合错误信息判断:服务端会对它做 Base64 解码,失败即报 Invalid base64。因此不能直接传图片二进制,也不能传文件路径或图片地址,必须先读取字节流再做 Base64 编码。是否接受带 data: 前缀的 Data URL、是否接受 URL-safe 变体,文档未说明,建议只传标准 Base64,并在编码前去掉前缀与换行。

返回体中的字段文档未给出,常见实现会包含格式、宽高、体积等信息,但具体键名与单位必须以实测为准。解析层应允许字段缺失,并把格式字段统一转成大写后与 /stats 的 supported 对照,避免大小写差异导致误判。

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

{"data": "<图片 Base64 字符串>"}
代码语言:javascript
复制
GET /api/imgopt/info?data=<URL 编码后的 Base64>

GET 方式有两个额外约束:Base64 中的 +、/、= 在查询串里有特殊含义,必须做 URL 编码;同时查询串长度受服务端与中间层限制,大图会被截断或直接拒绝。除调试外,一律推荐 POST。

服务与数据统计

/stats 不接收参数,返回 features 与 supported 两个数组,前者当前只含 info_extraction,后者列出 JPG、PNG、GIF、WebP。它适合在客户端启动时读取,用于判断某项能力是否可用、对上传控件设置 accept 白名单,从而在提交前拦掉不支持的格式,减少无效请求。

代码语言:javascript
复制
GET /api/imgopt/stats

健康检查

/ping 免鉴权、无参数,返回 version 字段,实测值为 1.0。适合作为探活与版本核对入口,配合 /stats 可在故障时快速区分「服务不可达」与「能力缺失」。

代码语言:javascript
复制
GET /api/imgopt/ping

数据与限制

支持格式为 JPG、PNG、GIF、WebP 四种,/stats 的 supported 为唯一权威列表。接口没有分页与批量参数,一次请求处理一张图片;文档未给出 Base64 长度上限、图片体积上限与像素上限,这些需要在接入前实测。

由于 GET 受 URL 长度限制,实际可用的图片体积远小于 POST。批量场景应逐个调用并控制并发,同时对同一图片内容的 Base64 结果做本地缓存,避免重复编码与重复传输。

接口未声明缓存策略与结果 TTL,图片信息属于不可变数据,调用方在内容哈希不变的前提下可长期缓存解析结果。上游依赖异常时返回 5031/5032,应作为可重试错误处理。

典型使用场景

  1. 上传组件在提交前调用 /info,校验图片格式是否在白名单内,并把宽高写入元数据表。
  2. 素材库做批量盘点,遍历对象存储中的图片,逐张解析并补齐格式与尺寸字段。
  3. 内容审核链路先解析图片信息,把异常格式或损坏文件提前挡在下游处理之前。
  4. 客户端启动时读取 /stats,动态生成文件选择器的格式过滤条件。

注意事项

data 的必填性标注为「视业务」,但错误信息表明它是核心输入:不传或编码不合法都会失败。接入方应把它当作事实上的必填参数处理,先做本地 Base64 编码与合法性自检,再发起请求。

Base64 编码方式容易出错。读取文件时必须按二进制模式打开,不能按文本模式,否则字节会被改写;编码后应移除换行符,GET 场景还要做 URL 编码。若图片来自前端 FileReader,注意结果默认带 data:image/...;base64, 前缀,直接提交可能触发解码失败,应先截取逗号后的部分。

/info 缺少成功样例,字段名无法从文档确认,属于文档薄弱点。建议先拿一张小尺寸 PNG 验证,记录真实返回结构,再编写解析代码;不要在未验证的情况下假定字段一定存在。错误 4002 的 msg 会带具体原因,可用于区分「不是 Base64」与「Base64 解出来不是图片」,但判断依据仍应是 code。

GIF 等多帧格式的返回信息是否包含帧数、是否只按首帧处理,文档未说明,接入前应实测。图片版权由调用方自行确认。

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

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

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 图片信息解析
    • 服务与数据统计
    • 健康检查
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档