ImgYoung
DocsAPI
API reference

Admin · Import

Bulk-import images from lists of image URLs, Markdown and HTML text, sitemaps or web pages, and export a mapping from old links to new ones

导入任务列表

GET
/api/admin/imports

分页返回导入任务，最新的在前。普通用户只看得到自己创建的；管理员看到全部，并可用 user_id 只看指定用户的。

Authorization

session
cookieimgyoung_session<token>

登录时设置的会话 cookie。状态变更请求还须带 X-CSRF-Token 头，值为该会话的 CSRF 令牌。

Query Parameters

page?integer

页码，从 1 起；缺省 1

Range1 <= value <= 2147483647
page_size?integer

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

Range1 <= value <= 100
user_id?string

只看指定用户创建的任务；仅管理员生效

Response Body

导入任务分页

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

当前用户的任务总数

Formatint64
curl -X GET 'http://localhost:8721/api/admin/imports'
{  "items": [    {      "id": "string",      "user_id": "string",      "user_name": "string",      "mode": "images",      "status": "scanning",      "seeds": [        "string"      ],      "ttl_seconds": 0,      "exif_policy": "string",      "referer": "string",      "counts": {        "candidate": 0,        "pending": 0,        "done": 0,        "failed": 0,        "skipped": 0      },      "scan": {        "pages_found": 0,        "pages_done": 0,        "report": {          "pages": 0,          "pages_without_images": 0,          "offsite_pages": 0,          "failed_pages": [            {              "source": "string",              "code": "internal",              "detail": "string"            }          ],          "failed_pages_total": 0,          "unfetchable": [            {              "source": "string",              "reference": "string"            }          ],          "unfetchable_total": 0        }      },      "error_code": "internal",      "created_at": "string",      "finished_at": "string"    }  ],  "total": 0}

创建导入任务

POST
/api/admin/imports

按 mode 创建一个导入任务。导入的图片归属当前用户，走与上传相同的处理流程：格式白名单、像素预算、EXIF 处理与存储配额照常生效。

  • images：urls 是图片地址清单。任务直接进入 importing，逐张转存。
  • text：documents 是 Markdown 或 HTML 文本，从中找出图片引用。文件名以 .html 或 .htm 结尾的按 HTML 解析，内容以 <!doctype html 或 <html 开头的也按 HTML 解析，其余按 Markdown 解析（内嵌的 HTML 同样会被扫描）。扫描在本请求内完成，任务进入 ready，等待确认。
  • site：sites 是站点地图、订阅源（RSS 或 Atom）、网页或图片的地址。任务进入 scanning，由服务端抓取并找出图片，完成后进入 ready，等待确认。

各模式只能带自己的字段，带了其他模式的字段返回 400。

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
mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
urls?array<string>

images 必填：图片地址，每个都是 http 或 https 绝对地址，不能为空，同一个地址出现多次只导入一次

documents?array<>

text 必填：文档，至少一份

base_url?string

text 可选：解析文档里相对路径的基准地址，须是 http 或 https 绝对地址。没有它，相对路径无法转成可抓取的地址，会记入扫描报告的 unfetchable。HTML 文档里的 <base href> 优先于它

sites?array<string>

site 必填：站点地图、订阅源、网页或图片的地址，至少一个，每个都是 http 或 https 绝对地址

ttl?|

导入图片的有效期秒数，规则同 URL 转存的 ttl。缺省时用该用户的默认有效期，用户未设置则用全局默认

exif_policy?string

导入图片的 EXIF 档位；缺省用运营配置的全局默认

Value in"strip""passthrough"
referer?string

抓取图片时发送的 Referer，须是 http 或 https 绝对地址，用于绕过只放行自家页面的防盗链。缺省时取该图片来源页的地址；来源不是网页（图片清单、文档）时不发送

Response Body

任务已创建

application/json
  1. response
id*string

任务 ID

user_id*string

创建任务的用户，导入的图片归属于他

user_name*string

创建任务的用户的登录名

mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
status*ImportStatus

任务状态：

  • scanning：正在抓取并扫描（仅 site）
  • ready：扫描完成，等待确认要导入哪些域名
  • importing：正在逐张转存
  • done：已处理完全部条目，其中可能有失败的
  • cancelled：已取消
  • aborted：因存储配额已满、没有可用渠道或服务端故障而中止，原因见 error_code；未处理的条目保留，可重试
Value in"scanning""ready""importing""done""cancelled""aborted"
seeds*array<string>

site 任务的起始地址；其他模式为空数组

ttl_seconds*|

创建时指定的有效期秒数，0 表示永久；null 表示按用户默认与全局默认

Formatint64
exif_policy*string

创建时指定的 EXIF 档位；空串表示用全局默认

referer*string

创建时指定的 Referer；空串表示取来源页

counts*

任务各状态的条目数

scan*

扫描进度与结果

error_code*|

aborted 的原因：upload_quota_exceeded、upload_unavailable 或 internal；其他状态为 null

created_at*string
finished_at*|

进入 done、cancelled 或 aborted 的时刻；重试后清空

curl -X POST 'http://localhost:8721/api/admin/imports' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "mode": "images"}'
{  "id": "string",  "user_id": "string",  "user_name": "string",  "mode": "images",  "status": "scanning",  "seeds": [    "string"  ],  "ttl_seconds": 0,  "exif_policy": "string",  "referer": "string",  "counts": {    "candidate": 0,    "pending": 0,    "done": 0,    "failed": 0,    "skipped": 0  },  "scan": {    "pages_found": 0,    "pages_done": 0,    "report": {      "pages": 0,      "pages_without_images": 0,      "offsite_pages": 0,      "failed_pages": [        {          "source": "string",          "code": "internal",          "detail": "string"        }      ],      "failed_pages_total": 0,      "unfetchable": [        {          "source": "string",          "reference": "string"        }      ],      "unfetchable_total": 0    }  },  "error_code": "internal",  "created_at": "string",  "finished_at": "string"}

导入任务详情

GET
/api/admin/imports/{id}

返回任务的状态、各状态的条目数与扫描报告。进行中的任务由前端轮询本接口取得进度。普通用户只能读自己的任务，管理员能读全部。

Authorization

session
cookieimgyoung_session<token>

登录时设置的会话 cookie。状态变更请求还须带 X-CSRF-Token 头，值为该会话的 CSRF 令牌。

Path Parameters

id*string

导入任务 ID

Response Body

任务详情

application/json
  1. response
id*string

任务 ID

user_id*string

创建任务的用户，导入的图片归属于他

user_name*string

创建任务的用户的登录名

mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
status*ImportStatus

任务状态：

  • scanning：正在抓取并扫描（仅 site）
  • ready：扫描完成，等待确认要导入哪些域名
  • importing：正在逐张转存
  • done：已处理完全部条目，其中可能有失败的
  • cancelled：已取消
  • aborted：因存储配额已满、没有可用渠道或服务端故障而中止，原因见 error_code；未处理的条目保留，可重试
Value in"scanning""ready""importing""done""cancelled""aborted"
seeds*array<string>

site 任务的起始地址；其他模式为空数组

ttl_seconds*|

创建时指定的有效期秒数，0 表示永久；null 表示按用户默认与全局默认

Formatint64
exif_policy*string

创建时指定的 EXIF 档位；空串表示用全局默认

referer*string

创建时指定的 Referer；空串表示取来源页

counts*

任务各状态的条目数

scan*

扫描进度与结果

error_code*|

aborted 的原因：upload_quota_exceeded、upload_unavailable 或 internal；其他状态为 null

created_at*string
finished_at*|

进入 done、cancelled 或 aborted 的时刻；重试后清空

curl -X GET 'http://localhost:8721/api/admin/imports/string'
{  "id": "string",  "user_id": "string",  "user_name": "string",  "mode": "images",  "status": "scanning",  "seeds": [    "string"  ],  "ttl_seconds": 0,  "exif_policy": "string",  "referer": "string",  "counts": {    "candidate": 0,    "pending": 0,    "done": 0,    "failed": 0,    "skipped": 0  },  "scan": {    "pages_found": 0,    "pages_done": 0,    "report": {      "pages": 0,      "pages_without_images": 0,      "offsite_pages": 0,      "failed_pages": [        {          "source": "string",          "code": "internal",          "detail": "string"        }      ],      "failed_pages_total": 0,      "unfetchable": [        {          "source": "string",          "reference": "string"        }      ],      "unfetchable_total": 0    }  },  "error_code": "internal",  "created_at": "string",  "finished_at": "string"}

删除导入任务

DELETE
/api/admin/imports/{id}

删除任务及其条目、来源与对照表。已经导入的图片不受影响。scanning 与 importing 的任务须先取消。管理员可以删除任何人的任务。

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/imports/string' \  -H 'X-CSRF-Token: string'
Empty

待确认的图片地址按域名分组

GET
/api/admin/imports/{id}/hosts

返回 candidate 状态的条目按域名分组的数量，数量多的在前，每组附最多 3 个示例地址。用于确认页决定导入哪些域名下的图片。任务确认之后没有 candidate 条目，返回空数组。

Authorization

session
cookieimgyoung_session<token>

登录时设置的会话 cookie。状态变更请求还须带 X-CSRF-Token 头，值为该会话的 CSRF 令牌。

Path Parameters

id*string

导入任务 ID

Response Body

域名分组

application/json
  1. response
[index: integer]?
curl -X GET 'http://localhost:8721/api/admin/imports/string/hosts'
[  {    "host": "string",    "count": 0,    "samples": [      "string"    ]  }]

导入任务的条目

GET
/api/admin/imports/{id}/items

分页返回任务的条目，按发现顺序排列，可按状态与域名过滤。

Authorization

session
cookieimgyoung_session<token>

登录时设置的会话 cookie。状态变更请求还须带 X-CSRF-Token 头，值为该会话的 CSRF 令牌。

Path Parameters

id*string

导入任务 ID

Query Parameters

page?integer

页码，从 1 起；缺省 1

Range1 <= value <= 2147483647
page_size?integer

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

Range1 <= value <= 100
state?string

只看指定状态的条目

Value in"candidate""pending""done""failed""skipped"
host?string

只看指定域名的条目，须与分组里的 host 完全一致

Response Body

条目分页

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

过滤后的总条数

Formatint64
curl -X GET 'http://localhost:8721/api/admin/imports/string/items'
{  "items": [    {      "id": 0,      "url": "string",      "host": "string",      "state": "candidate",      "image_id": "string",      "error_code": "internal",      "error_detail": "string",      "sources": [        "string"      ],      "source_count": 0    }  ],  "total": 0}

确认并开始导入

POST
/api/admin/imports/{id}/start

对 ready 状态的任务，导入 hosts 所列域名下的全部 candidate 条目，其余条目记为 skipped，任务进入 importing。

hosts 里没有任何域名对应待导入的条目时返回 400，任务保持 ready。

只有创建任务的用户能确认；管理员确认别人的任务返回 403，错误码 import_owner_only。

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
hosts*array<string>

要导入的域名，取自 GET /api/admin/imports/{id}/hosts 的 host；重复的只算一个

Items1 <= items <= 1000

Response Body

任务已开始

application/json
  1. response
id*string

任务 ID

user_id*string

创建任务的用户，导入的图片归属于他

user_name*string

创建任务的用户的登录名

mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
status*ImportStatus

任务状态：

  • scanning：正在抓取并扫描（仅 site）
  • ready：扫描完成，等待确认要导入哪些域名
  • importing：正在逐张转存
  • done：已处理完全部条目，其中可能有失败的
  • cancelled：已取消
  • aborted：因存储配额已满、没有可用渠道或服务端故障而中止，原因见 error_code；未处理的条目保留，可重试
Value in"scanning""ready""importing""done""cancelled""aborted"
seeds*array<string>

site 任务的起始地址；其他模式为空数组

ttl_seconds*|

创建时指定的有效期秒数，0 表示永久；null 表示按用户默认与全局默认

Formatint64
exif_policy*string

创建时指定的 EXIF 档位；空串表示用全局默认

referer*string

创建时指定的 Referer；空串表示取来源页

counts*

任务各状态的条目数

scan*

扫描进度与结果

error_code*|

aborted 的原因：upload_quota_exceeded、upload_unavailable 或 internal；其他状态为 null

created_at*string
finished_at*|

进入 done、cancelled 或 aborted 的时刻；重试后清空

curl -X POST 'http://localhost:8721/api/admin/imports/string/start' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "hosts": [    "string"  ]}'
{  "id": "string",  "user_id": "string",  "user_name": "string",  "mode": "images",  "status": "scanning",  "seeds": [    "string"  ],  "ttl_seconds": 0,  "exif_policy": "string",  "referer": "string",  "counts": {    "candidate": 0,    "pending": 0,    "done": 0,    "failed": 0,    "skipped": 0  },  "scan": {    "pages_found": 0,    "pages_done": 0,    "report": {      "pages": 0,      "pages_without_images": 0,      "offsite_pages": 0,      "failed_pages": [        {          "source": "string",          "code": "internal",          "detail": "string"        }      ],      "failed_pages_total": 0,      "unfetchable": [        {          "source": "string",          "reference": "string"        }      ],      "unfetchable_total": 0    }  },  "error_code": "internal",  "created_at": "string",  "finished_at": "string"}

取消导入任务

POST
/api/admin/imports/{id}/cancel

取消 scanning、ready 或 importing 的任务。正在转存的图片会被中断，没处理完的条目保持 pending，已经导入的图片保留。管理员可以取消任何人的任务。

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

任务已取消

application/json
  1. response
id*string

任务 ID

user_id*string

创建任务的用户，导入的图片归属于他

user_name*string

创建任务的用户的登录名

mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
status*ImportStatus

任务状态：

  • scanning：正在抓取并扫描（仅 site）
  • ready：扫描完成，等待确认要导入哪些域名
  • importing：正在逐张转存
  • done：已处理完全部条目，其中可能有失败的
  • cancelled：已取消
  • aborted：因存储配额已满、没有可用渠道或服务端故障而中止，原因见 error_code；未处理的条目保留，可重试
Value in"scanning""ready""importing""done""cancelled""aborted"
seeds*array<string>

site 任务的起始地址；其他模式为空数组

ttl_seconds*|

创建时指定的有效期秒数，0 表示永久；null 表示按用户默认与全局默认

Formatint64
exif_policy*string

创建时指定的 EXIF 档位；空串表示用全局默认

referer*string

创建时指定的 Referer；空串表示取来源页

counts*

任务各状态的条目数

scan*

扫描进度与结果

error_code*|

aborted 的原因：upload_quota_exceeded、upload_unavailable 或 internal；其他状态为 null

created_at*string
finished_at*|

进入 done、cancelled 或 aborted 的时刻；重试后清空

curl -X POST 'http://localhost:8721/api/admin/imports/string/cancel' \  -H 'X-CSRF-Token: string'
{  "id": "string",  "user_id": "string",  "user_name": "string",  "mode": "images",  "status": "scanning",  "seeds": [    "string"  ],  "ttl_seconds": 0,  "exif_policy": "string",  "referer": "string",  "counts": {    "candidate": 0,    "pending": 0,    "done": 0,    "failed": 0,    "skipped": 0  },  "scan": {    "pages_found": 0,    "pages_done": 0,    "report": {      "pages": 0,      "pages_without_images": 0,      "offsite_pages": 0,      "failed_pages": [        {          "source": "string",          "code": "internal",          "detail": "string"        }      ],      "failed_pages_total": 0,      "unfetchable": [        {          "source": "string",          "reference": "string"        }      ],      "unfetchable_total": 0    }  },  "error_code": "internal",  "created_at": "string",  "finished_at": "string"}

重试失败的条目并继续

POST
/api/admin/imports/{id}/retry

对 done、aborted 或 cancelled 的任务，把 failed 的条目重新置为待导入，连同尚未处理的条目一起继续，任务回到 importing。

没有 failed 或 pending 的条目时返回 409。因存储配额或没有可用渠道而中止的任务，先解决问题再重试。

只有创建任务的用户能重试；管理员重试别人的任务返回 403，错误码 import_owner_only。

扫描没有完成就中止或取消的 site 任务没有候选可以继续，重试会让它回到 scanning，从头重新扫描。

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

任务已继续

application/json
  1. response
id*string

任务 ID

user_id*string

创建任务的用户，导入的图片归属于他

user_name*string

创建任务的用户的登录名

mode*ImportMode

输入类型：

  • images：图片地址清单，直接导入
  • text：Markdown 或 HTML 文本，扫描后确认
  • site：站点地图、订阅源、网页或图片的地址，由服务端抓取并扫描，完成后确认
Value in"images""text""site"
status*ImportStatus

任务状态：

  • scanning：正在抓取并扫描（仅 site）
  • ready：扫描完成，等待确认要导入哪些域名
  • importing：正在逐张转存
  • done：已处理完全部条目，其中可能有失败的
  • cancelled：已取消
  • aborted：因存储配额已满、没有可用渠道或服务端故障而中止，原因见 error_code；未处理的条目保留，可重试
Value in"scanning""ready""importing""done""cancelled""aborted"
seeds*array<string>

site 任务的起始地址；其他模式为空数组

ttl_seconds*|

创建时指定的有效期秒数，0 表示永久；null 表示按用户默认与全局默认

Formatint64
exif_policy*string

创建时指定的 EXIF 档位；空串表示用全局默认

referer*string

创建时指定的 Referer；空串表示取来源页

counts*

任务各状态的条目数

scan*

扫描进度与结果

error_code*|

aborted 的原因：upload_quota_exceeded、upload_unavailable 或 internal；其他状态为 null

created_at*string
finished_at*|

进入 done、cancelled 或 aborted 的时刻；重试后清空

curl -X POST 'http://localhost:8721/api/admin/imports/string/retry' \  -H 'X-CSRF-Token: string'
{  "id": "string",  "user_id": "string",  "user_name": "string",  "mode": "images",  "status": "scanning",  "seeds": [    "string"  ],  "ttl_seconds": 0,  "exif_policy": "string",  "referer": "string",  "counts": {    "candidate": 0,    "pending": 0,    "done": 0,    "failed": 0,    "skipped": 0  },  "scan": {    "pages_found": 0,    "pages_done": 0,    "report": {      "pages": 0,      "pages_without_images": 0,      "offsite_pages": 0,      "failed_pages": [        {          "source": "string",          "code": "internal",          "detail": "string"        }      ],      "failed_pages_total": 0,      "unfetchable": [        {          "source": "string",          "reference": "string"        }      ],      "unfetchable_total": 0    }  },  "error_code": "internal",  "created_at": "string",  "finished_at": "string"}

导出新旧链接对照表

GET
/api/admin/imports/{id}/mapping

以附件形式下载已导入成功的条目的对照表。新地址是图片的绝对访问地址：配置了对外站点地址（base_url）时用它，否则按本次请求推导。

  • format=json：每个条目一个对象，来源引用嵌套在 references 里。
  • format=csv：UTF-8，首行为表头，每条来源引用一行，列为 old_url、new_url、image_id、source、raw；没有来源引用的条目也输出一行，source 与 raw 为空。

图片被删除后，对应条目不再出现在对照表里。

Authorization

session
cookieimgyoung_session<token>

登录时设置的会话 cookie。状态变更请求还须带 X-CSRF-Token 头，值为该会话的 CSRF 令牌。

Path Parameters

id*string

导入任务 ID

Query Parameters

format?string

输出格式，缺省 json

Value in"json""csv"

Response Body

对照表

  1. response
[index: integer]?
curl -X GET 'http://localhost:8721/api/admin/imports/string/mapping'
[  {    "old_url": "string",    "new_url": "string",    "image_id": "string",    "references": [      {        "source": "string",        "raw": "string"      }    ]  }]

Admin · Images

Image list, details, edits and deletion

Admin · Upload tokens

Issuing, rotating and revoking named upload tokens, and their S3 credentials