「图片调色板」是数据鱼API平台提供的取色接口,Base 路径 /api/image-palette,共 3 个端点。调用方提交一张图片的地址,接口返回该图片的调色板数据,用于生成色卡、提取主色、做配色分析或为界面主题选取基准色。
接口只有两类端点:/ping 用于健康检查并返回服务版本,/extract 承担全部取色逻辑,同时提供 GET 与 POST 两种提交方式,参数名一致,POST 可走 JSON body 或表单。这种「一个业务端点加一个探活端点」的形态适合嵌入构建流水线与批处理脚本,调用路径短,无分页与批量概念。
取色在服务端完成,调用方不需要上传二进制文件,只需提供可被服务端访问的图片地址。该设计降低了客户端依赖,但也意味着图片必须对服务端可达:内网地址、需要鉴权的私有存储、防盗链严格的图床都可能取色失败。
文档没有披露取色算法、色彩空间与输出字段结构,图片解码失败时的实测表现为 HTTP 500 与 code=500,msg 为「无效的图片格式」。数据鱼API在该接口上未提供返回样例,接入时应以小样本先行验证,再固化解析逻辑。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/image-palette/ping | 健康检查,返回服务版本 | 免鉴权 |
GET | /api/image-palette/extract | 按图片地址提取调色板,参数走 query | 需要 |
POST | /api/image-palette/extract | 同一能力的 POST 形式,参数走 body | 需要 |
鉴权使用全站统一 Key,可放在 X-API-Key 请求头,也可用 ?api_key= 查询参数传递;/ping 免鉴权。未携带 Key 返回 4011,Key 无效返回 4013。
成功响应统一为 {"code":0,"msg":"success","data":{...}},调色板结果位于 data 内。参数缺失返回 4001,格式或取值非法返回 4002,路由不存在返回 4040,方法不允许返回 4050,服务内部错误返回 5000/5001,上游依赖不可用返回 5031/5032 且不返回伪造数据。数据鱼API的 extract 端点对无法解码的图片返回 code=500,该码不在通用错误表中,属于端点级错误,客户端需要单独兜底。
/extract 接收图片地址,返回从该图片中提取的调色板。GET 与 POST 能力等价,参数名相同,GET 适合单次调试与脚本拼接,POST 适合参数较多或被调用方统一走 JSON 的场景。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
url | string | 是 | 无 | 目标图片地址,需服务端可访问 |
count | string | 视业务 | 无 | 取色数量,文档仅标注类型与「见示例」,未给出取值范围 |
api_key | string | 是 | 无 | 全站统一 Key,也可放请求头 |
url 必须指向真实的图片资源,传网页地址、空地址或服务端无法解码的内容都会落到「无效的图片格式」,返回 code=500。count 的文档描述非常薄:类型被标为 string,必填性写作「视业务」,示例值为 CN,与取色数量的常见语义不符,可以判断文档在该参数上未做有效校验说明。接入时建议先省略 count 取默认结果,确认字段后再尝试传整数,并把「不支持该参数」视为可降级情形,不要让它阻断主流程。
返回结构在文档中缺失,data 下可能包含颜色数组及每个颜色的十六进制值或分量值,具体字段名与顺序需以实测为准。解析时应做类型兼容:颜色值可能带井号也可能不带,可能为大写或小写,可能额外附带占比、名称等字段,这些都应在适配层归一化。
GET /api/image-palette/extract?url=<图片绝对地址>&count=5POST /api/image-palette/extract
Content-Type: application/json
{"url": "<图片绝对地址>", "count": "5"}/ping 不接收参数,免鉴权,返回 version 字段,实测值为 1.0.0。它适合放在部署脚本与监控探针中,用于确认服务与路由已就绪,也便于把版本号写进日志,定位「同一请求在不同版本下结果不同」的问题。
GET /api/image-palette/ping文档未给出 count 的上限、图片体积上限、支持格式清单与缓存 TTL,这些都属于需要在接入前实测确认的项目。可以确定的是:每次请求只处理一张图片,没有批量参数;GET 与 POST 共用同一套参数;url 为唯一必填业务参数。
由于取色依赖服务端下载图片,处理耗时与图片体积、网络状况相关,批量任务应控制并发并设置超时与重试。接口未声明结果缓存,同一图片重复请求会重复计算,调用方应在本地按图片地址与 count 组合做缓存,命中时直接复用色卡。
count 是本接口最容易踩坑的参数。文档标注类型为 string,示例值 CN 与数量语义无关,必填性写为「视业务」,三处信息互相矛盾。稳妥做法是:不传 count 先取默认调色板;需要指定数量时传数字字符串并验证返回颜色个数是否符合预期;若返回 4002 或 4003,回退到默认调用。
code=500 需要特别处理。它既可能表示图片无法下载,也可能表示图片格式不受支持,仅凭 msg「无效的图片格式」无法区分。客户端应分别探测地址可达性与内容类型,避免把网络问题误判为格式问题。通用错误码表中的 5000/5001 与此处的 500 不是同一层级,重试策略应区别对待:500 通常重试无效,应更换图片或提示用户。
url 传入的地址必须能被服务端访问,携带登录态、临时签名或内网地址的图片会失败。文章示例中的 <图片绝对地址> 为占位符,实际调用需替换为真实地址,且不要在其中附加未编码的查询串。图片版权与使用授权由调用方自行确认,接口只做颜色统计,不改变原图。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。