颜色转换与配色工具

正常 NEW

完整的颜色工具 API: HEX / RGB(A) / HSL(A) / HSV(HSB) / HWB / CMYK / XYZ / Lab / LCH / Oklab / Oklch / Display-P3 / sRGB / CSS4 颜色名互转, 并提供 WCAG 对比度、CIEDE2000 最近色、调色板生成、色盲模拟、alpha 合成与 sRGB/Oklab 混合。纯本地算法, 不依赖数据库、Redis 或外部 HTTP。

协议：HTTP 格式：JSON 版本：v1.0.0日调用量：1268次

¥ 0.002 / 次

按次计费

健康检查

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/color/ping JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.name	string	-
data.version	string	-
data.time	string	-
data.timezone	string	-
data.endpoints	array	-
data.input_formats	array	-
data.output_keys	array	-
data.palette_types	array	-
data.simulation_types	array	-
data.named_color_count	int	-
data.max_batch	int	-
data.max_input_length	int	-

请求示例

返回示例

{"msg":"pong","code":0,"data":{"name":"颜色转换与配色工具 API","time":"2026-11-02 09:00:00","version":"1.1.0","timezone":"Asia/Shanghai","endpoints":["ping","formats","convert","info","contrast","mix","batch","palette","simulate","composite"],"max_batch":20,"output_keys":["hex","rgb","hsl","hsv","hwb","cmyk","xyz","lab","lch","oklab","oklch","p3","alpha"],"input_formats":["hex","rgb","hsl","hsv","hsb","hwb","cmyk","xyz","lab","lch","oklab","oklch","display-p3","srgb","named"],"palette_types":["complementary","analogous","triadic","tetradic","split_complementary","monochromatic","tints","shades"],"max_input_length":128,"simulation_types":["protanopia","deuteranopia","tritanopia","achromatopsia"],"named_color_count":148}}

支持的格式与颜色名

返回输入格式、输出字段、调色板类型、色盲模拟类型和完整 CSS4 颜色名清单。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/color/formats JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.input_formats	array	-
data.output_keys	array	-
data.palette_types	array	-
data.simulation_types	array	-
data.named_colors	array	-
data.notes	array	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"notes":["色相自动归一化到 0-360, 支持 deg 后缀","最近颜色名使用 CIEDE2000, 颜色名为 148 个 CSS4 名称 (含别名)"],"output_keys":["hex","rgb","hsl","hsv","hwb","cmyk","xyz","lab","lch","oklab","oklch","p3","alpha"],"named_colors":[{"hex":"#F0F8FF","name":"aliceblue"},{"hex":"#FAEBD7","name":"antiquewhite"}],"input_formats":[{"name":"hex","note":"3/4/6/8 位, # 可省略; 4/8 位含 alpha","examples":["#F80","#FF8800","#FF880080"]},{"name":"rgb","note":"分量 0-255 或百分比, 支持斜杠语法","examples":["rgb(255, 136, 0)","rgba(255, 136, 0, 0.5)"]}],"palette_types":["complementary","analogous","triadic","tetradic","split_complementary","monochromatic","tints","shades"],"simulation_types":["protanopia","deuteranopia","tritanopia","achromatopsia"]}}

颜色格式转换

把任意支持的颜色输入转换为指定格式。不传 to 时返回全部 13 个输出字段。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/convert JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
value	string	是	颜色字符串
to	string	否	输出字段, 逗号/空格分隔; 传 all 等同不传

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.input	string	-
data.input_format	string	-
data.colors	object	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"input":"#FF8800","colors":{"p3":{"b":0.2057,"g":0.5575,"r":0.9387,"in_gamut":true},"hex":"#FF8800","rgb":{"b":0,"g":136,"r":255},"oklch":{"c":0.1812,"h":56.5,"l":0.7442}},"input_format":"hex"}}

完整色值信息

返回颜色的全部表示、CSS 字符串、相对亮度、最佳文字颜色、CIEDE2000 最近颜色名和黑白对比度。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/info JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
value	string	是	颜色字符串

返回参数说明

参数名	类型	说明
input	string	原始输入
input_format	string	识别出的输入格式
name	string\	null
alpha	number	0-1
hex	string	#RRGGBB
hex_short	string\	null
hex8	string\	null
rgb/hsl/hsv/hwb/cmyk/xyz/lab/lch/oklab/oklch/p3	object	各颜色空间表示
css.hex/css.rgb/css.hsl	string	可直接用于 CSS 的字符串; alpha < 1 时自动使用 rgba()/hsla()
luminance	number	WCAG 相对亮度 0-1
is_light	bool	相对亮度 > 0.179 时为 true (此时黑色文字对比度更高)
best_text_color	string	在 #000000 / #FFFFFF 中选择对比度更高的文字颜色
nearest_name	object	CIEDE2000 最近颜色名, 含 name / hex / distance / metric
contrast	object\	null
alpha_note	string	仅半透明颜色返回的说明

请求示例

返回示例

{"msg":"success","code":0,"data":{"p3":{"b":0.2057,"g":0.5575,"r":0.9387,"in_gamut":true},"css":{"hex":"#FF8800","hsl":"hsl(32, 100%, 50%)","rgb":"rgb(255, 136, 0)"},"hex":"#FF8800","hsl":{"h":32,"l":50,"s":100},"hsv":{"h":32,"s":100,"v":100},"hwb":{"b":0,"h":32,"w":0},"lab":{"a":41.7,"b":75.65,"l":69.4},"lch":{"c":86.38,"h":61.1,"l":69.4},"rgb":{"b":0,"g":136,"r":255},"xyz":{"x":0.5004,"y":0.3887,"z":0.0487},"cmyk":{"c":0,"k":0,"m":46.67,"y":100},"hex8":null,"name":null,"alpha":1,"input":"#FF8800","oklab":{"a":0.1001,"b":0.151,"l":0.7442},"oklch":{"c":0.1812,"h":56.5,"l":0.7442},"contrast":{"black":8.77,"white":2.39},"is_light":true,"hex_short":"#F80","luminance":0.388683,"input_format":"hex","nearest_name":{"hex":"#FF8C00","name":"darkorange","metric":"CIEDE2000","distance":1.24},"best_text_color":"#000000"}}

WCAG 对比度计算

计算前景色与背景色的 WCAG 2.x 对比度, 并给出 AA / AAA / UI 达标情况。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/contrast JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
fg	string	是	前景色 (文字颜色), 必须不透明
bg	string	是	背景色, 必须不透明

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.fg	string	-
data.bg	string	-
data.ratio	int	-
data.aa	object	-
data.aaa	object	-
data.ui	bool	-
data.luminance	object	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"aa":{"large":true,"normal":true},"bg":"#FFFFFF","fg":"#000000","ui":true,"aaa":{"large":true,"normal":true},"ratio":21,"luminance":{"bg":1,"fg":0}}}

颜色混合

按比例混合两个颜色, 支持 sRGB (默认) 与 Oklab 两种插值空间。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/mix JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
from	string	是	起始颜色
to	string	是	目标颜色
ratio	number	否	混合比例 0-1; 0=起始颜色, 1=目标颜色
space	string	否	srgb 或 oklab

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.from	object	-
data.to	object	-
data.ratio	float	-
data.space	string	-
data.result	object	-
data.result_css	object	-
data.best_text_color	string	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"to":{"hex":"#0000FF","input":"#0000FF"},"from":{"hex":"#FF0000","input":"#FF0000"},"ratio":0.5,"space":"srgb","result":{"...":"其余输出字段同 convert","hex":"#800080","hsl":{"h":300,"l":25.1,"s":100},"rgb":{"b":128,"g":0,"r":128},"alpha":1,"oklch":{"c":0.1935,"h":328.4,"l":0.4209}},"result_css":{"hex":"#800080","hsl":"hsl(300, 100%, 25.1%)","rgb":"rgb(128, 0, 128)"},"best_text_color":"#FFFFFF"}}

批量颜色转换

一次转换最多 20 个有效颜色。重复颜色自动去重计数, 非法项跳过并回传, 超过 20 个按顺序截断并置 truncated=true。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/batch JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
values	array\	否	-
to	string	否	每个颜色的输出字段, 同 convert

返回参数说明

参数名	类型	说明
total	int	提交的颜色总数 (含重复与非法项)
unique	int	去重后的有效颜色数量
returned	int	实际返回条目数 (最多 20)
valid	int	返回的有效条目数
invalid_count	int	非法项数量
invalid	array	非法项原文列表
duplicate_count	int	重复颜色数量 (按规范化 hex + alpha 判断)
truncated	bool	有效颜色超过 20 个时为 true
max_limit	int	批量上限 (20)
to	array\	string
list[].input	string	原始输入
list[].data	object	转换结果, 结构同 convert 的 colors

请求示例

返回示例

{"msg":"success","code":0,"data":{"to":["hex","rgb"],"list":[{"data":{"hex":"#FF0000","rgb":{"b":0,"g":0,"r":255}},"input":"#f00"},{"data":{"hex":"#0000FF","rgb":{"b":255,"g":0,"r":0}},"input":"rgb(0,0,255)"}],"total":3,"valid":2,"unique":2,"invalid":["zzz"],"returned":2,"max_limit":20,"truncated":false,"invalid_count":1,"duplicate_count":0}}

调色板生成

基于基色的 HSL 色相/明度生成调色板, 所有输出颜色均为不透明。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/palette JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
value	string	是	基色
type	string	否	complementary / analogous / triadic / tetradic / split_complementary / monochromatic / tints / shades / all
count	int	否	3-9; 影响 monochromatic / tints / shades 的颜色数量

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.base	object	-
data.type	string	-
data.count	int	-
data.colors	array	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"base":{"hex":"#FF8800","hsl":{"h":32,"l":50,"s":100},"rgb":{"b":0,"g":136,"r":255},"input":"#FF8800","oklch":{"c":0.1812,"h":56.5,"l":0.7442}},"type":"complementary","count":2,"colors":[{"hex":"#FF8800","hsl":{"h":32,"l":50,"s":100},"rgb":{"b":0,"g":136,"r":255},"role":"base","oklch":{"c":0.1812,"h":56.5,"l":0.7442}},{"hex":"#0077FF","hsl":{"h":212,"l":50,"s":100},"rgb":{"b":255,"g":119,"r":0},"role":"complement","oklch":{"c":0.2212,"h":258,"l":0.5967}}]}}

色盲模拟

使用 Machado et al. (2009) 矩阵模拟色觉缺陷, 支持 0-1 的严重程度插值。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/simulate JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
value	string	是	原始颜色
type	string	否	protanopia / deuteranopia / tritanopia / achromatopsia; 支持逗号分隔多个, all 为全部
severity	number	否	0-1; 0=原色, 1=完全模拟

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.input	string	-
data.severity	int	-
data.results	array	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"input":"#FF0000","results":[{"hex":"#6D5F00","hsl":{"h":52.3,"l":21.37,"s":100},"rgb":{"b":0,"g":95,"r":109},"type":"protanopia","oklch":{"c":0.1004,"h":99.2,"l":0.4842}},{"hex":"#A39000","hsl":{"h":53,"l":31.96,"s":100},"rgb":{"b":0,"g":144,"r":163},"type":"deuteranopia","oklch":{"c":0.1352,"h":99.9,"l":0.6503}},{"hex":"#FF000F","hsl":{"h":356.5,"l":50,"s":100},"rgb":{"b":15,"g":0,"r":255},"type":"tritanopia","oklch":{"c":0.2571,"h":28.4,"l":0.6283}},{"hex":"#7F7F7F","hsl":{"h":0,"l":49.8,"s":0},"rgb":{"b":127,"g":127,"r":127},"type":"achromatopsia","oklch":{"c":0,"h":0,"l":0.5965}}],"severity":1}}

alpha 合成

把半透明前景色合成到不透明背景上, 返回实际显示颜色及其对背景的对比度。

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/color/composite JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
fg	string	是	前景色 (可含 alpha)
bg	string	是	背景色 (必须 alpha=1)

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.fg	string	-
data.bg	string	-
data.fg_alpha	float	-
data.result	object	-
data.result_css	object	-
data.contrast	object	-
data.best_text_color	string	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"bg":"#FFFFFF","fg":"rgba(0,0,0,0.5)","result":{"p3":{"b":0.502,"g":0.502,"r":0.502,"in_gamut":true},"hex":"#808080","hsl":{"h":0,"l":50.2,"s":0},"hsv":{"h":0,"s":0,"v":50.2},"hwb":{"b":49.8,"h":0,"w":50.2},"lab":{"a":0,"b":0,"l":53.58},"lch":{"c":0,"h":0,"l":53.58},"rgb":{"b":128,"g":128,"r":128},"xyz":{"x":0.2052,"y":0.2159,"z":0.2351},"cmyk":{"c":0,"k":49.8,"m":0,"y":0},"alpha":1,"oklab":{"a":0,"b":0,"l":0.5999},"oklch":{"c":0,"h":0,"l":0.5999}},"contrast":{"aa":{"large":true,"normal":false},"bg":"#FFFFFF","fg":"#808080","ui":true,"aaa":{"large":false,"normal":false},"ratio":3.95,"luminance":{"bg":1,"fg":0.215861}},"fg_alpha":0.5,"result_css":{"hex":"#808080","hsl":"hsl(0, 0%, 50.2%)","rgb":"rgb(128, 128, 128)"},"best_text_color":"#FFFFFF"}}

产品说明

产品概述

使用场景

数据查询：快速集成颜色转换与配色工具到您的应用中

业务系统：将颜色转换与配色工具数据嵌入业务流程

开发工具：通过 API 接口获取开发工具数据

数据分析：基于颜色转换与配色工具数据进行分析和决策

费用计算

按次计费单价

¥0.002 / 次

每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。

2 次数包

预付费购买固定调用次数，折算单价与按次付费相同，用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣：个人版9折专业版8折企业版7折
量折扣：月付费调用 ≥1000 次享 2%、月付费调用 ≥10000 次享 5%、月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。

VIP 权益对比

等级	每月免费次数	本接口月免费上限	折扣	VIP 折后单价
免费版	按接口配置	—	-	¥0.002/次
个人版	5000 次	5000 次	10%	¥0.0018/次
专业版	30000 次	30000 次	20%	¥0.0016/次
企业版推荐	200000 次	200000 次	30%	¥0.0014/次

* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。

示例1：普通用户按次付费

调用 1000 次，费用 = 0.002 × 1000 = ¥2.00

示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）

调用 1000 次，折扣约 10%，费用 = 0.002 × (1 - 10%) × 1000 ≈ ¥1.80

错误码说明

本接口未定义专属错误码，调用时请参考通用错误码体系。

查看通用错误码参考

错误码	说明	解决方案
200	请求成功	-
400000	请求参数错误	检查参数名、格式与取值
401000	认证失败	检查 Authorization: Bearer 密钥是否正确、是否过期
401002	缺少 API 认证参数	请求未携带 key，请通过 URL 参数 key 或请求头 Authorization 传递密钥
402000	账户余额不足	充值后重试
403000	无访问权限	确认密钥权限、接口范围与 IP 白名单是否满足要求
404001	接口或端点不存在	检查 API 与端点的请求路径
409000	请求冲突	请稍后重试
422000	参数校验失败	检查参数格式与取值
429001	请求频率超限（QPS）	降低请求频率，或升级套餐提升额度
429002	分钟级调用频率超限	降低调用频率，或升级套餐提升额度
429003	小时级调用额度已用完	升级套餐提升额度，或整点后重试
429004	今日调用额度已用完	升级套餐提升额度，或次日重试
500000	服务器内部错误	携带响应中的 request_id 联系技术支持
502000	服务暂时不可用	稍后重试
503000	服务暂时不可用	稍后重试
504000	请求超时	稍后重试

更新日志

暂无更新日志