健康检查

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

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

请求参数

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

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.version	string	-
data.time	string	-

请求示例

返回示例

{"msg":"pong","code":0,"data":{"time":"2026-11-02 10:44:12","version":"1.2"}}

能力清单

返回可生成/解析版本、输出格式、生成/批量上限与时间戳说明。

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

GET http://www.shujuyu.cn/v1/api/uuid/stats JSON

请求参数

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

返回参数说明

参数名	类型	说明
code	int	-
msg	string	-
data	object	-
data.generate_versions	array	-
data.name_based_versions	array	-
data.namespaces	array	-
data.generate_methods	array	-
data.parse_methods	array	-
data.parse_versions	array	-
data.strict_validation	bool	-
data.formats	array	-
data.max_generate_count	int	-
data.max_parse_batch	int	-
data.timestamp_versions	array	-
data.timestamp_note	string	-
data.v7_ordering	string	-
data.generate_cache	string	-
data.parse_cache	string	-
data.random_source	string	-
data.timezone	string	-

请求示例

返回示例

{"msg":"success","code":0,"data":{"formats":["canonical","compact","urn","braces"],"timezone":"UTC","namespaces":["dns","url","oid","x500"],"parse_cache":"no-store","v7_ordering":"same-ms 12-bit sequence; monotonic within one process/request, not across processes","parse_methods":["POST","GET"],"random_source":"random_bytes (CSPRNG)","generate_cache":"no-store","parse_versions":[1,2,3,4,5,6,7,8],"timestamp_note":"v1/v6: 100ns since 1582-10-15 UTC; v7: Unix ms; output ISO 8601 UTC","max_parse_batch":50,"generate_methods":["POST","GET"],"generate_versions":[3,4,5,7],"strict_validation":true,"max_generate_count":100,"timestamp_versions":[1,6,7],"name_based_versions":[3,5]}}

生成 UUID

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

POST http://www.shujuyu.cn/v1/api/uuid/generate JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
version	int	否	生成版本: 3 / 4 / 5 / 7
count	int	否	生成数量, 1-100; 超过 100 返回 4002; 名称型 (3/5) 只能为 1
format	string	否	输出格式: canonical / compact / urn / braces
uppercase	bool	否	十六进制是否大写; 1/true/yes/on 为真 (URN 前缀保持 urn:uuid:)
namespace	string	是	命名空间: dns / url / oid / x500 或自定义 UUID
name	string	是	名称输入, 最长 512 字符

返回参数说明

参数名	类型	说明
version	int	本次生成的版本
count	int	实际生成数量
format	string	实际输出格式
uppercase	bool	十六进制是否大写
deterministic	bool	名称型 (v3/v5) 为 true, 相同输入结果恒定
namespace	string	名称型回显命名空间 (非名称型不返回)
name	string	名称型回显名称 (非名称型不返回)
list[].uuid	string	按 format 输出的 UUID 字符串
list[].version	int	版本号
list[].version_name	string	版本名称
list[].variant	string	变体名称
list[].timestamp	string\	null
list[].timestamp_unix_ms	int\	null

请求示例

返回示例

{"msg":"success","code":0,"data":{"list":[{"uuid":"cfbff0d1-9375-5685-968c-48ce8b15ae17","variant":"RFC 4122","version":5,"timestamp":null,"version_name":"v5 (SHA-1 name-based)","timestamp_unix_ms":null}],"name":"example.com","count":1,"format":"canonical","version":5,"namespace":"dns","uppercase":false,"deterministic":true}}

解析 / 规范化 UUID

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

POST http://www.shujuyu.cn/v1/api/uuid/parse JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
uuid	string	是	支持 canonical / compact / braces / urn 四种写法, 最长 128 字符
strict	bool	否	1/true/yes/on 时, 非 RFC 版本/变体返回 4002 (Nil/Max 放行)

返回参数说明

参数名	类型	说明
input	string	原始输入 (已 trim)
input_format	string	输入写法: canonical / compact / braces / urn
valid	bool	是否格式合法; 格式非法时接口返回 4002
strict	bool	本次是否启用 strict 校验
uuid/canonical	string	标准 36 位小写形式
compact	string	32 位无连字符形式
uppercase	string	36 位大写形式
urn	string	urn:uuid: 形式
braces	string	花括号形式
hex	string	32 位十六进制
version	int	版本号 0-15
version_name	string	版本名称; Nil/Max UUID 显示对应名称
variant	string	NCS / RFC 4122 / Microsoft / Future
variant_code	string	变体高半字节 (如 0xA)
is_nil	bool	是否为 Nil UUID
is_max	bool	是否为 Max UUID
is_rfc4122	bool	是否为 RFC 4122/9562 规范 UUID (含 Nil/Max)
timestamp	string\	null
timestamp_unix_ms	int\	null
timestamp_unix_100ns	int\	null
timestamp_sub_ms_100ns	int\	null
timestamp_precision	string\	null
node	string\	null
clock_seq	int\	null

请求示例

返回示例

{"msg":"success","code":0,"data":{"hex":"550e8400e29b41d4a716446655440000","urn":"urn:uuid:550e8400-e29b-41d4-a716-446655440000","node":null,"uuid":"550e8400-e29b-41d4-a716-446655440000","input":"550e8400-e29b-41d4-a716-446655440000","valid":true,"braces":"{550e8400-e29b-41d4-a716-446655440000}","is_max":false,"is_nil":false,"compact":"550e8400e29b41d4a716446655440000","variant":"RFC 4122","version":4,"canonical":"550e8400-e29b-41d4-a716-446655440000","clock_seq":null,"timestamp":null,"uppercase":"550E8400-E29B-41D4-A716-446655440000","is_rfc4122":true,"input_format":"canonical","variant_code":"0xA","version_name":"v4 (random)","timestamp_unix_ms":null,"timestamp_precision":null}}

批量解析

uuids 为字符串数组, 1-50 条

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

POST http://www.shujuyu.cn/v1/api/uuid/parse-batch JSON

请求参数

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

返回参数说明

参数名	类型	说明
total	int	提交总数
valid	int	解析成功数量
invalid	int	解析失败数量
strict	bool	本次是否启用 strict 校验
version_counts	object	成功项按版本统计, 如 {"4":2,"7":1}
list[].index	int	原始数组下标
list[]	object	成功项结构同 /parse; 失败项含 input / valid=false / error

请求示例

返回示例

{"msg":"success","code":0,"data":{"list":[{"...":"同 /parse","uuid":"550e8400-e29b-41d4-a716-446655440000","index":0,"input":"550e8400-e29b-41d4-a716-446655440000","valid":true,"variant":"RFC 4122","version":4,"input_format":"canonical"},{"error":"UUID 格式非法 (支持 canonical / compact / {braces} / urn:uuid:)","index":1,"input":"bad","valid":false}],"total":2,"valid":1,"strict":false,"invalid":1,"version_counts":{"4":1}}}

产品说明

产品概述

独立 UUID 工具服务: 生成 v3/v5 (名称型, 确定性) / v4 (随机) / v7 (Unix 毫秒时间有序, 同毫秒内单调递增), 解析/规范化 v1-v8 UUID (可选 strict 校验), 识别版本/变体, 提取 v1/v6/v7 时间戳 (含精确 100ns) 与 v1/v6 node/clock_seq。零数据库、零外部请求, 随机源为 random_bytes (CSPRNG), 时区统一 UTC。

使用场景

数据查询：快速集成 UUID 生成与解析到您的应用中

业务系统：将 UUID 生成与解析数据嵌入业务流程

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

数据分析：基于 UUID 生成与解析数据进行分析和决策

费用计算

按次计费单价

¥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	请求超时	稍后重试

更新日志

暂无更新日志