ImgYoung
文档接口参考
接口参考

后台·图片

图片列表、详情、修改与删除

图片列表

GET
/api/admin/images

分页；普通用户只见自己的，管理员可按用户、Token、时间与关键词过滤。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Query Parameters

page?integer

页码，从 1 起；缺省 1

Range1 <= value
page_size?integer

每页条数；缺省 20，上限 100

Range1 <= value <= 100
search?string

文件名关键词

user_id?string

只看指定用户的图；仅管理员生效

token_id?integer

只看来自指定 Token 的图

Formatint64
since?string

时间范围下界（闭），UTC 文本 YYYY-MM-DD HH:MM:SS

until?string

时间范围上界（开），UTC 文本 YYYY-MM-DD HH:MM:SS

exempt?1

为 1 时只看已清理豁免的图

Value in1

Response Body

图片分页

application/json
  1. response
items*array<>
total*integer

过滤后的总条数

Formatint64
curl -X GET 'http://localhost:8721/api/admin/images'
{  "items": [    {      "id": "string",      "url": "string",      "user_id": "string",      "token_id": 0,      "token_name": "string",      "file_name": "string",      "mime": "string",      "size": 0,      "width": 0,      "height": 0,      "sha256": "string",      "expire_at": "string",      "ttl_seconds": 0,      "last_access_at": "string",      "access_count": 0,      "pending_cleanup": true,      "cleanup_exempt": true,      "created_at": "string",      "ref_count": 0    }  ],  "total": 0}

批量删除图片

POST
/api/admin/images/batch-delete

逐张按单删的权限与级联语义处理，单张失败不中断其余；他人图按不存在处理。单次至多 100 个 ID。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body
ids*array<string>

待删除的短 ID

Items1 <= items <= 100

Response Body

逐张结果

application/json
  1. response
deleted*integer

成功删除张数

failed*array<>

失败明细；全部成功时为空数组

curl -X POST 'http://localhost:8721/api/admin/images/batch-delete' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "ids": [    "string"  ]}'
{  "deleted": 0,  "failed": [    {      "id": "string",      "error": "string"    }  ]}

图片详情

GET
/api/admin/images/{id}

列表项字段之外附带各渠道的副本状态；普通用户查他人图一律 404，不泄露存在性。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*string

图片短 ID

Response Body

图片详情

application/json
  1. response

图片列表项

id*string

短 ID

url*string

公开访问路径，相对站点根

user_id*string

归属用户

token_id*|

上传来源 Token；null 表示后台上传或来源 Token 记录已删除

Formatint64
token_name*|

来源 Token 用途名；null 同 token_id

file_name*string

原始文件名

mime*string

真实 MIME

size*integer

存储字节

Formatint64
width*integer
Formatint64
height*integer
Formatint64
sha256*string

内容哈希

expire_at*|

到期时刻；null 表示永久

ttl_seconds*|

有效时长（秒），访问续期按此顺延；null 表示永久

Formatint64
last_access_at*|

最近公开访问；null 表示从未

access_count*integer

累计公开访问次数，活跃度落库周期粒度

Formatint64
pending_cleanup*boolean

是否在待清理列表

cleanup_exempt*boolean

是否清理豁免

created_at*string

上传时刻

ref_count*integer

物理图引用计数（同图去重共享）

Formatint64
replicas*array<>

物理图在各渠道的副本状态，按渠道优先级降序

curl -X GET 'http://localhost:8721/api/admin/images/string'
{  "id": "string",  "url": "string",  "user_id": "string",  "token_id": 0,  "token_name": "string",  "file_name": "string",  "mime": "string",  "size": 0,  "width": 0,  "height": 0,  "sha256": "string",  "expire_at": "string",  "ttl_seconds": 0,  "last_access_at": "string",  "access_count": 0,  "pending_cleanup": true,  "cleanup_exempt": true,  "created_at": "string",  "ref_count": 0,  "replicas": [    {      "channel_id": 0,      "channel_name": "string",      "state": "pending",      "attempts": 0,      "last_error": "string",      "updated_at": "string"    }  ]}

修改有效期或清理豁免

PATCH
/api/admin/images/{id}

至少携带一个修改项。ttl_hours 对属主开放；cleanup_exempt 是冷图裁决的「保留」语义，仅管理员，普通用户携带即 403。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*string

图片短 ID

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body

修改项；缺省的项不动，至少携带一项

ttl_hours?integer

大于 0 从现在起算新的到期时刻并更新时长；0 改为永久

Formatint64
Range0 <= value <= 876000
cleanup_exempt?boolean

预设或取消清理豁免；仅管理员。取消时顺带摘掉待清理标记，由下轮扫描重判

Response Body

图片详情

application/json
  1. response

图片列表项

id*string

短 ID

url*string

公开访问路径，相对站点根

user_id*string

归属用户

token_id*|

上传来源 Token；null 表示后台上传或来源 Token 记录已删除

Formatint64
token_name*|

来源 Token 用途名；null 同 token_id

file_name*string

原始文件名

mime*string

真实 MIME

size*integer

存储字节

Formatint64
width*integer
Formatint64
height*integer
Formatint64
sha256*string

内容哈希

expire_at*|

到期时刻；null 表示永久

ttl_seconds*|

有效时长（秒），访问续期按此顺延；null 表示永久

Formatint64
last_access_at*|

最近公开访问；null 表示从未

access_count*integer

累计公开访问次数，活跃度落库周期粒度

Formatint64
pending_cleanup*boolean

是否在待清理列表

cleanup_exempt*boolean

是否清理豁免

created_at*string

上传时刻

ref_count*integer

物理图引用计数（同图去重共享）

Formatint64
replicas*array<>

物理图在各渠道的副本状态，按渠道优先级降序

curl -X PATCH 'http://localhost:8721/api/admin/images/string' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{}'
{  "id": "string",  "url": "string",  "user_id": "string",  "token_id": 0,  "token_name": "string",  "file_name": "string",  "mime": "string",  "size": 0,  "width": 0,  "height": 0,  "sha256": "string",  "expire_at": "string",  "ttl_seconds": 0,  "last_access_at": "string",  "access_count": 0,  "pending_cleanup": true,  "cleanup_exempt": true,  "created_at": "string",  "ref_count": 0,  "replicas": [    {      "channel_id": 0,      "channel_name": "string",      "state": "pending",      "attempts": 0,      "last_error": "string",      "updated_at": "string"    }  ]}

删除图片

DELETE
/api/admin/images/{id}

立即删除引用，渠道副本、衍生图与 CDN 缓存由清理任务级联；他人图一律 404。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*string

图片短 ID

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Response Body

已删除

curl -X DELETE 'http://localhost:8721/api/admin/images/string' \  -H 'X-CSRF-Token: string'
Empty

后台预览图

GET
/api/admin/images/{id}/thumb

与 /i/{id} 同一处理管线，但走会话鉴权、不计公开访问活跃度、不受防盗链约束。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*string

图片短 ID

Query Parameters

w?integer

目标宽度（像素），须在运营配置 process_widths 的档位内；缺省不缩放

format?string

目标格式，须在运营配置 process_formats 内；缺省或 auto 按 Accept 协商

Header Parameters

If-None-Match?string

与上次响应的 ETag 一致时返回 304

Response Body

图片字节（HEAD 只有响应头），带强 ETag。短 ID 下内容不可变，缓存一年（immutable）；对象键别名可被同键重传 改指，为 Cache-Control: public, no-cache，每次带 ETag 确认、未变即 304。同一 URL 的输出格式随 Accept 协商时（未显式指定 format），原图与衍生图响应都带 Vary: Accept；处理失败降级输出原图时为 Cache-Control: no-store

image/*
curl -X GET 'http://localhost:8721/api/admin/images/string/thumb'
Empty

后台·上传

会话认证的后台上传，与数据面同一管道

后台·上传 Token

具名 Token 的签发、轮转、吊销与 S3 凭证