Hydrus Network 开发者 API 详解
2025-07-10 08:06:32作者：董灵辛Dennis
概述
Hydrus Network 是一款强大的多媒体管理工具，其开发者 API 为开发者提供了与客户端交互的接口。本文将深入解析 Hydrus API 的核心概念、使用方法和最佳实践。
API 基础
请求与响应格式
Hydrus API 主要使用 UTF-8 编码的 JSON 格式进行通信：
- POST 请求和 200 OK 响应通常为 JSON 对象
- GET 请求参数需要经过 JSON 编码和 URL 编码双重处理
- 除文件/缩略图请求外，所有响应都返回 JSON 格式
错误处理
API 返回标准 HTTP 状态码：
- 400：参数缺失/无效
- 401/403/419：访问权限问题
- 500：服务器端错误
CBOR 支持
Hydrus API 支持 CBOR（简洁二进制对象表示）格式，适合需要高效传输的场景：
- POST 请求设置 Content-Type 为
application/cbor - GET 请求添加
cbor=1参数 - 使用 Accept 头可指定期望的响应格式
访问控制
访问密钥
Hydrus 使用 64 字符的十六进制访问密钥进行身份验证，可通过两种方式提供：
-
HTTP 头：
Hydrus-Client-API-Access-Key : 0150d9c4f6a6d2082534a997f4588dcf0c56dffe1d03ffbf98472236112236ae -
请求参数：
/get_files/thumbnail?file_id=452158&Hydrus-Client-API-Access-Key=0150d9c4f6a6d2082534a997f4588dcf0c56dffe1d03ffbf98472236112236ae
会话密钥
临时会话密钥系统可避免频繁使用主密钥：
- 通过
/session_key端点获取 - 有效期 24 小时（不活动时）或客户端重启时失效
- 使用
Hydrus-Client-API-Session-Key头传递
核心概念解析
文件引用参数
引用文件时可使用多种标识方式：
file_id：单个数字文件IDfile_ids：数字文件ID列表hash：单个SHA256哈希值hashes：SHA256哈希值列表
GET 请求中的列表参数需要双重编码处理：
- JSON 编码
- URL 编码
文件域参数
搜索时可指定文件域范围：
file_service_key：单个文件域file_service_keys：多个文件域联合搜索deleted_file_service_key：从指定域删除的文件deleted_file_service_keys：从多个域删除的文件
注意：联合搜索可能带来性能问题，应优先考虑单一域搜索。
服务对象详解
Hydrus 通过服务（services）管理不同功能域，服务对象包含以下核心属性：
name：用户友好的名称（可修改）type：服务类型枚举值（不可修改）service_key：服务的唯一标识（不可修改）
服务类型
主要服务类型包括：
- 0：标签仓库
- 1：文件仓库
- 2：本地文件域（如"我的文件"）
- 5：本地标签域（如"我的标签"）
- 6：星级评分服务
- 7：喜欢/不喜欢评分服务
- 10：所有已知标签（联合所有标签服务）
- 11：所有已知文件（联合所有文件服务）
- 14：回收站
- 15：所有本地文件
- 21：所有我的文件
评分服务扩展属性
评分服务包含额外元数据：
star_shape：评分图标形状（圆形、方形、星形等）min_stars/max_stars：星级评分范围
内容状态模型（CDPP）
Hydrus 使用四态模型管理内容：
- 当前（Current）：内容存在于服务中
- 已删除（Deleted）：内容已从服务移除
- 待处理（Pending）：内容等待添加到服务
- 申请中（Petitioned）：内容等待从服务移除
状态组合规则：
- 申请中内容必须同时是当前内容
- 已删除和待处理可同时存在
- 当前内容不能同时是已删除状态
最佳实践
- 服务标识：始终使用
service_key而非服务名称 - 性能优化：避免不必要的联合搜索
- 错误处理：妥善处理 419（会话过期）等状态码
- 编码规范：严格遵循参数编码要求
- 权限管理：检查每个请求的权限要求
通过深入理解这些核心概念，开发者可以构建出高效、稳定的 Hydrus 客户端应用，充分利用其强大的多媒体管理能力。
