接口文档

01

快速开始

创建永久 Token 后，在请求头中携带 Bearer Token。

1
创建 Token
登录用户中心，在“API Token”页面创建永久访问令牌。令牌只在创建后完整显示一次。
2
选择存储策略
调用策略接口获取当前用户组可使用的 strategy_id。
3
上传图片
以 multipart/form-data 提交文件，成功后保存响应中的云端 url 和图片 key。

cURL最小上传请求

curl -X POST "http://freehg.fdpc.xyz/api/v1/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@/path/to/photo.jpg"

02

身份认证

永久 Token 可访问全部授权接口，临时 Token 只能上传。

请求头格式Authorization: Bearer YOUR_TOKEN

凭证	适用范围	说明
永久 API Token	全部 /api/v1 授权接口	支持页面显示的 `id\|原始Token` 格式，也支持直接传原始 Token。
临时上传 Token	仅 POST /upload	按数量和有效秒数批量签发，不能查询资料、图片或删除图片。
不携带 Token	访客策略与访客上传	只有管理员开启访客上传且访客用户组有可用策略时才可使用。

全站 API 开关、账号状态、用户组状态和用户组“允许 API”权限必须同时开启。Token 请仅保存在服务端，不要写入公开网页或公开仓库。

03

响应格式

业务响应统一包含 status、message 和 data。

成功HTTP 200

{
  "status": true,
  "message": "success",
  "data": {}
}

失败示例

{
  "status": false,
  "message": "存储容量不足",
  "data": null
}

参数验证失败时 HTTP 状态码为 422，并由 Laravel 返回字段级 errors；调用端应同时判断 HTTP 状态码与 status。

GET/profile获取当前用户资料

需要永久 API Token。返回账号资料、容量、已用空间、图片数量与相册数量。capacity 和 size 的单位为 KB。

请求

curl "http://freehg.fdpc.xyz/api/v1/profile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

data 示例

{
  "username": "demo",
  "name": "演示用户",
  "avatar": "https://example.com/avatar.png",
  "email": "demo@example.com",
  "capacity": 1048576,
  "size": 256.5,
  "url": "https://example.com/user/dashboard",
  "image_num": 12,
  "album_num": 2,
  "registered_ip": "203.0.113.10"
}

GET/strategies获取可用存储策略

返回当前用户组可以使用的存储策略。未传 strategy_id 上传时，系统会优先使用默认策略。

参数	位置	类型	必填	说明
`q`	Query	string	否	按策略名称模糊搜索。

data 示例

{
  "strategies": [
    {"id": 3, "name": "云端对象存储"}
  ]
}

POST/upload上传图片

Content-Type 必须为 multipart/form-data。成功响应中的 url、缩略图和 Markdown 链接会指向图片所属存储策略的实际地址。

字段	类型	必填	说明
`file`	file	是	图片文件。扩展名、MIME 和文件内容必须一致，并满足站点与用户组限制。
`strategy_id`	integer	否	存储策略 ID；必须属于当前用户组可用策略。
`album_id`	integer	否	当前账号拥有的相册 ID；访客不能使用。
`permission`	integer	否	`1` 公开，`0` 私有，默认公开；访客不能上传私有图片。
`expired_at`	date	否	未来时间。不能超过当前用户组或套餐规定的图片保存上限。

完整请求cURL

curl -X POST "http://freehg.fdpc.xyz/api/v1/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@/path/to/photo.webp" \
  -F "strategy_id=3" \
  -F "album_id=8" \
  -F "permission=1" \
  -F "expired_at=2026-08-30T12:00:00+08:00"

data 示例

{
  "key": "20260728abcdefghijkl",
  "name": "20260728abcdefghijkl.webp",
  "origin_name": "photo.webp",
  "size": 248.36,
  "mimetype": "image/webp",
  "extension": "webp",
  "width": 1920,
  "height": 1080,
  "md5": "...",
  "sha1": "...",
  "is_public": true,
  "created_at": "2026-07-28 12:00:00",
  "url": "https://storage.example.com/images/photo.webp",
  "thumbnail_url": "https://storage.example.com/images/photo.webp",
  "html": "<img src=\"...\" alt=\"photo.webp\" />",
  "bbcode": "[img]...[/img]",
  "markdown": "![photo.webp](...)",
  "markdown_with_link": "[![photo.webp](...)](...)",
  "delete_url": "https://example.com/api/v1/images/20260728abcdefghijkl"
}

上传前会执行全部安全规则

包括允许格式、MIME 校验、单图大小、剩余容量、上传频率、并发数、存储权限、图片保存时间和用户组配置的内容审查。

GET/images获取图片列表

需要永久 API Token，仅返回当前账号的图片，按创建时间倒序分页。

参数	位置	类型	默认	限制
`per_page`	Query	integer	30	最小 1，最大 100。

分页响应结构

{
  "status": true,
  "message": "success",
  "data": {
    "current_page": 1,
    "last_page": 4,
    "total": 92,
    "data": []
  }
}

DELETE/images/{key}删除图片

需要永久 API Token。只能删除当前账号拥有的图片。key 可使用上传响应中的原始 key，也兼容带扩展名的文件名。

请求

curl -X DELETE "http://freehg.fdpc.xyz/api/v1/images/20260728abcdefghijkl" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

删除会同步处理数据库记录和对应存储对象。请在业务侧二次确认，删除完成后不可通过 API 撤销。

POST/images/tokens批量创建临时上传 Token

需要永久 API Token。适合给短时上传任务或受控客户端签发只能上传图片的临时凭证。

字段	类型	必填	限制
`num`	integer	是	1-100，生成数量。
`seconds`	integer	是	1-2626560，有效秒数，最长约 30.4 天。

请求

curl -X POST "http://freehg.fdpc.xyz/api/v1/images/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"num":2,"seconds":3600}'

data 示例

{
  "tokens": [
    {
      "token": "temporary-upload-token",
      "expired_at": "2026-07-28 13:00:00"
    }
  ]
}

10

错误与限制

调用端应记录 HTTP 状态码和 message，参数错误还应读取 errors。

HTTP 状态	常见原因	处理建议
`400`	容量不足、格式不支持、存储策略无权使用、过期时间超限、内容审查拒绝或其他业务规则。	直接展示 message，并根据用户组和站点配置调整请求。
`401`	缺少授权、Token 错误、Token 失效或 Authorization 格式错误。	重新创建 Token，并确认使用 Bearer 格式。
`403`	全站 API 已关闭、用户组不允许 API、账号或用户组停用、临时 Token 越权。	联系管理员检查权限，或改用永久 Token。
`404`	图片 key 不存在，或图片不属于当前账号。	检查 key 与 Token 所属账号。
`422`	字段缺失、类型错误或参数超出取值范围。	读取响应中的 errors 字段逐项修正。
`500`	存储服务、服务器或其他未预期异常。	保存请求时间与 message，通过工单联系管理员。

11

调用示例

下面示例均使用永久 API Token。

JavaScript查询图片列表

const response = await fetch('http://freehg.fdpc.xyz/api/v1/images?per_page=30', {
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
    Accept: 'application/json'
  }
});

const result = await response.json();
if (!response.ok || !result.status) {
  throw new Error(result.message || '请求失败');
}

console.log(result.data.data);

PHP上传图片

<?php
$curl = curl_init('http://freehg.fdpc.xyz/api/v1/upload');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('/path/to/photo.jpg'),
        'permission' => 1,
    ],
]);

$result = json_decode(curl_exec($curl), true);
curl_close($curl);

if (!($result['status'] ?? false)) {
    throw new RuntimeException($result['message'] ?? '上传失败');
}

Token 管理地址：http://freehg.fdpc.xyz/user/tokens

+

站点补充说明

以下内容由本站管理员在后台页面管理中维护。

接口根地址：/api/v1

鉴权方式：Authorization: Bearer {token}

上传：POST /api/v1/upload，表单字段 file

资料：GET /api/v1/profile

策略：GET /api/v1/strategies

图片列表：GET /api/v1/images

删除：DELETE /api/v1/images/{key}