接口文档

用接口令牌，你可以在自己的程序里做网站上能做的大部分事：浏览和搜索作品、整理书架、发评论、看通知、签到、投稿……本页是全部接口的说明：第 1、2 节是准备工作和一个 Python 客户端，第 3 节起按令牌的用途分节。投稿的完整流程（传文件、排结构、提交审核、更新作品）另见「投稿接口」。

1. 准备

1.1 建一个接口令牌

在网站上登录，打开「接口令牌」页（个人中心里），点「新建令牌」：

1. 起个名字（比如「同步书架」），勾选要用的用途（见下表，可以多选），选到期时间（最长多久页面上写着，默认 90 天；到期以后再建一个）。

2. 输入当前密码确认。还没设过密码的（用论坛账号快捷注册的）先在账号设置里加一个密码；邮箱要先验证过。

3. 页面上显示的 acgp_… 就是令牌，只显示这一次，马上存好（放进环境变量或密码管理器，不要写进代码、不要发给别人）。同一个页面上写着接口地址（到 /api/v1 为止），下文写作 $ACG_API。

令牌绑着你的账号，程序带着它调用接口就是以你的身份操作。它只能调用你勾选的用途里的接口：

• 查看当前账号（GET /me）任何用途都能调用。

• 用途不对时：要登录的接口返回 10003（data.reason 是 token_scope）；公开的接口不报错，按未登录的访客处理。

• 只勾选程序用得到的用途。令牌泄露时，别人能做的就是这些用途里的事。

• 改密码、改邮箱、管理令牌只能在网站上登录后操作，令牌做不了（第 12 节）。

• 「接口令牌」页上看得到每个令牌最后一次使用的时间和 IP；不认识的 IP、不再使用、可能泄露的，点「吊销」立即失效。改密码、找回密码时全部令牌自动作废。每建一个令牌都会往你的邮箱发一封提醒：不是你建的，马上吊销并改密码。

• 同时能用的令牌有上限（默认 5 个），不用的吊销掉。

试一下：

export ACG_API=https://api.neosek.ai/api/v1   # 「接口令牌」页上写的接口地址
export ACG_TOKEN=acgp_…
curl -s -H "Authorization: Bearer $ACG_TOKEN" "$ACG_API/me"

返回 "code": 0 和你的账号信息（第 11.1 节）就通了。

1.2 请求和响应

• 地址是 $ACG_API 加上本页写的路径，如 $ACG_API/works。每个请求都带请求头 Authorization: Bearer <令牌>。

• 请求体是 JSON（Content-Type: application/json），字段名用 snake_case。

• 账号的字段和路径叫 account（/accounts/…、account、account_id）。以前的 user 写法（/users/…、user、user_id）已停用：旧路径返回 10004，旧的字段名和查询参数不再识别。

• 时间是 RFC 3339，带时区（2026-10-20T23:30:00+08:00）；只有日期的参数写 YYYY-MM-DD，按站点时区。id 是数字，图片、视频这类文件的 uid 是字符串。

• 查询参数要多个值时用逗号分开（?content_type=manga,novel）；不认识的参数会被忽略。

• 语言：名称、说明这类给人看的文字按 ?lang= > 请求头 Accept-Language > 你账号的语言设置 > zh-CN 的顺序选，支持 zh-CN、en-US。接口里的 name 就是选出的那种语言的名称。

• 响应一律是 HTTP 200（维护中、上传文件的断点续传等少数情况除外），成败看 code：

{ "code": 0, "message": "success", "data": { } }

message 是给开发者看的英文。各节写了各自接口特有的错误码；通用的有：

找站务问问题时带上响应头里的 X-Request-Id，查得到那一次请求。

1.3 列表和分页

列表接口大多按游标分页：查询参数 limit（每页几条，默认 20、最大 100）和 cursor（第一页不带），响应是：

{ "items": [ ], "next_cursor": "…" }

下一页把 next_cursor 原样放进 cursor 再请求；next_cursor 为 null 就是到头了。空列表是 []。少数接口用页码（page 从 1 开始、page_size，响应带 pagination），个别接口不分页、一次给全，各节会写明。

1.4 修改、重试和频率

• 写操作成功时返回改好的完整对象。

• 几处可能同时修改的对象（投稿、收藏夹这类）带 version：修改时带上你拿到的 version，对不上返回 10005，data 是最新的对象，换上它的 version 再来。

• 写明支持 Idempotency-Key 的接口：请求头带一个随机串（不超过 64 个字符），网络断了重发时，24 小时内同一个键返回第一次的结果，不会重复执行（响应头带 Idempotent-Replayed: true）。

• 接口按账号限制频率（发评论、签到这类各有各的上限），超过时返回 10006。批量处理时一条一条来，10006、10009 等一会儿重试就好；别的错误要改了请求再来。

1.5 图片、视频、音频的地址

接口里每个文件都是同一个形状：

{ "url": "https://…", "fallbacks": ["https://…"], "expires_at": null }

• 主地址打不开（连不上、5xx）时按顺序换 fallbacks 里的；都打不开，或者快到 expires_at 了，用 POST /media/urls 重新要地址（第 3.7 节）。expires_at 为 null 是不过期。

• 图片另有 width、height、placeholder（主色和模糊预览）和各种尺寸的地址。

• 地址都由接口给出，不要自己拼。站点设成要登录才能看的分级（GET /meta 的 ratings[].requires_login），未登录时不给地址：带 restricted: "login_required"，图片只有尺寸和 placeholder。令牌带「浏览」用途就按你本人算。

2. Python 客户端

Python 3.8 以上，只依赖 requests（pip install requests）。存成 acg_client.py，本页和「投稿接口」页的例子都用它。别的语言照着它发同样的 HTTP 请求就行。

"""站点接口的最小客户端：Python 3.8+，只依赖 requests（pip install requests）。

环境变量：
  ACG_API    接口地址（「接口令牌」页上写着，到 /api/v1 为止）
  ACG_TOKEN  在网站「接口令牌」页建的令牌（acgp_ 开头）
"""
import os
import time
import uuid

import requests

API = os.environ["ACG_API"].rstrip("/")
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["ACG_TOKEN"]

RETRYABLE = {10006, 10009, 72012}  # 太频繁、维护中、文件服务暂时不可用：等一会儿再试


class APIError(Exception):
    def __init__(self, code, message, data=None):
        super().__init__(f"{code} {message} {data if data is not None else ''}".strip())
        self.code, self.message, self.data = code, message, data


def unwrap(resp):
    """拆开 { code, message, data }：code 不是 0 就抛 APIError。"""
    env = resp.json()
    if env.get("code") != 0:
        raise APIError(env.get("code"), env.get("message"), env.get("data"))
    return env["data"]


def call(method, path, body=None, params=None, files=None, idempotent=False):
    """调接口，返回 data。params 是查询参数；带文件时 body 当表单字段发（multipart）。"""
    headers = {"Idempotency-Key": uuid.uuid4().hex} if idempotent else {}
    for attempt in range(6):
        kw = {"data": body, "files": files} if files else {"json": body}
        resp = session.request(method, API + path, params=params, headers=headers, timeout=120, **kw)
        try:
            return unwrap(resp)
        except APIError as e:
            if e.code not in RETRYABLE or attempt == 5:
                raise
            time.sleep(float(resp.headers.get("Retry-After") or 10))


def pages(path, params=None):
    """按游标翻页的列表接口：逐条产出 items，翻到 next_cursor 为 null 为止。"""
    params = dict(params or {})
    while True:
        data = call("GET", path, params=params)
        yield from data["items"]
        if not data.get("next_cursor"):
            return
        params["cursor"] = data["next_cursor"]

call(..., idempotent=True) 会带上一个随机的 Idempotency-Key，自动重试时沿用同一个键（解锁、打赏这类必须带它的接口用）。用法：

from acg_client import APIError, call, pages

me = call("GET", "/me")
print(me["name"], me["permissions"])
for work in pages("/works", {"content_type": "manga", "limit": 100}):
    print(work["id"], work["title"])
try:
    call("GET", "/me/points")
except APIError as e:
    print(e.code, e.data)  # 令牌没有「积分」用途时：10003 {'reason': 'token_scope'}

3. 浏览（用途「浏览」）

公开的内容不登录也能读。令牌带「浏览」用途时按你本人算：看得到要登录才能看的标签和作品、你解锁过的内容，作品详情里的 viewer（关注、阅读进度、打分、收藏）是你的；没有这个用途时按未登录的访客算，不报错。

3.1 站点、分类和页面

GET /site 站点配置

另有 menus、footer、seo 等给网页显示用的字段；菜单和公告按你的身份过滤。

• 站点维护时（maintenance.enabled 为 true），除了 GET /site、GET /meta、GET /pages/{slug}，别的接口都返回 10009。

• GET /site、GET /meta 带 ETag：请求头 If-None-Match 对得上时回 HTTP 304（没有响应体）。

GET /meta 元数据

各种选项的代码和名字。选项由站务设置、会增减，程序里不要写死。带 ?names=all 时每项另给 names（全部语言的名字）。

另有下载、打赏、求档、通知、举报等用到的选项。筛选参数用各项的 code，只有 category 用分类的 id；按分类找 id 时用内容类型和分类代码（名字随语言变）：

meta = call("GET", "/meta")
cats = {(c["content_type"], c["code"]): c["id"] for c in meta["categories"]}
doujinshi = cats[("manga", "doujinshi")]   # 漫画的「同人志」分类
for ns in meta["tag_namespaces"]:
    print(ns["code"], ns["aliases"], ns["name"], ns["creator_role"])

GET /pages/{slug} 站点页面

→ { "slug": "terms", "title": "使用条款", "body": "（Markdown 原文）", "updated_at": "…" }。有哪些页面看 GET /site 的 pages；不存在 10004。

站点地图

给搜索引擎的站点地图用的 id 列表，总是按访客算。

只收能给搜索引擎收录的：访客看得到也能读、分级不是 noindex 的已发布作品，至少有一部这样的作品的标签、创作者、系列，以及全部站点页面。

3.2 作品列表、筛选面板、新番时间表、随机和相关

GET /works 作品列表

列已发布的作品，游标分页 → { "items": [作品列表项], "next_cursor" }。参数都可以不带：

• 代码不存在、范围反了、日期格式不对都是 10001，如 released_to: invalid。

• 游标里带着排序和筛选，换了参数要从第一页重新取。

作品列表项（列表、搜索、排行、首页里的作品都是这个形状）：

for w in pages("/works", {"content_type": "manga", "tag": "45,46", "sort": "updated"}):
    print(w["id"], w["title"], w["stats"]["views"])

GET /works/facets 筛选面板

按类型标签、年份筛作品时用：给这两排的选项和各有几部 → { "tags", "years" }。筛选参数同 GET /works（sort、cursor、limit 不用）。

• 每一排按除了它自己以外的条件数：类型标签不看 tag，年份不看发行日期的范围。选了一项以后另一排的数跟着变，自己这一排照旧列全。

• 套用你的内容过滤（filter=off 这次不套用）。

f = call("GET", "/works/facets", params={"content_type": "anime", "released_from": "2024-01-01", "released_to": "2024-12-31"})
print([(t["name"], t["count"]) for t in f["tags"]])

GET /schedule 新番时间表

一周七天，列连载中、填了放送时间的动画，每部作品一周一项；套用你的内容过滤。

• week：ISO 周 YYYY-Www（如 2026-W41），不带是本周。前后能翻的周数有限（默认各 8 周，以站点设置为准），超出或格式不对 10001。

• rating：只列这几档分级的作品（分级代码，多个用逗号分开，同 GET /works）；不认识的代码 10001。

{ "week": "2026-W41", "prev_week": "2026-W40", "next_week": "2026-W42", "timezone": "Asia/Shanghai",
  "days": [ { "date": "2026-10-10", "weekday": 6, "items": [
    { "work": { "…": "作品列表项" }, "at": "2026-10-10T22:30:00.000+08:00",
      "unit": { "id": 305, "title": "第2集", "published_at": null }, "state": "scheduled" } ] } ] }

• timezone 是站点时区，一周按它算；days 星期一在前，weekday 1 到 7 是星期一到星期日；prev_week、next_week 到了能翻的边界为 null。

• at 是放送时间推出来的这一档；unit 是这一档对应的那一集，还没有为 null；state：aired 已上线 / scheduled 定时了、还没到点 / expected 还没传。

GET /works/random 随机作品

在符合条件的已发布作品里随机挑一部（在作品编号的范围里随机取一个起点、取它后面第一部符合的，不完全等概率）→ { "id": 123, "content_type": "manga" }；一部都没有时两项都是 null。筛选参数同 GET /works（sort、cursor、limit 不用）。

GET /works/{id}/related 相关作品

和这部作品相似的已发布作品，最像的在前 → { "items": [作品列表项] }，不分页。

• limit：默认 12、最多 50（以站点设置为准），超出范围 10001。

• rating：只要这几档分级的作品（同 GET /works），从这几档里挑够条数；不认识的代码 10001。

• 手填的关联作品（详情的 relations）不在里面；套用你的内容过滤。结果不是实时的。

• 同一部作品的不同版本（不同汉化、不同语言、重复上传）只出一个，优先和这部作品同语言的，机翻的排在后面；这部作品自己的别的版本不在里面。

• 作品不存在、看不到 10004。

3.3 搜索和联想

搜索语法

搜索文字按空白（含全角空格）切成几个条件，条件之间是「并且」：

标签、创作者写任何一种语言的名字或别名都行。

GET /search 搜索

返回 items、next_cursor，另有：

• query：q 和解析出来的条件 terms[]：raw（原样写法）、kind（keyword / tag / creator / code）、认出来的 tag 或 creator（没认出为 null），另有 negated、or_group、exact、phrase、namespace、text、matched_alias。

• query.warnings[]：没按预期理解的条件 { "raw", "code" }：unknown_namespace（没有这个命名空间，整条当关键词）、unknown_tag、unknown_creator（正向的条件什么也匹配不到，排除的不起作用）、empty_term（如单独一个 -，忽略）。

• total：结果数；total_exact 为 false 时是估计值。

• degraded：true 时全文搜索暂时不可用，这次关键词只匹配了标题、别名、作品号，relevance 按 latest 排。

条件超过 limits.search_max_terms（默认 20）个返回 77001。

r = call("GET", "/search", params={"q": "female:眼镜 -male:眼镜", "content_type": "manga"})
print([(t["raw"], t["kind"]) for t in r["query"]["terms"]], r["query"]["warnings"])
print(r["total"], [w["title"] for w in r["items"]])

要全部结果时用 pages("/search", {...}) 逐条取。

GET /search/suggest 联想

按正在输入的一个条件给标签、创作者、作品的候选。

{ "items": [
  { "kind": "tag", "tag": { "id": 45, "namespace": "female", "name": "眼镜" }, "matched": "眼鏡", "work_count": 1234, "query": "female:眼镜" },
  { "kind": "creator", "creator": { "id": 3, "name": "某某", "roles": ["author"] }, "matched": null, "work_count": 12, "query": "artist:某某" }
] }

• matched：用别名或别的语言的名字匹配上时是匹配上的写法，直接按名字匹配上为 null。

• work_count：标签连同下位标签的已发布作品数；创作者的已发布作品数。

• kind 为 work 时给 work（简短的作品），没有 work_count，query 为 null。

• query：选中后放进搜索框的写法。遇到不认识的 kind 跳过。

GET /search/trending 热搜

一段时间里（默认 7 天）搜过同一个词的人数，多的在前；同一个人同一个词只算一次，人数太少的不列。所有人看到的一样，几分钟更新一次。

{ "items": [
  { "q": "female:眼镜", "heat": 128, "mark": "hot", "pinned": false },
  { "q": "侦探", "heat": 42, "mark": "new", "pinned": false }
] }

• q：搜索词，原样；拿它当 GET /search 的 q 就是这个词的结果。

• heat：这段时间里搜过的人数；站务手动加的词可能为 null。

• mark：hot（前几名）、new（刚有人搜的）或 null；以后可能加，不认识的当 null。

• pinned：站务置顶、手动加的，排在最前面。

• 热搜关着或者还没有够人数的词时 items 是空的。用接口令牌搜的不算进热搜。

for t in call("GET", "/search/trending")["items"]:
    print(t["q"], t["heat"], call("GET", "/search", params={"q": t["q"], "limit": 1})["total"])

3.4 作品详情、标签投票、价格、收录的片单

GET /works/{id} 作品详情

作品列表项的全部字段，另有：

另有 can_manage、manage_url，只对站务有意义。

• 不存在、下架、删除的，你看不到的（别人还没公开的作品）都是 10004。

• 取详情不记浏览。浏览只在有人真的打开作品页时由浏览器报（下面的 POST /works/{id}/views），程序取数据不用报。

GET /works/batch 一次取几部作品

GET /works/batch?ids=12,13,14 → { "items": [作品详情], "missing": [14] }：一次取几部作品的详情，每项同 GET /works/{id}，按 ids 的顺序（重复的只给一次）；看不到、没有的 id 放进 missing，不报错。不记浏览，适合程序批量刷新作品信息。

• ids 必填，逗号分开，最多 50 个（GET /site 的 limits.works_batch_max）；没带、不是数字、太多都是 10001（ids: required / invalid / too_many）。默认每分钟 60 次（以站点设置为准）。

POST /works/{id}/views 报一次浏览

给自己做的阅读、播放界面用：页面真的显示给人看的时候报一次，→ { "recorded": true }。同一个人同一部作品一天只算一次，算过的、没公开的预览、User-Agent 像爬虫或脚本的都是 false；看不到的作品 10004。带「浏览」用途的令牌按本人算，不带的按访客算。批量取数据、刷新缓存的程序不要调。

GET /works/{id}/tags 作品的标签和投票

这部作品的候选标签和票数 → { "items": [{ "tag", "score", "shown", "locked", "source", "viewer_vote" }], "thresholds": { "show", "remove" } }，tag 是 { "id", "namespace", "name" }。

• 作品上的标签由投票决定显不显示：score 到 thresholds.show 显示，显示着的掉到 thresholds.remove 以下撤下；locked 是站务锁定的，不能投。

• 显示着的在前，其余按分数高的在前；撤下的也列出（shown: false）。

• source：uploader 投稿人 / staff 站务 / user 用户补的；viewer_vote 是你投的：1 赞成 / -1 反对 / 0 没投。

• 作品看不到 10004。投票、补标签要「互动」用途。

GET /works/{id}/price 作品的价格

要花积分的下载（解锁）现在多少钱，按你本人算：

作品不存在、看不到 10004。

GET /works/{id}/collections 收录这部作品的片单

收录了这部作品的公开收藏夹（片单）。页码分页：page（从 1 起）、page_size（默认 20、最大 100）→ { "items": [片单], "pagination": { "page", "page_size", "total", "total_capped" } }。

• sort：popular 赞多的在前（默认）/ new 新建的在前 / updated 最近改过的在前。

• 片单的字段：id、name、description、item_count、covers（最近放进来的几部作品的封面）、account（主人 { "id", "name", "avatar", "deleted" }）、like_count、liked（你赞了没有）、created_at、updated_at，另有 public、is_default、item_order。

• 作品看不到 10004。

3.5 标签、创作者、系列

• 标签：id、namespace（{ "code", "name" }）、name、aliases、description（Markdown 原文）、parent 和 children（上位、下位标签，下位最多给 50 个）、work_count（带这个标签或它任何一个下位标签的已发布作品数，不一定是实时的）、query（它在搜索语法里的写法，如 female:眼镜）、redirected_from、viewer。

• 创作者：name、aliases、roles（出现过的角色代码）、description、links（{ "kind", "url", "title" }）、work_count、redirected_from、viewer。

• 系列：name、aliases、description、work_count、cover（系列里排第一的作品的封面，没有作品为 null）、redirected_from、viewer。

• viewer.following：你关注了没有。redirected_from：请求的是合并掉的旧 id 时，返回合并后的那个，这里是旧 id（正常为 null），存下来的 id 请换成新的。

• 禁用的、还在审核的标签，还在审核的创作者，都是 10004。按名字找创作者用 GET /creators?q=（下一小节）或者联想 GET /search/suggest（scope=creators）。

• 它们的作品：GET /works?tag=45、GET /works?creator=3&creator_role=author、GET /works?series=5&sort=series。

t = call("GET", "/tags/lookup", params={"namespace": "female", "name": "眼镜"})
print(t["id"], t["work_count"], t["query"])
for w in pages("/works", {"tag": t["id"], "sort": "score"}):
    print(w["id"], w["title"])

列出全部标签、创作者、系列

• 三个接口都是页码分页：page（从 1 起）、page_size（默认 20、最大 100）→ { "items", "pagination": { "page", "page_size", "total", "total_capped" } }；sort：works 作品多的在前（默认）/ new 新建的在前。

• 只列正常的（合并掉的、禁用的、还在审核的不列）；按访客算时不列要登录才能看的标签。work_count 同详情页。

• namespace、role 不认识，sort 不对，都返回 10001。

3.6 首页和排行

GET /home 首页

一个请求取完首页的全部模块，已按你的身份和内容过滤处理好 → { "is_default", "modules": [...] }（is_default 为 true 是默认的首页）。

每个模块有 id、kind、title（null 时按种类用默认标题）、display（grid / list / compact）、pc_count、mobile_count（电脑上、手机上各显示几条）、columns（一行建议显示几本，为 null 时自己定），另按 kind 多出：

遇到不认识的 kind 跳过。

带 rating（分级代码，多个用逗号分开，同 GET /works）时只要这几档分级的作品：精选、作品区、排行都先按分级筛再取条数，幻灯片关联的作品不在这几档的那一张不给，筛完没有作品的模块不给。不认识的代码 10001。

GET /rankings 排行

不认识的、这个指标不能用的返回 10001：metric: unknown、period: unknown、content_type: unknown、rating: unknown、limit: invalid。

返回 { "metric", "period", "content_type", "generated_at", "items": [{ "rank", "value", "backfill", "work" }] }，不分页，work 是作品列表项：

• 排行每小时算一次，generated_at 是这一份的时间；content_type 是全部类型时为 null。

• rank 按这次返回的顺序连着排；value 是这个指标在这个时段里的数（all 是累计）；数一样时 id 小的在前。

• backfill 为 true：今日的不够数，这一项是拿昨天的补上的，value 是昨天的数。

• 套用你的内容过滤，过滤掉的不补，所以可能不到 limit 个。

3.7 目录、阅读和播放

作品分成几个单元，单元里是条目：

条目的用途在 role 里（如 page、chapter、main、pv、track、script），全部取值和名字看 GET /meta 的 content_types[].item_roles。

• 这一节的接口都不花积分、不用解锁（下载见第 8.3 节）；记阅读进度、续播见第 5.6 节。

• 看不到的一律返回 10004：作品没公开、下架、删除、不存在，单元定时还没到点、暂不公开、被下架，按访客算时还有带「要登录才能看」标签的作品。你自己投的、还没公开的内容也能取，带 preview: true。

• 有的分级要登录才能读（GET /meta 里这一档的 ratings[].requires_login 为 true）。按访客算时（没带令牌、令牌无效，或者没有「浏览」用途），这种作品的目录照样能取，取条目、正文、文本、播放列表、弹幕返回 10002（换成带「浏览」用途的有效令牌就能取），作品详情的 viewer.can_read 为 false；图片、视频、音频带 restricted: "login_required"，不给地址，只有尺寸和 placeholder。

• 取条目、正文、文本、播放列表、地址按用户和 IP 限频，超过返回 10006；正常阅读碰不到。

目录

GET /works/{id}/units：作品的全部单元，按顺序一次给完，不分页 → { "items": [单元] }。

GET /units/{id}：一个单元和它前后的单元 → { "unit", "work", "prev", "next" }。prev、next 是上一个、下一个单元，没有为 null；work 是简短的作品（id、content_type、title、title_lang、rating、cover）。

另有 preview、status、publish_at，投稿人看自己还没公开的单元时用。

条目

GET /units/{id}/items?start=&limit=：一个单元的条目，按下标取（不是游标）。start 是从第几个开始（0 起，默认 0；负数返回 10001），limit 默认 40、最大 100 → { "items": [条目], "total", "next_start" }。total 是这个单元的条目总数，next_start 是下一批的 start，取完了为 null。取整个单元：从 0 开始，每次把 next_start 当作下一次的 start，直到它为 null。

条目有 id、unit_id、index（在单元里的下标）、kind、role、title（投稿人起的名字，没起为 null），另有 image、text、video、audio 四个字段：和 kind 同名的那个有值，别的为 null。遇到不认识的 kind 跳过。

• 页、插图：image 是图片，原图在 image.original（可能为 null），各规格在 image.styles。

• 小说的章：text 是 { "title", "word_count", "published_at" }（章名、字数、公开时间），不带正文。

• 音声的文本：text 是 { "name", "size" }（文件名、字节数）。

视频（video）和音频（audio）的主要字段：

小说：目录和正文

GET /works/{id}/toc?script=：小说带章名的完整目录，一次给全 → { "work_id", "word_count", "units", "preview" }。units 里每卷是 { "id", "title", "word_count", "items" }，items 里每章是 { "id", "index", "title", "word_count", "published_at", "updated_at", "likes" }（likes 是这一章的点赞数）。

• 只列已公开的章，按阅读顺序；一章都没公开的卷不列。index 是章在这一卷已公开的章里的位置。

• 响应带 ETag：请求带上 If-None-Match 并且目录没变时回 HTTP 304，没有响应体。

GET /items/{id}/text?script=：一章的正文 → { "item", "unit", "work", "script", "blocks", "author_note", "prev", "next", "preview", "text_version" }。

• item 是这一章：id、unit_id、index、title、word_count、published_at、updated_at、likes 点赞数、viewer.liked 你点过没有；unit 是 { "id", "title" }；work 是简短的作品。

• prev、next：上一章、下一章（跨卷，只算已公开的）{ "id", "unit_id", "title" }，没有为 null。

• text_version：这份公开正文的版本（一串字符，正文改了就变）；发段评时放进 anchor.text（第 6.1 节）。

• blocks、author_note：正文和「作者的话」解析好的块（没有作者的话为空数组）。块的 type 是 p 段落 / blank 空行 / hr 分隔线 / image 插图，n 是块的序号（0 起）。段落的 content 是一串片段：text 普通文字、ruby 注音（text 是正文、ruby 是读音）、em 着重号、note 注释（text 是注释的文字：在这里画一个记号，点了弹出；不算字数）。插图块有 uid、image（图片，可能为 null）、caption（说明，没有为 null）。不认识的块跳过，不认识的片段当普通文字。

• 样式：段落和片段可以有 style（原书或作者设的，只有设了的键）：align（left / center / right，段落）、size（相对字号）、bold、italic（false 是取消）、font（serif / sans / mono）、color（#rrggbb）、indent、space_before、space_after（段落，单位 em）、letter_spacing（em）、valign（sup / sub）、underline、strike；插图块可以有 style：align、width、height（em，按阅读器的字号；只有一个时另一个按比例），没有的整宽。不认识的键忽略。

• 只有小说的章有正文，别的条目返回 10004；已发布作品里还没公开的章（定时、下架这类）谁都取不到，也是 10004。

• 默认每分钟最多 120 章（以站点设置为准）。取正文不记浏览：浏览只在有人真的打开阅读页时由浏览器报（POST /works/{id}/views），程序取数据不用报。

两个接口的 script：original 原文（默认）/ hans 简体 / hant 繁体，在服务端按词转换，卷名、章名、正文、作者的话、插图说明都跟着转，注音的读音不转；别的值返回 10001。

data = call("GET", "/items/5013/text", params={"script": "hans"})
print(data["item"]["title"])
for b in data["blocks"]:
    if b["type"] == "p":
        print("".join(s["text"] for s in b["content"] if s["type"] != "note"))
        for s in b["content"]:
            if s["type"] == "note":
                print("  注：" + s["text"])
    elif b["type"] == "blank":
        print()
next_id = data["next"]["id"] if data["next"] else None  # 下一章

小说：书内搜索

GET /works/{id}/text-search?q=&script=&cursor=&limit=：在一部小说里搜正文 → { "script", "items", "total", "total_exact", "next_cursor" }。能读这部小说才能搜（同 GET /items/{id}/text）：看不到、不是小说 10004，要登录才能读的分级没登录 10002。

• q：要搜的字，去掉首尾空白以后 1 到 50 个字（以 /site 的 limits.novel_text_search_query_max 为准）；西文不分大小写。没带 10001（q: required），太长 10001（q: too_long）。

• script：同上，在转换以后的正文里搜，q 也照它转一遍；位置、前后文、章名都是转换以后的样子。

• items 按阅读顺序（卷、章、块），每一处是 { "item": { "id", "unit_id", "title" }, "n", "offset", "length", "before", "match", "after" }：n 是块的序号，offset、length 是在那一块纯文字里的位置和字数（纯文字是段落各片段的文字接起来：注音只留正文、着重去掉标记、注释不算；按 Unicode 码点数），before、after 是前后各最多 20 个字，match 是搜到的原文。一处不跨块，不重叠。

• 一次最多数 1000 处（以站点设置为准）：total_exact 为 false 时 total 是「至少这么多」。

• 翻页：limit 默认 50、最多 200，next_cursor 带到 cursor 取下一页，为 null 是没有了。换了 q、script，或者正文改了，旧的 cursor 返回 10001（cursor: invalid），从第一页重新搜。

• 默认每分钟最多 30 次（翻页也算，以站点设置为准）。

page = call("GET", "/works/12/text-search", params={"q": "星海"})
for h in page["items"]:
    print(h["item"]["title"], h["n"], h["before"] + "[" + h["match"] + "]" + h["after"])

音声：播放列表和文本

GET /works/{id}/playlist：一部音声的全部分组和条目，一次给完 → { "work_id", "duration", "units" }，units 里每个分组是 { "id", "title", "items": [条目] }。duration 是全部音轨的总时长（秒），有还在处理的为 null。条目按投稿人排的顺序，音轨、插图、文本混在一起，只要音轨就取 kind 为 audio 的。没有音频条目的类型返回 72016（动画按集用 GET /units/{id}/items 取）。

GET /items/{id}/content：音声文本条目（剧本、台本）的内容 → { "id", "name", "content" }，content 是原样的纯文本。别的条目返回 72016（小说的章用 GET /items/{id}/text）。

重新要地址

POST /media/urls：图片、视频、音频的地址取不到（主地址和 fallbacks 都失败，或者返回 403、410），或者快到 expires_at 时，按 uid 换新的地址。请求体 { "uids": ["…"] }，1 ~ 100 个 → { "items", "missing" }。

• items 每项有 uid、kind（image / video / audio）、status（processing / ready / failed，failed 的没有地址），和 kind 同名的字段里是完整的图片、视频或音频。按请求的顺序给，重复的只给一次。

• 只给你看得到的：下架、删除、不存在、看不到的 uid 都在 missing 里，不分原因。

• 平时不用调：上面这些接口返回时已经带着地址。

3.8 评论和弹幕

评论

评论跟着作品：看得到作品就看得到它的评论，看不到的返回 10004。发评论、点赞见第 6.1 节。

GET /works/{id}/comments?unit_id=&item_id=&paragraph=&all=&sort=&cursor=&limit=：一级评论，游标分页 → { "items", "next_cursor", "total" }，total 是一级评论的条数。

• 不带 unit_id、item_id 是作品下面的；带了是那一话、一集、一章的。小说的 item_id 是这一章的「本章说」，不列段评；再带 paragraph（块的序号）是这一段的段评，没带 item_id、负数返回 10001。各内容类型能在哪几处评论看 GET /meta 的 content_types[].comment_scopes（work / unit / item）。不是这部作品的、这种类型不能在那一处评论的返回 10001，看不到的集、章返回 10004。

• all=true：这部作品全部的评论（作品、各集、各章混在一起，看 unit、item 区分；不列段评）；只列你看得到的那几处（定时、暂不公开、下架的集，没公开的章上的不列，total 也不算）；再带 unit_id 或 item_id 返回 10001。

• sort：hot 热门（默认：赞和回复多的在前，新发的也往前排）/ new 新的在前 / old 早的在前，别的返回 10001。换了 sort 要从第一页取，拿旧的 cursor 返回 10001。

GET /items/{id}/paragraph-comments：小说一章各段的段评数 → { "item_id", "counts": [{ "n", "count" }] }，只列有段评的段、按序号；数的是一级评论（删了但下面还有回复的也算，同列表的 total）。打不开这一章的返回同 GET /items/{id}/text（10004、10002）。

GET /bounties/{id}/comments?sort=&cursor=&limit=：求档下面的一级评论，规矩同作品的（没有 unit_id、item_id、all），is_uploader 是求档的发起人；求档不存在返回 10004。

GET /comments/{id}/replies?cursor=&limit=：一条一级评论下的回复，游标分页、早的在前 → { "items", "next_cursor", "total" }。不是一级评论的返回 10004。

GET /comments/{id}：一条评论；是回复时另带 parent（它所在的一级评论，不带那条的 replies）。删了的返回 10004。

弹幕

弹幕只在视频条目（kind 为 video）上，别的条目返回 72016。站点关了弹幕（GET /site 的 features.danmaku 为 false）时返回 10003；分级要登录才能看、按访客算时返回 10002。发弹幕见第 6.5 节。

GET /items/{id}/danmaku?segment=：按时间分段取一个视频的弹幕 → { "segment", "segment_seconds", "segments", "total", "items" }。

• segment：第几段（0 起，默认 0），是视频从第 segment × segment_seconds 秒到第 (segment + 1) × segment_seconds 秒（不含）的弹幕；负数、不是整数返回 10001，超出的给空的 items。

• segment_seconds 是一段多少秒（默认 360，以站点设置为准），segments 是这个视频一共几段，total 是这个视频一共多少条。

• items 按 time 排。一段最多给 3000 条（默认，以 GET /site 的 danmaku.segment_max 为准），超了按时间均匀抽取；你自己发的总在里面。

一条弹幕：id、time（第几秒，一位小数）、mode（scroll 滚动 / top 顶部 / bottom 底部）、color（#RRGGBB）、text（一行纯文本）、sender（发的人的代号，12 个十六进制字符：同一个人全站一样，查不出是谁）、created_at、mine（是不是你发的）。

seg, segs = 0, 1
while seg < segs:
    data = call("GET", "/items/7001/danmaku", params={"segment": seg})
    segs = data["segments"]
    for d in data["items"]:
        print(d["time"], d["mode"], d["text"])
    seg += 1

3.9 片单和用户主页

片单和收藏夹

公开的收藏夹就是片单（管理自己的收藏夹、给片单点赞见第 5.4 节）。收藏夹的字段：id、name、description（纯文本）、public、is_default（是不是默认收藏夹）、item_count（一共几部）、covers（最近放进来的最多 4 部作品的封面）、user（主人）、item_order（夹里默认的排法：added 新放进来的在前 / manual 主人手排）、like_count、liked（你赞过没有）、created_at、updated_at。

GET /collections?q=&sort=&page=&page_size=：片单广场，只列公开的、至少有 3 部作品（默认，以站点设置为准）的收藏夹。q 在名字、简介里找；sort：popular 赞多的在前（默认）/ new 新建的在前 / updated 最近改过的在前，别的返回 10001。

这个接口是页码分页：page 从 1 起（默认 1），page_size 默认 20、最大 100（超过按 100，小于 1 按默认，不报错）→ { "items", "pagination": { "page", "page_size", "total", "total_capped" } }。total 最多数到 10000，超过时 total_capped 为 true。pages() 不适用，按下面的例子自己翻页。

GET /collections/{id}：一个收藏夹。私有的只有主人看得到，别人返回 10004。

GET /collections/{id}/items?q=&content_type=&sort=&cursor=&limit=：夹里的作品，游标分页 → { "items", "next_cursor", "total" }，total 是符合条件的部数。

• q 按标题、别名找；content_type 只看一种内容类型（不认识的返回 10001）；sort：added 放进来的时间（新的在前）/ manual 主人手排的顺序 / updated 作品最近更新的在前 / title 按标题，不带时按夹的 item_order。换了参数要从第一页取。

• 每项是 { "work", "work_status", "note", "added_at" }：work 是作品列表项，note 是主人写的备注。只列你看得到的作品，也套用你的内容过滤。

page = 1
while True:
    data = call("GET", "/collections", params={"sort": "new", "page": page, "page_size": 100})
    for c in data["items"]:
        print(c["id"], c["name"], c["item_count"], c["like_count"])
    if len(data["items"]) < data["pagination"]["page_size"]:
        break
    page += 1

用户主页

GET /accounts/{id} → { "account": { "id", "name", "avatar", "deleted" }, "created_at", "stats": { "works", "co_created_works", "collections", "comments" } }。created_at 是注册时间；stats 是已发布的投稿数（你看得到的）、共创的已发布作品数、公开的收藏夹数、评论数。没有这个人、已注销的返回 10004。

GET /accounts/{id}/comments?cursor=&limit=：他写的评论（一级和回复都算，新的在前），游标分页 → { "items", "next_cursor" }，每项是 { "comment", "work" }（评论、作品列表项）。只列你看得到的作品上的，删了的不列。

GET /accounts/{id}/collections：他公开的收藏夹，一次给全 → { "items": [收藏夹] }；没有这个人、一个都没公开的是空数组。

他投的作品用 GET /works 的 uploader 参数取，他当共创者的作品用 co_creator 参数取。

3.10 求档

求档是用户挂积分求一部站里还没有的作品（规则和发起、应征见第 9 节）。这两个接口不用「求档」用途；带「浏览」用途时 my_stake 按你算。

GET /bounties?status=&content_type=&rating=&q=&sort=&page=&page_size=：求档列表，页码分页（同 GET /collections）。

• status 默认 open，可以逗号分隔几个，all 是全部；content_type、rating 可以逗号分隔几个；q 在标题、说明里找。

• sort：new 新发的在前（默认）/ amount 悬赏多的在前 / expiring 快到期的在前。

• status、sort 不认识返回 10001。

GET /bounties/{id}：一个求档，另加 stakes 和 answers。没有这个求档返回 10004；取消了的照样能看。

• stakes：挂了积分的人 [ { "account", "amount", "created_at" } ]，一个人加了几次合成一条，多的在前。

• answers：应征，新的在前，撤回的不列。每项有 id、account（应征的人）、work（作品列表项，看不到了为 null）、status（pending 待处理 / accepted 采纳了 / rejected 拒了）、given（采纳时拿到的积分）、reject_reason、auto_accept_at、created_at、decided_at，含义见第 9.2 节。

data = call("GET", "/bounties", params={"status": "open", "sort": "amount", "page_size": 50})
for b in data["items"]:
    print(b["id"], b["amount"], b["content_type"], b["title"], b["expires_at"])

4. 投稿（用途「投稿」）

投稿的完整流程——建草稿、传文件、排结构、填信息、提交审核，发布以后加新的一集、改作品信息、改已经上线的集，小说的写作、导入和按章发布——写在「投稿接口」页，那里有上传文件用的客户端代码和每一步的例子。这里列出全部投稿接口备查。只有账号能投稿时，令牌才能选「投稿」用途；免不免审跟着账号走。

投稿：从草稿到提交

文件

结构和条目

我的作品

作品共创

一部作品有一个创建者（就是投稿人，作品的 uploader）和最多 10 个（默认）共创者（作品详情的 co_creators）。共创者和创建者一样管内容：加新的一集、改集、改作品信息、定时、重新转码、小说的写作和导入，看没公开的部分，自己的作品免费看、下载不算次数。只有创建者能做的：改价格、邀请和移出别人、转让（共创者调是 10003，data.reason 是 owner_only）；分成、打赏、悬赏归创建者。

只能对已发布的作品申请加入、邀请、转让、申请接管。站点关了共创（GET /site 的 features.co_creation 为 false）时，申请、邀请、转让、接管和同意、拒绝、撤回都返回 10003（data.reason 是 feature_off），移出、退出照样能用。申请加入、申请接管、邀请、转让按人限频（默认每小时 30 次）。作品页能不能申请看作品详情的 viewer.co_creation（第 3.4 节）。

• 申请、邀请、转让、接管是同一个形状：id、kind（apply / invite / transfer / takeover）、status（pending 在等 / accepted / declined / canceled 撤回了或没法再同意 / expired 过期）、work、user（申请的、被邀请的、接收的人）、created_by、message、keep_creator、granted（接管批准成了 owner 还是 co_creator）、note（站务的说明）、created_at、expires_at（申请、邀请、转让 14 天，接管 30 天，默认）、decided_at。

• 不能申请、邀请、转让时是 72026，data.reason：owner（自己是创建者）/ member（已经是共创者）/ self（邀请、转给自己）/ pending（已经有一份在等的，data.request_id）/ cooldown（被拒以后 7 天内（默认）不能再申请，data.available_at）/ full（共创者满了，data.max）/ active（作品还没停更满 30 天，不能申请接管，data.available_at）/ no_owner（作品没有创建者，可以申请接管）/ not_published（作品没发布）。

• 已经不在等了的申请再同意、拒绝、撤回是 72027（data.status 是它现在的状态）；不归你处理的、不是你发起的是 10004。

• 移出、退出、转让时不再管这部作品的人，他在这部作品上没完成的修改（加集、改集、改信息）作废。

• 有人申请、邀请、转让、结果出来时发通知 co_creation（第 7 节）。

小说：写作、导入、发布

5. 书架（用途「书架」）

这一节读写的都是你自己的数据，令牌要有「书架」用途。下文数字后面标了「（默认）」的，以站点设置为准；「10001（follows: too_many）」表示返回 10001，data.errors 里 follows 的原因是 too_many。

5.1 追番追更

列表每项是 { "work", "followed_at", "new_units" }，work 是作品列表项（同 GET /works 的 items）：

• new_units：你上次报这部作品的阅读进度以后（没报过的从关注时算；标为已读过的从标的时候算）新公开的单元数，小说是章数；没有为 0。只有报进度（PUT /me/progress/{work_id}，第 5.6 节）和标为已读（POST /me/follows/read）会把它清零，读作品详情、单元、条目都不会。

• 下架、删除的作品不在列表里，恢复后回来。最多关注 2000 部（默认），超出 10001（follows: too_many）。

5.2 关注标签、创作者、系列

• PUT 返回 { "following": true }，DELETE 返回 { "following": false }；取消本来没关注的也不报错。

• 每种最多关注 1000 个（默认），满了 10001（follows: too_many）；关注着的里后来禁用了的、还在审核的不算。不存在、禁用了、还在审核的不能关注（10004）。

• 合并掉的标签、创作者、系列：用旧 id 关注或取消，作用在合并进的那个上；已有的关注会转过去（followed_at 不变）。关注后被禁用的不列出，重新启用后回来。

5.3 关注动态和订阅链接

GET /me/feed：关注动态，游标分页，新的在前。包括最近 30 天（默认）里：

• 你关注的标签（连同下位标签）、创作者、系列的新作品（这段时间里首次发布的）；

• 你关注的作品新公开的集、话、章（作品首次发布时一起公开的不算）。

两种都按你的内容过滤设置筛过；一共最多 500 条（默认），更早的不列。每项的字段：

订阅链接：GET /feeds/me?token=…&limit= 读同一份关注动态。

• 这个接口不认个人令牌，不用带 Authorization；认的是查询参数 token 里的订阅令牌（acgf_ 开头）。订阅令牌只能登录网站后获取、更换、删除（第 12.1 节），它只能读你的关注动态；泄露了就在网站上换一个，旧的立即失效。

• 返回 { "account": { "id", "name", "avatar", "deleted" }, "items": [ … ] }：account 是令牌的主人，items 同 GET /me/feed 的第一页（按主人的内容过滤）。不分页，limit 不带时 20，最多 100。

• 令牌不对、已更换或删除，或者主人被封禁、注销：10002。

• 按 IP 限频（失败的也算），每小时 120 次（默认）。响应带 Cache-Control: private, max-age=300，可以缓存五分钟。

curl -s "$ACG_API/feeds/me?token=$ACG_FEED_TOKEN&limit=50"   # 订阅令牌，不是个人令牌

5.4 收藏夹和片单

每人有一个默认收藏夹（第一次调 GET /me/collections 时自动建好，is_default 为 true，能改名，不能删），另外最多能建 100 个（默认）。公开的收藏夹就是片单，别人能看到、点赞。收藏夹对象的字段见第 3.9 节；自己的夹 liked 总是 false。

• 名字：空的 name: required，太长 too_long，有换行这类控制字符 invalid；简介、备注太长 too_long（都是 10001）。

• PUT /works/{id}/collections：有不是你的夹 10001（collection_ids: unknown）；一个夹最多 5000 部（默认），满了 10001（collection_ids: too_many）；作品看不到 10004（收藏后才下架的照样能拿出来、改备注）。只想往一个夹里放时，用上面的 POST /me/collections/{id}/items；要用这个接口，先从作品详情的 viewer.collection_ids 取现在的夹（令牌要同时有「浏览」用途），加上新的一起提交。

GET /me/collections/{id}/items 的参数：q 按标题、别名找；content_type 只看一种内容类型（不认识的 10001）；sort：added 放进来的时间（新的在前）/ manual 手排 / updated 作品最近更新的在前 / title 按标题（中文按拼音），不带按夹的 item_order，别的值 10001（sort: unknown）。换了参数要从第一页重新取。每项是 { "work", "work_status", "note", "added_at" }：work 是作品列表项，note 是你的备注，work_status 是作品现在的状态（draft / pending / rejected / published / taken_down / deleted），下架、删除的作品照样列在你的夹里。

片单的赞：

• 片单不存在或是私有的 10004，赞自己的 10005。

• GET /me/liked-collections 是页码分页：page（从 1 起）、page_size（不带时 20，最大 100）→ { "items": [ … ], "pagination": { "page", "page_size", "total", "total_capped" } }。pages() 不适用，按 page 自己翻。

default = call("GET", "/me/collections")["items"][0]
for it in pages(f"/me/collections/{default['id']}/items", {"sort": "added"}):
    print(it["work"]["title"], it["work_status"], it["note"])

5.5 历史和看过的集

历史就是你的阅读进度（第 5.6 节）按最近读的排。「看过」按单元（一集、一话）记。

• GET /me/seen 的 work_id 必填：没带 10001（work_id: required），不是数字 10001（work_id: invalid），作品看不到 10004。

• 标、取消返回的 seen 是现在的状态；重复标、重复取消都不报错；单元看不到 10004。

• 报进度时也会自动标：请求体带 "finished": true 就把那个单元记成看过，false 不记；不带时按站点的规则：漫画报到这一话的最后一页；动画的正片（花絮、PV 不算）、音声这一组的最后一条音轨，播到离结尾 2 秒（默认）以内。小说报进度不会自动标，可以手动标。

• 暂停记录：你在个人设置（第 11.2 节）里暂停了历史记录（history.paused 为 true）时，报进度、标看过都不保存：报进度照样返回进度对象，但 recorded 为 false；PUT /me/seen/{unit_id} 返回原来的状态。取消看过、删历史照常能用。

5.6 阅读进度和书签

每部作品只有一条进度，后报的覆盖先报的（不比较客户端时间），报得再频繁也不会出错。进度对象除了 work_id、updated_at，还有：

• 报进度：单元不在这部作品里、条目不在这个单元里 10001（unit_id: unknown 或 item_id: unknown）；paragraph、position 是负数 10001（invalid）；作品看不到 10004。paragraph 只用于小说；position 只对视频和音频有用，别的条目、单元开头带了不报错也不记。

call("PUT", "/me/progress/12", {"unit_id": 301, "item_id": 9001, "position": 128.4})

小说的书签

书签：{ "id": 77, "work_id": 12, "unit_id": 101, "item_id": 6001, "paragraph": 42, "excerpt": "星海的尽头是另一片星海", "created_at": "…" }。

• excerpt 从那一段自动截取：纯文字（注音只留正文、着重去掉标记、注释不算），前 100 字；插图、分隔线和超出范围的段号是空串。

• 加书签时带了 excerpt（读者选中的字）：去掉首尾空白以后不为空、是那一段纯文字里连着的一截（阅读时开了简繁转换的，转换以后的字也认）就用它当摘录，最多 100 字；不然照旧自动截取，不报错。

• 一部小说最多 100 个书签（默认），满了 10001（bookmarks: too_many）；paragraph 没带或是负数 10001；item_id 不是小说的章、作品看不到 10004。

• 作者改了正文，书签跟着挪到那一段新的段号（几秒内；摘录不变）；那一段删了的留在原来的段号上（超出这一章的放在最后一块）；同一个人两个书签挪到同一段的只留早加的那个。

6. 互动（用途「互动」）

这一节的操作都以你的账号进行：评论和弹幕公开显示（弹幕只带一个匿名代号，不显示名字），评分、点赞和标签投票计入作品的公开统计，纠错和举报交给站务处理。

被禁言时（GET /me 的 restrictions 里有 kind 为 mute 的一项），发评论、改评论、补标签、提纠错、发弹幕都返回 75005，data 是 { "kind": "mute", "until", "reason" }（until 为 null 表示永久）；给标签投票、评分、举报不受影响。

6.1 评论

POST /works/{id}/comments 发评论或回复，返回新评论（同 GET /comments/{id}）；求档下面用 POST /bounties/{id}/comments，请求体相同，但不能带 unit_id、item_id、anchor。请求体：

• @ 提醒：正文里的 @名字 按显示名或用户名识别（不分大小写），名字后面要跟空白、标点或结尾（_、-、. 算名字的一部分），@ 前面紧挨着字母或数字的不算；一条最多识别 10 个（以站点设置为准），结果在评论的 mentions 里。回复会通知被回复的人，@ 到的人另有通知；回复自己、@ 自己不通知。

• 段评：在小说一章（带 item_id）发一级评论、anchor 是 { "kind": "paragraph", "item_id", "n" } 就是那一段的段评，n 要是这一章公开的正文里有字的段落（分隔线、空行、插图、超出范围的返回 10001 anchor: invalid）。带上 anchor.text 时，正文在你读的时候被改过（版本对不上）返回 10005：重新取这一章、再发。作者改了正文、段的序号变了，段评跟着挪到新的序号（anchor.n 一起改）；那一段删了的变成本章说（anchor 为 null），那一段回来了再挂回去。

• 其他参数错误：parent_id: unknown（不是这部作品的一级评论，或已删除）；reply_to_id: unknown（不在这条楼里）或 invalid（没带 parent_id）；unit_id: unknown（不是这部作品的集）；unit_id / item_id: invalid（这种内容不能在那一处评论）；anchor: invalid（种类和条目对不上，或不在这一集、这一章里）；anchor.item_id: unknown（不是这部作品的条目）。

• 作品看不到、没发布，或者那一集、那一章看不到，返回 10004。正文含站点不允许的词返回 74001，data.hits 是 [{ "word", "count" }]（普通词按包含匹配，不分大小写和全角半角；按规则匹配的，word 是匹配到的原文）。发得太快返回 10006（默认每人每分钟 10 条）。

改、删别人的评论返回 10003；评论已删除、作品看不到了返回 10004。

c = call("POST", "/works/12/comments", {"body": "这一话的分镜很好看", "unit_id": 101})
call("POST", "/works/12/comments", {"body": "同感", "parent_id": c["id"]})

6.2 打分

• stats 是这次改完以后的统计：score 是平均分（1 ~ 10，保留一位小数），score_count 是打分人数；人数不到 3（以站点设置为准）时 score 为 null。

• 给自己投稿的、自己共创的作品打分返回 10003；分数不是 1 ~ 10 的整数返回 10001（score: invalid）；作品看不到或没发布返回 10004。

• 你打过的分也在 GET /works/{id} 的 viewer.rating 里（令牌要有「浏览」用途；没打过为 null）。

6.3 点赞一集、一章

给作品的一集点赞。点赞和收藏是两回事：收藏放进自己的收藏夹（第 5.4 节），点赞只给这一集加一个数。在哪一级点看 GET /meta 的 content_types[].like_on：漫画、动画、音声是 unit（每一话、每一集、每一组），小说是 item（每一章，卷不能点）。作品本身不能直接点，作品的 stats.likes 是各集、各章的点赞加起来。

• 那一集、那一章看不到或者还没公开（定时、暂不公开、被下架的，作品没发布的），或者那一级不能点（小说的卷、漫画的页这类），返回 10004。

• 给自己投稿的、自己共创的作品点赞返回 10003。

• 点得太快返回 10006（点赞和取消一起算，默认每人每分钟 30 次，以站点设置为准）。

• 你点过没有在单元的 viewer.liked（GET /works/{id}/units、GET /units/{id}）和章节正文的 item.viewer.liked 里（令牌要有「浏览」用途）。

r = call("PUT", "/units/101/like")
print(r["likes"], r["stats"]["likes"])

6.4 补标签和投票

作品上显示哪些标签由投票决定。GET /works/{id}/tags 列出候选标签和两条线 thresholds（默认 show 为 3、remove 为 -3）：没显示的候选分数到 show 才显示，显示着的掉到 remove 以下才撤下。每一票有权重（按投票人以往补的标签被采纳的比例算），所以 score 不一定等于票数；站务锁定的标签（locked 为 true）不能投票。

PUT /works/{id}/tags/{tag_id}/vote 投票：{ "vote": 1 }，1 赞成、-1 反对、0 撤回；返回这个标签的最新状态（同 GET /works/{id}/tags 的 items 里的一项）。没带 vote 报 vote: required，别的值报 vote: invalid；标签被锁定返回 72023；作品看不到、没发布，或者标签不是这部作品的候选，返回 10004。

POST /works/{id}/tags 补标签：已有的标签带 { "tag_id": 45 }，新提一个带 { "namespace": "female", "name": "眼镜" }（命名空间代码见 GET /meta 的 tag_namespaces）；返回同上。别名会换成正式标签，补的人自动投一票赞成。新提的标签要站务通过以后才算数。你补的标签第一次显示时会发积分奖励（同一部作品的同一个标签只发一次，每天有上限）。参数错误（10001）：

作品的标签列表被锁定、或者这个标签被锁成不显示时返回 72023；作品看不到、没发布返回 10004。投票和补标签合计默认每人每分钟 60 次，超过返回 10006。

call("POST", "/works/12/tags", {"tag_id": 45})
call("PUT", "/works/12/tags/46/vote", {"vote": -1})

6.5 弹幕

只有视频条目（GET /units/{id}/items 里 kind 为 video 的）有弹幕，别的条目返回 72016。站点关闭弹幕时（GET /site 的 features.danmaku 为 false），弹幕接口都返回 10003。

POST /items/{id}/danmaku 发一条弹幕，返回刚发的这一条（同 GET /items/{id}/danmaku 的 items 里的一条，mine 为 true）：

• 字段错误是 10001，键是上面的字段名。看不到这个视频（包括作品没发布、这一集还没公开）返回 10004；含屏蔽词返回 74001（同评论）；发得太快返回 10006（默认每人每分钟 20 条）。

• DELETE /danmaku/{id} 删自己的一条 → { "deleted": true }；别人的返回 10003，已删除或不存在返回 10004。站务删掉一个视频或删除作品时，上面的弹幕一起删掉。

d = call("POST", "/items/7001/danmaku", {"time": 615.5, "text": "前方高能", "mode": "top"})
call("DELETE", f"/danmaku/{d['id']}")

6.6 纠错和举报

POST /works/{id}/corrections 给作品信息纠错，交给站务处理：

• fields：必填，错在哪里，至少一项：titles 标题、description 简介、creators 创作者、series 系列、released_on 首发日期、codes 作品号、links 外部链接、other 其他。

• body：必填，说明，去掉两头空白后 1 ~ 1000 字。

返回纠错对象 { "id", "work", "fields", "body", "status", "note", "created_at", "decided_at" }：status 是 pending 待处理 / accepted 已采纳 / rejected 未采纳；note 是站务的回复（没写为 null）；work 是作品现在的摘要，看不到了为 null。处理后你会收到 correction 通知。参数错误：fields: required、fields[i]: unknown、body: required、body: too_long；没处理的纠错每人最多 5 条（以站点设置为准），多了报 corrections: too_many。作品看不到、没发布返回 10004。站点打开了纠错的词检查时（默认不检查），body 含站点不允许的词返回 75006，data.hits 同 74001。

GET /me/corrections 列出我提的纠错（游标分页，新的在前）→ { "items": [纠错对象], "next_cursor" }。

POST /reports 举报，请求体：

默认的原因如下（站务可以调整，以 GET /meta 为准）：

• 返回举报对象：id、kind、target_id、unit_id、item_id、reason、body、status（open 待处理 / resolved 已处理 / dismissed 不成立）、created_at、handled_at，以及 work、comment、user、danmaku：按 kind 给出被举报对象现在的样子，其余为 null。作品是作品摘要（看不到了为 null），用户是 { "id", "name", "avatar", "deleted" }，评论和弹幕是 { "id", "excerpt", "deleted" }（评论取前 50 字，弹幕是全文，已删除的 excerpt 为空串）。

• 同一个对象你只能有一条待处理的举报：再举报会更新原来那条的原因和说明（id、created_at 不变）；处理过以后再举报是新的一条。处理后你会收到 report 通知。

• 对象不存在或看不到（已删除的评论和弹幕、已下架的作品、已注销的用户）返回 10004。参数错误：kind: invalid；reason: invalid（不认识或不能用于这种对象）；body: too_long；target_id: own（举报自己，或自己的评论、弹幕、自己投稿和共创的作品）；unit_id / item_id: unknown（不是这部作品的或看不到）；unit_id / item_id: invalid（kind 不是 work、两个一起带、这种内容指不到这一级）。默认每人每分钟 10 次（失败的也算），超过返回 10006。

GET /me/reports 列出我的举报（游标分页，新的在前）→ { "items": [举报对象], "next_cursor" }。

call("POST", "/reports", {"kind": "comment", "target_id": 777, "reason": "spoiler", "body": "没有标剧透"})

6.7 按名字找用户

GET /accounts/search?q=月&limit=10 → { "items": [{ "id", "name", "avatar", "deleted" }] }：显示名或用户名以 q 开头的用户（不分大小写，按显示名排序），已注销的不在内。q 去掉两头空白后至少 1 个字，否则报 q: required；limit 默认 10，最多 20。写评论前可以用它确认要 @ 的名字。

7. 通知（用途「通知」）

站内通知，令牌要有「通知」用途。哪些种类会发由你的个人设置（第 11.2 节的 notifications）决定：关掉的种类不再生成，已有的留着。没读的通知从 updated_at 起保留 180 天，读过的从读的时候起保留 30 天；每人最多留 2000 条，多的删最旧的（都是默认，以站点设置为准）。

7.1 接口

ids = []
for n in pages("/me/notifications", {"unread": "true"}):
    print(n["kind"], n["count"], n["work"]["title"] if n["work"] else "")
    ids.append(n["id"])
if ids:
    call("POST", "/me/notifications/read", {"ids": ids})

7.2 通知的形状和种类

{ "id": 9001, "kind": "comment_reply", "read": false, "created_at": "…", "updated_at": "…",
  "actor": { "id": 5, "name": "示例用户", "avatar": null, "deleted": false }, "work": { "…": "作品列表项" },
  "comment": { "id": 777, "excerpt": "说得对……", "deleted": false }, "count": 1,
  "data": { "parent_id": 770, "unit_id": null, "item_id": null } }

• actor 是做这件事的人，work 是相关作品（作品列表项），comment 是相关评论；用不上的为 null，作品看不到了（比如下架）work 也为 null。

• comment.excerpt 是评论的前 50 个字；评论删了时 excerpt 为空串、deleted 为 true。

• 合并：work_update 同一部作品的、work_comment 和 income 同一部作品同一天、bounty_comment 同一个求档同一天（按站点时区）的没读的通知合成一条，count 累加、updated_at 更新；读了以后再来的另起一条。

• 你自己的评论不会通知你；同一条评论已经让你收到 comment_reply 或 mention 的，不再发别的种类。work_update、new_work 在内容公开后一两分钟内到，你创建的、共创的作品不发。

• 遇到不认识的 kind，跳过或者按 data 原样处理。

8. 积分（用途「积分」）

本节的接口要令牌带「积分」用途。会花积分的接口有：解锁 POST /unlocks、打赏 POST /works/{id}/tips，以及第 9 节的发起求档 POST /bounties、加码 POST /bounties/{id}/stakes（用途「求档」）。令牌带了这两种用途，程序就能花你的积分，请只给确实需要的程序。

这四个花积分的接口：

• 都必须带请求头 Idempotency-Key（1 ~ 64 个字符，只能是字母、数字和 -_.:），每次新的付款生成一个新的；没带或格式不对 10001。同一个键再请求，返回第一次的结果，不会重复扣分，所以网络出错时用同一个键重试是安全的（解锁连失败的结果也原样返回：积分不够时充值以后要换新的键）。同一个键、请求内容不一样 76007。

• 积分不够 76003，data 有 balance（你的余额）和 price（要扣的分）；账号封禁中不能付款 76006；积分暂时用不了 76005（没扣分，稍后再试）。

8.1 余额和变动

GET /me/points 返回：

• balance：余额。

• member：会员权益，不是会员为 null：role（code、name）、percent（解锁减百分之几，100 是免费）、daily_free（每天前几次解锁免费）、daily_free_left（今天还剩几次）。

• downloads：今天的下载次数：limit、used、reset_at（重置的时间）。

• checkin：签到：amount（签一次加几分，0 是签到没开）、done_today（今天签过没有）。

GET /me/points/entries：积分变动，新的在前，游标分页。每条有 id、kind、amount（加分为正、扣分为负）、title、work（相关的作品，没有或看不到为 null）、bounty_id（bounty、bounty_refund、bounty_income 三种是求档 id，其他为 null）、created_at。title 是作品名（动画带集名）、标签名或求档标题；signup、checkin 是空字符串。

p = call("GET", "/me/points")
print("余额", p["balance"])
for e in pages("/me/points/entries"):
    print(e["created_at"], e["kind"], e["amount"], e["title"])

8.2 签到

POST /me/checkin（不用请求体）→ { "granted": 5, "already": false, "balance": 1239 }

• 每天一次，按站点时区的自然日。签一次加 GET /me/points 里的 checkin.amount（默认 5，以站点设置为准）；签到和其他奖励一样有每天的上限，到了上限 granted 会比它少，可能是 0。

• 今天已经签过也返回成功：already 为 true、granted 为 0。所以每天定时调一次即可，多调没有副作用。

• 签到没开 76015。

r = call("POST", "/me/checkin")
print("今天签过了" if r["already"] else f"签到 +{r['granted']}", "余额", r["balance"])

8.3 解锁和下载

阅读、在线看、在线听（站点转码后的版本）都免费。要花积分解锁的是下载类的东西：哪种内容能下载什么、要不要解锁，看 GET /meta 的 content_types[].downloads（kind、scopes、options、paid）。默认是：漫画 zip（整本或一话）；动画 source（每个视频）、zip（一集）、stream（每个视频）；音声 stream、source（每条音轨）和 zip（整包）；小说 txt、epub（整本）。paid 为 true 的要先解锁，为 false 的登录就能下（照样算次数）。解锁的单位看 content_types[].pricing.scope：漫画、音声、小说按作品解锁（work，以后新加的话、章也包括在内），动画按集解锁（unit）。解锁永久有效。你自己投的作品不用解锁、不花分、不算次数。

价格由站点算，用 GET /works/{id}/price 取。

解锁

POST /unlocks（必带 Idempotency-Key），请求体：

现在的价和 expected_price 不一样时（活动结束、会员到期、作品改价）不扣分，返回 76002，data.quote 是最新的报价，确认以后用新的价和新的键再请求。价是 0 的（会员免费、限时免费）也调这个接口，不扣分；会员的每日免费次数同时用几次也只免费剩下的那几次，多出来的同样返回 76002。

返回这次解锁：

• id：字符串，查结果用。

• status：completed 解锁成功；pending 暂时不确定扣没扣分（很少见），站点会自动核对，请每隔几秒用 GET /purchases/{id} 查，一般几秒到几分钟内变成 completed 或 failed；failed 没扣分、没解锁。

• work、unit_ids（动画这次解锁的集，其他类型为空数组）、list_price（打折前）、amount（实际扣的分）、discounts[]（用上的折扣：kind 是 event 活动 / member 会员 / bundle 动画多集一起买，另有 name、percent、ends_at）。

• source：purchase 花分买的 / member 会员免费 / daily_free 会员的每日免费次数 / event 限时免费 / staff 站务补发。

• created_at、completed_at、refund（退款：at、reason、returned；没退为 null）。

GET /purchases/{id}：查一次解锁的结果，只能查自己的，返回同上。

GET /me/unlocks：我的解锁，新的在前，游标分页；可选 work_id 只看一部作品的。每项有 work、unit_ids 和 units（动画这次解锁的集：id、title）、source、amount、purchase_id、unlocked_at、expires_at（现在总是 null，即永久）、refunded、refund_reason、work_status（作品现在的状态，不是 published 的已下架或删除，不能下载）。

自动退款：作品被下架或删除时，之前 7 天内（以站点设置为准）花分的解锁全额退回（积分变动 refund），refunded 变成 true，refund_reason 是 work_taken_down / unit_taken_down / work_deleted（站务手动退的是站务写的原因）。动画单独下架某一集时，一次解锁里的集全部下架了才退。退了款的解锁不能再下载，作品恢复以后要重新解锁。

下载

POST /downloads，请求体：

打包下载（zip）的内容：

• 漫画：全部原图，按页编号（001.jpg……），不止一话时一话一个文件夹。

• 动画的一集：这一集各个视频的源文件；上传的字幕放在视频旁边，命名为 视频名.字幕 id.扩展名（如 ep01.zh-Hans.ass，播放器能自动加载）；Fonts/ 里是上传的字体和作品的字体。

• 音声：音轨的源文件、插图、台本，上传的字幕放在各自的音轨旁边（命名同上）。

• 字幕的格式：ASS、SSA 是原文件，PGS 是 .sup，SRT、VTT、LRC 是转换后的 WebVTT（.vtt）。源文件内嵌的字幕、字体在源文件里，不另外附带。source 只有上传的原文件。

返回：

• status：ready 给了地址；preparing 小说的文件还在生成，只给 retry_after（秒），过这么久用同样的请求再要（不算次数）。

• url：下载地址，支持断点续传；用的时候现要，不要存起来反复用。小说的是 /api/v1/novel-exports/ 开头的相对地址，接在接口地址的协议和主机后面，下载时不用带令牌，地址过期或不对回 HTTP 403。

• backup_urls：url 连不上（超时、5xx）时按顺序换着用，没有为空数组。

• expires_at：地址的有效期，默认下载 4 小时、在线播放 6 小时（以站点设置为准）。

• filename、size（字节，未知为 null）、purpose（download 下载 / stream 在线播放，可以拖进度）。

• counted：这次算没算次数；downloads_left：今天还能下几次（自己创建的、共创的作品为 null）；file_downloads_left：这次解锁这个文件还能下几次（不按解锁限次数时为 null）。

下载次数（GET /meta 的 download_limits：daily 每人每天几次，per_unlock 每次解锁每个文件几次（0 是不限））：

• 「同一个文件」指 kind、work_id、unit_id、item_id、options 都相同。上次算了次数的地址还没过期时，再要同一个文件不算（counted 为 false，照样给新地址），所以重试、续传不会多扣。stream 和自己的作品不算次数。

• 今天的次数用完 76011，data 有 limit、reset_at（按站点时区的自然日重置）。

• 这次解锁这个文件的次数用完 76014，data 有 limit、quote：照 quote.renew_price（动画是这一集的 units[].renew_price）用 POST /unlocks 带 renew: true 再解锁一次。

• 站点可能开启地址绑定 IP：地址只在要地址的那个 IP 上能用（IPv6 是同一个 /64），换了网络会回 HTTP 403，重新要一个即可（上一个没过期就不算次数）。

import time
from urllib.parse import urljoin
from acg_client import API, call

body = {"work_id": 123, "kind": "epub", "options": {"script": "hans"}}
d = call("POST", "/downloads", body)
while d["status"] == "preparing":
    time.sleep(d["retry_after"])
    d = call("POST", "/downloads", body)
print(urljoin(API, d["url"]), d["filename"])  # 小说给的是相对地址，接到接口地址的主机上

8.4 打赏和收入

POST /works/{id}/tips（必带 Idempotency-Key）给作品打赏积分。请求体：amount（必填，整数，在 GET /meta 的 tips.min ~ tips.max 之间）、message（可选，给投稿人的一句话，最多 100 字，只有投稿人在通知里看得到）。

返回 tip 和 balance（打赏以后你的余额）。tip 有 id、work、amount（你打了多少）、given（投稿人实际拿到的）、message、created_at。投稿人按分成比例拿（默认 70%，向下取整；每个投稿人每天的分成有上限，到了就少给），其余作废。

• 76016 打赏不了，data.reason：off（站点关了打赏，tips.enabled 为 false）/ own（你是这部作品的创建者；共创者能打赏，积分归创建者）/ no_uploader（作品没有投稿人）。

• 作品不存在、看不到、没发布 10004；amount 不在范围里（amount: invalid）、message 太长（message: too_long）10001。

• 每人默认每分钟最多 20 次（失败的也算），超了 10006。

GET /me/income：你投的作品各被解锁了几次、一共分到多少，最近有解锁的在前，游标分页。别人解锁你的作品时，你按同样的分成比例拿实付的积分。每项：work、unlocks（完成的解锁次数，会员免费、限时免费的也算，退了款的不算）、income（实际分到的积分，退了款的不算）、last_at（最近一次解锁的时间，后来退了款的那次也算）。下架的作品照样列出。

r = call("POST", "/works/123/tips", {"amount": 50, "message": "谢谢分享"}, idempotent=True)  # 自动重试沿用同一个键
print("投稿人拿到", r["tip"]["given"], "余额", r["balance"])

9. 求档（用途「求档」）

求档是挂积分求一部站里还没有的作品。规则在 GET /meta 的 bounties：enabled（关着时不能发起、加码，开着的求档照常应征、采纳、到期退回）、min ~ max（一次挂多少积分）、days（默认几天到期）、max_days（最长几天）、review_days（应征以后几天不处理就自动采纳）。

1. 发起人用 POST /bounties 发起，挂的积分当时就扣（积分变动 bounty）。别人可以用 POST /bounties/{id}/stakes 加码，同样当时扣。

2. 有人把这部作品投稿、发布以后，用 POST /bounties/{id}/answers 拿这部作品应征。

3. 发起人采纳一个应征：应征的人按分成比例（默认 70%，向下取整）拿走全部悬赏（bounty_income），其余作废，别的待处理的应征自动拒掉。发起人也可以拒掉应征。应征以后 review_days 天发起人还没处理的自动采纳（几个都到了时采纳最早的）。

4. 到了 expires_at 还没采纳、也没有待处理的应征时，积分原样退回给每个挂了积分的人（bounty_refund）；到期时还有待处理的应征就等它们处理完（都拒了马上退回）。发起人取消时也原样退回。

自动采纳和到期退回在时间到了以后十分钟内处理。求档的 status：open 开着 / fulfilled 采纳了 / expired 到期退回了 / cancelled 取消了（发起人或站务取消，积分已退回）。应征的 status：pending 待处理 / accepted 采纳了 / rejected 拒了；撤回的应征直接删掉。

9.1 发起、加码、取消

三个接口都返回求档对象，和 GET /bounties 列表里的一项相同（不带 stakes、answers），my_stake 是你挂的积分。

• 76017 发起、加码不了，data.reason：off（站点关了求档）/ too_many（你开着的求档到了上限，只限发起）。

• 75005 被禁言时不能发起（加码、应征不受影响）。

• 75006 标题、说明含站点不允许的词，data.hits 是 [{ "word", "count" }]（同评论的 74001）。

• 10005 求档不是 open 的不能加码、取消；有人加码或有待处理的应征时不能取消。10003 不是发起人不能取消。

• 10001 的字段原因：content_type、rating 不认识 invalid；title 空的 required、太长 too_long；description 太长 too_long；amount、days 不在范围里 invalid。

• 发起和加码每人默认每小时 20 次（失败的也算），超了 10006。

9.2 应征、采纳、拒

应征对象：id、account（应征的人）、work（应征的作品，看不到了为 null）、status、given（采纳时应征的人拿到多少，没采纳为 null）、reject_reason（拒的理由：发起人写的；自动拒的是 another_accepted 别的应征被采纳 / work_hidden 作品下架或删除 / cancelled 站务取消了求档）、auto_accept_at（待处理的到这个时间自动采纳，其他为 null）、created_at、decided_at。一个求档收到的应征列在 GET /bounties/{id} 的 answers 里（撤回的不列），发起人从这里拿 answer_id。

• 应征不了 76018，data.reason：own（你在这个求档上挂了积分）/ not_yours（作品不是你投的）/ content_type（类型不对）/ before（作品在求档发起以前就发布了）/ answered（这部作品应征过这个求档，或者你还有一个待处理的应征）。作品不存在、看不到、没发布 10004。

• 求档不是 open、应征不是 pending 的 10005；不是发起人不能采纳、拒，不是应征的人不能撤回 10003；reason 空的、太长 10001。

• 应征每人默认每小时 30 次（失败的也算）。

• 应征的作品下架或删除后，待处理的应征自动拒掉；已经采纳的不收回。

9.3 我的求档

GET /me/bounties 是页码分页：page（从 1 开始）、page_size（默认 20，最大 100），返回 items（求档对象）和 pagination（page、page_size、total、total_capped；total 最多算到 10000，超过时 total_capped 为 true）。参数 role：posted 我发起的（默认）/ staked 我挂了积分的（含我发起的）/ answered 我应征过的；status：open、fulfilled、expired、cancelled，可以用逗号分隔几个，all 是全部（默认 all）。

10. 分发节点（用途「分发节点」）

你可以在自己的机器上运行站点的节点程序 xm-edge，替站点分发文件，按每天的工作量拿积分。

申请条件：站点开放了这项功能、验证过邮箱（默认要求）、注册满一定天数（默认 7 天）、你的节点（含待审批的）不到 max_nodes 台。GET /me/edge 的 eligible 是现在能不能申请，不能时 reasons 列出原因：off（没开放）/ email（没验证邮箱）/ too_new（注册天数不够）/ too_many（节点到了上限）。

1. 用 GET /me/edge 确认 eligible 为 true，阅读条款：条款是站点页面，terms_page 是它的 slug（GET /pages/{slug}）。

2. 同意条款以后调 POST /me/edge/enrollments 要申请码。

3. 安装：在 Linux（systemd）机器上用 root 运行返回的 command（一条现成的命令，带着申请码）。安装脚本会一项项问对外端口、对外地址（自动检测）、代理、缓存、限速、流量、测速、自动更新，再登记、建服务、启动；装好以后用 sudo xm-edge-ctl status（状态）、update（更新）、config（改配置）、logs（日志）、auto-update on|off、uninstall 管理，默认每天自动更新。不用脚本的照 install 手动装：按平台下载节点程序并核对 sha256，把 config 存成 edge.yaml，改掉注释里标着「要改」的几项（对外端口、缓存目录、对外地址等），然后运行 xm-edge enroll -config edge.yaml -code <申请码> -agree <consent_version> 登记。

4. 登记的节点出现在 GET /me/edge 的 nodes 里，status 是 pending，等站点审核；批准以后变成 active，开始分发。审核结果会发站内通知。

5. 不用了的节点：先在那台机器上停掉节点程序，离线以后用 DELETE /me/edge/nodes/{uid} 删掉（见 10.1），不再占名额。

10.1 我的节点和申请码

GET /me/edge 返回：

• enabled（站点开没开这项功能）、eligible、reasons、terms_page、max_nodes。

• reward：奖励规则 per_hour、per_gb、daily_cap（见 10.2）。

• rewards：yesterday、last_30_days，昨天和最近 30 天拿到的分。

• install：安装信息，没有为 null：main_url（节点连接的地址，已经填进配置模板）、downloads[]（各平台的节点程序：os、arch、version、size、sha256、url）、config（配置模板，YAML 文本）、script_url（安装脚本的地址）、script_command（不带申请码的安装命令，装好以后重装、看管理用法时用；后两项没有为 null）。

• nodes：你的节点，按登记先后；暂时取不到时是空数组，另带 nodes_unavailable: true。每台节点：

  • uid 节点号；status：pending 待审批 / active 正常 / paused 暂停 / disabled 停用；online、last_seen_at、online_since（这一段连续在线从什么时候开始）。

  • assignable：此刻能不能被派活，为 false 时原因在 health_reasons；health_score（0 ~ 100，低了不派活）、quality（质量分 0 ~ 10000）。

  • health_reasons：扣分、少派或不派活的原因码，例如 offline 掉线、cert 证书没用上或过期、probe_down 抽查不合格停派、too_slow、download_slow 测速的上传、下载不够、limit_low 自己设的限速低于要求、outdated 节点程序太旧、month_full 这一期流量用到了自己设的上限的 95%、slow_serving / serving_errors 实际分发时慢的、出错的太多（只扣分）；不认识的码请原样显示。

  • continents：这台服务的大洲（AS、EU、NA、SA、OC、AF、AN），按最近一次成功测速定位的国家算，不用、也不能自己设；空数组是不分地区。

  • speedtest_pending：请了重新测速、还没出结果（见下面的 POST /me/edge/nodes/{uid}/speedtest）。

  • 另有 trust、speedtest（最近一次测速；server_id、server_sponsor、server_city、server_country 是测的那个测速点）、cdn_cap_mbps、cdn_cap_source、limits（节点自己设的限额和这一期的用量）、probe（抽查）、proxy、version、base_url、created_at、consented_at。

POST /me/edge/enrollments：请求体 { "agree": true }（同意条款，必须是 true，否则 10001）。返回 code（一次性的申请码，xee_ 开头，expires_at 以前有效，只能用一次）、expires_at、consent_version（现在的条款版本，登记时用）、install（同上）、command（带着申请码和条款版本的安装命令，复制到机器上运行；没有为 null）。每人默认每小时 5 次（失败的也算）。

• 不能申请 76019，data.reason 同 reasons（几个都不满足时给第一个）。

• 分发节点暂未开放 76020（data.reason 是 closed），暂时连不上也是 76020（unavailable）。

DELETE /me/edge/nodes/{uid}：删掉自己的一台节点，返回 { "deleted": true }。离线的（online 为 false）、待审批的能删；在线、已经批准的返回 76021：先在那台机器上停掉节点程序（sudo xm-edge-ctl uninstall，或者 sudo systemctl stop xm-edge），约 2 分钟后离线了再删。删掉以后节点的密钥作废、不再派活、不再占 max_nodes 的名额；以前的工作量照常结算。不是你的、没有这台 10004。

POST /me/edge/nodes/{uid}/speedtest：请自己的一台节点重新测速，返回这台节点（speedtest_pending 为 true）。请求体可以不带（节点自己挑测速点），或者 { "server_id": "56935" } 只测那一个测速点（speedtest.net 的测速点 ID，1 ~ 10 位数字，不对 10001）。30 秒内开始测，一两分钟后出结果：隔一会儿再取 GET /me/edge，speedtest_pending 变回 false、speedtest.at 换成新的时间就是测完了。现在测不了返回 76022，data.reason：recent（10 分钟内刚测过）/ outdated（节点程序太旧，请更新）/ server_unsupported（指定测速点要更新节点程序，不指定照样能测）/ disabled（节点停用了）。不是你的、没有这台 10004。每人默认每小时 10 次（失败的也算）。

me = call("GET", "/me/edge")
if me["eligible"]:
    e = call("POST", "/me/edge/enrollments", {"agree": True})
    print(e["code"], e["expires_at"], e["consent_version"])
    print("在你的机器上运行：", e["command"])
else:
    print("现在不能申请：", me["reasons"])

10.2 奖励和工作量

• 每台节点每天的奖励 = 向下取整（healthy_seconds ÷ 3600 × per_hour + bytes ÷ 10⁹ × per_gb），healthy_seconds 是能派活的秒数，bytes 是计入奖励的分发字节数。

• 一个人一天几台加起来最多 daily_cap 分（0 是不限），超了少给，那天的记录 capped 为 true。

• 一天过完以后才结算（最多晚一天半），每台节点每天只结算一次，记进积分变动（edge，title 是节点号）；不受其他奖励的每日上限限制。

GET /me/edge/rewards：结算过的奖励，新的在前，页码分页（同 GET /me/bounties）。每项：day、node（节点号）、healthy_seconds、bytes、points、capped。

GET /me/edge/usage：最近几天每台节点每天的工作量，包括还没结算的（今天的还在涨）。参数 days：1 ~ 30，默认 7，含今天。返回 items，不分页，新的天在前、同一天按节点号。每项：day、node、online_seconds（在线秒数）、healthy_seconds、bytes、points 和 capped（还没结算时 points 为 null）。暂时连不上 76020（unavailable）。

11. 资料和设置（用途「资料和设置」）

11.1 当前账号

GET /me 返回当前账号。任何用途的令牌都能调，可以用来确认令牌有效、属于哪个账号。

11.2 个人设置

PATCH /me/settings 改个人设置，返回改后的完整 settings。请求体是 JSON Merge Patch（RFC 7396），Content-Type 用 application/merge-patch+json 或 application/json 都可以：

• 只改带了的字段，嵌套的对象可以只带要改的那一项；值为 null 表示恢复默认。

• 数组整个替换：要往 content_filter.hidden_tags 这类列表里加一项，先从 GET /me 取出原来的数组，加上以后整个传回去。

• 不认识的字段（哪一层都算，ui 里面的除外）报 unknown，类型不对、取值不合法报 invalid，都是 10001；data.errors 的键是 JSON 路径，如 player.audio.loop、title_preference[1]。出错时整个请求一项都不改。

subtitle_language："auto" 跟随作品（开作品标明的默认字幕）；"" 不开字幕；其他值是偏好的语言（BCP 47，如 zh-Hans、ja），作品有这种语言的字幕就开它，没有再开默认字幕。PATCH 里的 null 是恢复成 "auto"，不是关字幕。

call("PATCH", "/me/settings", {"theme": "light", "player": {"speed": 1.5}, "notifications": {"work_update": False}})

11.3 显示名、头像、年龄确认

换头像不用先另外上传图片：直接用 multipart/form-data 把图片放在字段 file 里发给 PUT /me/avatar。支持 JPEG、PNG、WebP、GIF，默认不超过 2 MB（以站点设置为准）；图片会被裁成正方形，旧头像随之删除。

img = open("avatar.png", "rb").read()
me = call("PUT", "/me/avatar", files={"file": ("avatar.png", img, "image/png")})
print(me["avatar"])

12. 只能在网站上做的事、其他公开接口

12.1 只能在网站上做的

下面这些和账号安全有关，只认网站上登录的会话：令牌调用它们返回 10003（data.reason 是 session_only），令牌也不会因此获得权限。请在网站上操作。

• 注册、登录、退出、找回密码、验证邮箱（/auth/… 下的接口）。

• 修改密码 POST /me/password、修改邮箱 POST /me/email、重发验证邮件 POST /me/email/resend。

• 管理接口令牌：GET /me/api-tokens、POST /me/api-tokens、DELETE /me/api-tokens/{id}。

• 订阅链接的凭证：GET /me/feed-token、POST /me/feed-token、DELETE /me/feed-token（拿到订阅链接以后怎么用，见第 5.3 节）。

12.2 版权投诉

POST /copyright-claims：权利人或代理人投诉站内作品侵权。不需要令牌（带了也照常受理，并记下是谁提交的）。

返回 { "id": 5, "created_at": "…" }，id 是受理编号。处理结果由站务通过邮件或电话联系，接口不提供查询。按 IP 限制频率（默认每小时 5 次，失败的也计数）。

12.3 App 用的分流结果

GET /app/dispatch?platform=android：不需要令牌。这是给本站 App 用的：返回一份签过名的分流结果，里面有接口的几个可用地址（按你所在的国家排好）、网站地址和 App 的最新版本，App 照它挑地址连接。脚本一般用不到；要用的话，payload 是一段 JSON 的 base64url 编码（不带 =），解开以后：

站点还没配好时返回 78001。按 IP 限制频率（默认每分钟 60 次）。

12.4 App 的各版本

GET /app/releases：不需要令牌，给本站 App 的更新日志和网站的 App 下载页用。

?platform=android 只要一个平台，不带给全部 → { "icon", "items": [ { "platform", "latest", "min", "versions": [ { "version", "url", "size_bytes", "notes", "released_at", "required", "packages" } ] } ], "screenshots": [ { "image", "device", "caption" } ] }。icon 是 App 的图标（图片，不分平台；没设为 null）。versions 新的在前，notes 是 Markdown 原文（按请求语言），required 为 true 的版本以下必须更新，packages 同上一节（没有为空数组）。screenshots 是 App 的截图（device 是 phone / tablet / tv，caption 是按请求语言的一句说明、没有为 null）。platform 写法不对返回 10001。