随机动漫壁纸 API 的调用侧契约：随机性、缓存与失败边界怎么定

随机动漫壁纸接口看起来只是“每次返回一张图”，但对调用方真正有意义的是契约：随机性怎么定义、尺寸与格式怎么约定、能不能缓存、失败时返回什么。在缺少接口正文与官方文档可核对的前提下，本文只讨论调用侧能自行确定的部分；具体路径、参数名、配额与返回结构以官方文档为准，本文不代填。

先把“随机”写成可验证的条件#

“随机”不是一种实现，而是一组需要明示的条件。接入前建议逐项确认：

• 取值范围：全站图库、指定标签，还是指定横竖方向；能否排除已看过的图。
• 重复策略：是否保证连续 N 次不重复，去重窗口多大。
• 返回形态：直接 302 跳到图片地址，还是返回 JSON 带 URL 字段。两者对客户端缓存与错误处理的影响完全不同。
• 尺寸与体积：是否有分辨率上限、是否支持按宽度裁剪。
• 内容分级与授权：是否可能返回 NSFW 内容；图片的署名、商用与热链政策怎么规定。

这些条件决定了展示层与缓存层的写法，先问清楚再写代码，比事后改回调参数便宜得多。

缓存：随机接口的天然矛盾#

随机端点如果被 CDN 或浏览器缓存，用户会反复看到同一张图；如果完全不缓存，每次请求都要回源，配额消耗很快。一种常见分工是：随机端点返回不可缓存的响应头，而图片本体地址稳定、交给长缓存，用图片 ID 或内容哈希作为缓存键。

这只是设计建议，是否如此取决于服务端实际返回的响应头。接入时应先抓一次响应，确认 Cache-Control、ETag 与跳转行为，再决定客户端缓存策略，不要凭经验假设。

一个最小的调用骨架（未执行）#

下面代码未实际运行，仅演示结构：超时、鉴权、429 与异常分支放在哪一层。路径、鉴权头与 JSON 字段名均为占位，必须按官方文档替换。

import os
import requests

# 未执行的示例：地址与鉴权方式均为占位，待按官方文档替换
BASE = os.environ.get("IMAGE_API_BASE", "https://api.example.com")
KEY = os.environ.get("IMAGE_API_KEY", "YOUR_KEY")

def fetch_random(tag="anime", timeout=5.0):
    resp = requests.get(
        f"{BASE}/random",                     # 占位路径
        params={"tag": tag},
        headers={"Authorization": f"Bearer {KEY}"},  # 占位鉴权头
        timeout=timeout,
    )
    if resp.status_code == 429:
        return None, "rate_limited"           # 读 Retry-After 后再退避
    resp.raise_for_status()
    return resp.json().get("url"), None        # 字段名待核对

把地址、密钥、路径都放进环境变量或配置，是拿不到文档时唯一稳妥的做法：文档到位后只改配置，不动调用逻辑。

失败边界：429 和 5xx 不是一回事#

• 429 表示速率或配额受限。应读取响应中的 Retry-After 做退避，并在客户端缓存上一张成功的图作为兜底，避免页面空白。
• 超时与 5xx 可重试，但随机接口每次重试都会再消耗一次配额，重试次数要保守。
• 图片 404 / 403 属于资源失效，重新取一次即可；盲目循环重试只会放大配额消耗。

展示与合规边界#

动漫壁纸多为第三方作品，能否商用、是否需要署名、是否允许热链，都要按图源说明核对；接口能取到图，不等于可以把它当作可长期分发的资源。内容分级也应有客户端开关，而不是依赖服务端默认行为。

在拿到接口正文之前，能确定的就是这些边界：随机语义要写清、缓存要按实际响应头决定、错误要分类处理。至于端点路径、参数、配额与返回字段，待核实。