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

图片调色板 API 接口文档(数据鱼API)

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

接口简介

「图片调色板」是数据鱼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 下可能包含颜色数组及每个颜色的十六进制值或分量值,具体字段名与顺序需以实测为准。解析时应做类型兼容:颜色值可能带井号也可能不带,可能为大写或小写,可能额外附带占比、名称等字段,这些都应在适配层归一化。

代码语言:javascript
复制
GET /api/image-palette/extract?url=<图片绝对地址>&count=5
代码语言:javascript
复制
POST /api/image-palette/extract
Content-Type: application/json

{"url": "<图片绝对地址>", "count": "5"}

健康检查

/ping 不接收参数,免鉴权,返回 version 字段,实测值为 1.0.0。它适合放在部署脚本与监控探针中,用于确认服务与路由已就绪,也便于把版本号写进日志,定位「同一请求在不同版本下结果不同」的问题。

代码语言:javascript
复制
GET /api/image-palette/ping

数据与限制

文档未给出 count 的上限、图片体积上限、支持格式清单与缓存 TTL,这些都属于需要在接入前实测确认的项目。可以确定的是:每次请求只处理一张图片,没有批量参数;GET 与 POST 共用同一套参数;url 为唯一必填业务参数。

由于取色依赖服务端下载图片,处理耗时与图片体积、网络状况相关,批量任务应控制并发并设置超时与重试。接口未声明结果缓存,同一图片重复请求会重复计算,调用方应在本地按图片地址与 count 组合做缓存,命中时直接复用色卡。

典型使用场景

  1. 设计工具在用户上传参考图后提取主色,生成可复制的色卡与十六进制色值列表。
  2. 电商运营批量分析商品主图配色,统计品类常用的色调分布。
  3. 壁纸、主题类应用根据图片自动生成配套的界面强调色。
  4. 内容平台为文章封面自动生成占位背景色,减少首屏空白与布局跳动。

注意事项

count 是本接口最容易踩坑的参数。文档标注类型为 string,示例值 CN 与数量语义无关,必填性写为「视业务」,三处信息互相矛盾。稳妥做法是:不传 count 先取默认调色板;需要指定数量时传数字字符串并验证返回颜色个数是否符合预期;若返回 4002 或 4003,回退到默认调用。

code=500 需要特别处理。它既可能表示图片无法下载,也可能表示图片格式不受支持,仅凭 msg「无效的图片格式」无法区分。客户端应分别探测地址可达性与内容类型,避免把网络问题误判为格式问题。通用错误码表中的 5000/5001 与此处的 500 不是同一层级,重试策略应区别对待:500 通常重试无效,应更换图片或提示用户。

url 传入的地址必须能被服务端访问,携带登录态、临时签名或内网地址的图片会失败。文章示例中的 <图片绝对地址> 为占位符,实际调用需替换为真实地址,且不要在其中附加未编码的查询串。图片版权与使用授权由调用方自行确认,接口只做颜色统计,不改变原图。

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

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

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