健康检查

服务存活探测

健康检查接口，用于探活并返回服务版本、已支持分类数量、批量上限与功能特性列表。本接口无需任何请求参数，成功时 msg 固定返回 pong。错误码：400000 参数错误；502000 服务暂时不可用。

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

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

请求参数

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

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息，本接口固定为 pong
data	object	业务数据
data.version	string	服务版本号，当前为 1.0
data.time	string	服务器当前时间，格式 Y-m-d H:i:s（Asia/Shanghai）
data.categories	integer	已支持的分类数量，当前为 14
data.batch_limit	integer	批量接口单次允许的最大条数，当前为 10
data.features	array	支持的功能特性列表，即 14 个分类的 key
data.features[]	string	分类 key，如 length、mass、temperature 等

请求示例

返回示例

{"msg":"pong","code":200,"data":{"time":"2026-10-22 22:49:55","version":"1.0","features":["length","mass","temperature"],"categories":14,"batch_limit":10}}

分类列表

返回全部单位分类

查询支持的换算分类。不传参数返回全部分类列表；传 category 返回该分类的完整详情；传 detail=true 时每个分类附带全部单位明细。错误码：400000 参数错误（如 category 不存在）；502000 服务暂时不可用。

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

GET http://www.shujuyu.cn/v1/api/unit/categories JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
category	string	否	指定单个分类 key（如 length、mass、temperature），只返回该分类对象；不传则返回全部分类列表。非法值返回 400000
detail	boolean	否	是否返回每个分类的完整单位明细，传 1/true/yes/on/y 视为 true，默认 false

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息，成功时为 success
data	object	业务数据；默认返回分类列表结构，传 category 时返回单个分类对象
data.total	integer	分类总数，仅列表模式返回
data.categories	array	分类列表，仅列表模式返回
data.categories[]	object	单个分类
data.categories[].category	string	分类 key
data.categories[].name	string	分类中文名
data.categories[].en	string	分类英文名
data.categories[].base_unit	string	基准单位符号
data.categories[].base_name	string	基准单位名称
data.categories[].unit_count	integer	该分类下的单位数量
data.categories[].special	string	特殊换算标记，仅 temperature（温度，受绝对零度限制）与 fuel（油耗，倒数换算）返回，其余分类不返回该字段
data.categories[].units	array	单位明细列表，仅 detail=true 时返回
data.categories[].units[]	object	单个单位
data.categories[].units[].key	string	单位标识
data.categories[].units[].name	string	单位英文名
data.categories[].units[].cn	string	单位中文名
data.categories[].units[].symbol	string	单位符号
data.categories[].units[].aliases	array	别名列表
data.categories[].units[].aliases[]	string	别名
data.categories[].units[].factor	number	相对基准单位的换算系数，特殊换算分类可能不含该字段
data.category	string	分类 key，仅 category 模式返回
data.name	string	分类中文名，仅 category 模式返回
data.en	string	分类英文名，仅 category 模式返回
data.base_unit	string	基准单位符号，仅 category 模式返回
data.base_name	string	基准单位名称，仅 category 模式返回
data.unit_count	integer	该分类下的单位数量，仅 category 模式返回
data.special	string	特殊换算标记，仅 category 模式返回；无特殊换算时为 null
data.units	array	单位明细列表，仅 category 模式返回，始终包含
data.units[]	object	单个单位
data.units[].key	string	单位标识
data.units[].name	string	单位英文名
data.units[].cn	string	单位中文名
data.units[].symbol	string	单位符号
data.units[].aliases	array	别名列表
data.units[].aliases[]	string	别名
data.units[].factor	number	相对基准单位的换算系数，特殊换算分类可能不含该字段

请求示例

返回示例

{"msg":"success","code":200,"data":{"total":14,"categories":[{"en":"Length","name":"长度","category":"length","base_name":"米 (meter)","base_unit":"m","unit_count":19},{"en":"Mass / Weight","name":"质量","category":"mass","base_name":"千克 (kilogram)","base_unit":"kg","unit_count":15},{"en":"Temperature","name":"温度","special":"temperature","category":"temperature","base_name":"开尔文 (Kelvin)","base_unit":"K","unit_count":4}]}}

单次换算

单位换算

单位换算接口，GET 与 POST 均支持，POST 时 JSON 请求体中的参数优先于 query 参数。to 支持单个单位、逗号分隔多单位（英文逗号与中文全角逗号均可）、数组以及 all 关键字。错误码：400000 参数错误（参数缺失、单位不支持、数值非数字、目标数量超过 10 等）；502000 服务暂时不可用。

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

GET http://www.shujuyu.cn/v1/api/unit/convert JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
category	string	是	分类 key，如 length、mass、temperature、area 等，完整列表见 /categories 接口
from	string	是	源单位 key 或别名，如 m、meter、米
to	string \| array	是	目标单位。支持单个单位 key、多个单位用逗号分隔（英文逗号与中文全角逗号均可）、数组形式，以及 all 关键字（返回该分类全部单位，不受数量上限约束）。非 all 时单次最多 10 个目标，超出返回 4002（无效参数）
value	number	是	待换算的数值，非数字返回 400000

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.category	string	分类
data.category_name	string	分类名称
data.from	string	来源（源货币/单位）
data.from_unit	object	源单位
data.from_unit.key	string	单位标识
data.from_unit.name	string	名称
data.from_unit.cn	string	中文名称
data.from_unit.symbol	string	单位符号
data.from_unit.aliases	array	别名列表
data.from_unit.aliases[]	string	别名
data.input	number	输入参数
data.base_unit	string	基准单位
data.base_value	number	基准值
data.results	array	结果数据
data.results[]	object	结果数据
data.results[].to	string	目标（目标货币/单位）
data.results[].to_unit	object	目标单位
data.results[].to_unit.key	string	单位标识
data.results[].to_unit.name	string	名称
data.results[].to_unit.cn	string	中文名称
data.results[].to_unit.symbol	string	单位符号
data.results[].to_unit.aliases	array	别名列表
data.results[].to_unit.aliases[]	string	别名
data.results[].value	number	值

请求示例

返回示例

{"msg":"success","code":200,"data":{"from":"m","input":100,"results":[{"to":"km","value":0.1,"to_unit":{"cn":"千米","key":"km","name":"kilometer","symbol":"km","aliases":["km","kilometer","kilometers"]}}],"category":"length","base_unit":"m","from_unit":{"cn":"米","key":"m","name":"meter","symbol":"m","aliases":["m","meter","meters"]},"base_value":100,"category_name":"长度"}}

批量换算

批量换算最多 10 条

批量单位换算接口，仅支持 POST，items 必须放在 JSON 请求体中（Content-Type: application/json）。单次最多 10 条，超出直接返回 4002 错误（不截断）；单条换算失败不中断整体，该条返回 ok=false 与 error 标识。错误码：400000 参数错误（items 缺失或为空）；502000 服务暂时不可用。

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

POST http://www.shujuyu.cn/v1/api/unit/convert-batch JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
items	array	是	换算项数组，必须放在 JSON 请求体中传递（Content-Type: application/json）；空 body 或 GET 请求均返回 400000。单次最多 10 条，超出直接返回 4002 错误（不截断）
items[].category	string	是	分类 key
items[].from	string	是	源单位 key 或别名
items[].to	string \| array	是	目标单位，支持单个单位、逗号分隔多单位（英文逗号与中文全角逗号均可）、数组以及 all（返回该分类全部单位，不受数量上限约束）；非 all 时单条最多 10 个目标，超出该条返回 ok=false、error=engine_error
items[].value	number	是	待换算的数值

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.ok	integer	成功处理的条目数
data.fail	integer	失败数量
data.list	array	数据列表
data.list[]	object	列表中的单条记录
data.list[].ok	boolean	成功处理的条目数
data.list[].index	integer	序号
data.list[].error	string	失败时的错误标识，如 engine_error；成功时不返回该字段
data.list[].result	object	计算结果
data.list[].result.from	string	来源（源货币/单位）
data.list[].result.input	number	输入参数
data.list[].result.results	array	结果数据
data.list[].result.results[]	object	结果数据
data.list[].result.results[].to	string	目标（目标货币/单位）
data.list[].result.results[].value	number	值
data.list[].result.results[].to_unit	object	目标单位
data.list[].result.results[].to_unit.cn	string	中文名称
data.list[].result.results[].to_unit.key	string	单位标识
data.list[].result.results[].to_unit.name	string	名称
data.list[].result.results[].to_unit.symbol	string	单位符号
data.list[].result.results[].to_unit.aliases	array	别名列表
data.list[].result.category	string	分类
data.list[].result.base_unit	string	基准单位
data.list[].result.from_unit	object	源单位
data.list[].result.from_unit.cn	string	中文名称
data.list[].result.from_unit.key	string	单位标识
data.list[].result.from_unit.name	string	名称
data.list[].result.from_unit.symbol	string	单位符号
data.list[].result.from_unit.aliases	array	别名列表
data.list[].result.base_value	number	基准值
data.list[].result.category_name	string	分类名称
data.total	integer	总条数
data.returned	integer	本次实际返回条数
data.max_limit	integer	允许返回的最大条数
data.truncated	boolean	保留字段，当前恒为 false（超过 10 条时直接返回 4002 错误，不会截断）
data.list[].result.from_unit.aliases[]	string	源单位别名
data.list[].result.results[].to_unit.aliases[]	string	目标单位别名

请求示例

返回示例

{"msg":"success","code":200,"data":{"ok":1,"fail":0,"list":[{"ok":true,"index":0,"result":{"from":"m","input":100,"results":[{"to":"km","value":0.1,"to_unit":{"cn":"千米","key":"km","name":"kilometer","symbol":"km","aliases":[]}}],"category":"length","base_unit":"m","from_unit":{"cn":"米","key":"m","name":"meter","symbol":"m","aliases":["m","meter","meters"]},"base_value":100,"category_name":"长度"}}],"total":1,"returned":1,"max_limit":10,"truncated":false}}

产品说明

产品概述

单位换算服务，覆盖长度、质量、温度、面积、体积、速度、时间、数据、压力、能量、功率、角度、油耗、频率共 14 个分类，支持单次与批量换算。错误码：400000 参数错误；502000 服务暂时不可用。

使用场景

数据查询：快速集成单位换算到您的应用中

业务系统：将单位换算数据嵌入业务流程

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

数据分析：基于单位换算数据进行分析和决策

费用计算

按次计费单价

¥0.001 / 次

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

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

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

2 次数包

预付费购买固定调用次数，最高可省 20%（相对按次付费），用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

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

次数包方案

方案名称	调用次数	价格	折算单价	比按次付费节省	有效期
100次调用包	100 次	¥0.1	¥0.0010/次	-	365 天
500次调用包	500 次	¥0.475	¥0.00095/次	省5%	365 天
1000次调用包	1000 次	¥0.9	¥0.0009/次	省10%	365 天
5000次调用包	5000 次	¥4.25	¥0.00085/次	省15%	365 天
10000次调用包	10000 次	¥8	¥0.0008/次	省20%	365 天

VIP 权益对比

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

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

费用计算示例

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

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

调用 1000 次，费用 = 0.001 × 1000 = ¥1.00

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

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

示例3：购买「500次调用包」次数包

支付 ¥0.475，获得 500 次调用，折算单价 ¥0.00095/次

同等次数按次付费需 ¥0.50，次数包可节省 ¥0.025

错误码说明

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

更新日志

暂无更新日志