# HDHive OpenAPI 文档

## 概述

HDHive OpenAPI 面向个人脚本、内部工具和第三方应用，提供资源查询、资源解锁、分享管理、用户信息和用量查询能力。

新版 OpenAPI 使用统一平台凭证：

- **个人 API Key**：用户自己创建，适合个人脚本和自用自动化。
- **OpenAPI 应用**：管理员创建，适合第三方应用或合作方系统。
- **用户授权 Token**：用户通过第三方应用授权后获得，代表具体用户执行业务操作。

## 基本信息

- **业务接口 Base URL**：`/api/open`
- **用户授权接口 Base URL**：`/api/public/openapi/oauth`
- **用户授权页**：`/openapi/authorize`
- **认证方式**：`X-API-Key` 必填，业务接口可附加 `Authorization: Bearer <token>`
- **响应格式**：JSON
- **权限模型**：应用 scope + 用户授权 scope + 用户身份共同决定可访问范围
- **SDK 与文档下载**：[打开 SDK 下载页](/api-docs/sdk)，可下载 Go / Python / Node SDK 和公开版 API 文档 ZIP

## 文档原则

本文档只说明接入方式、接口语义、认证流程和错误码，不展示具体 QPS 或每日额度。具体限制由管理员在「OpenAPI 策略」和「OpenAPI 应用」中配置，接入方应按 `429` 响应和 `Retry-After` 头进行退避重试。

## 目录

- **认证与授权** — API Key、用户 Token、scope、用户身份来源
- **限制与错误处理** — 429、冷却、IP 策略、额度响应头
- **通用响应格式** — 成功/错误响应结构、错误码汇总
- **接口列表** — 主要 OpenAPI 接口说明、请求参数与响应示例