星绘开放 API

面向开发者的公开接口。当前提供免费随机二次元图片，后续将增加数据类查询接口。

随机图片

GET /v1/images/random

从审核通过且分级为 safe 的图库中随机返回一张。默认以 302 跳转到图片地址，可直接用在 <img> 标签里。

<img src="https://open.starhui.cc/v1/images/random">

参数

参数	取值	默认	说明
`format`	`redirect`、`json`	`redirect`	返回跳转还是元数据
`orientation`	`landscape`、`portrait`、`square`、`any`	`any`	图片方向
`category`	分类 slug	全部	未知分类会返回 400 并列出可用值

未知参数会返回 400 而不是被忽略。参数拼错时你会立刻知道，而不是拿到一个看起来正常但并非你想要的结果。

JSON 模式

GET /v1/images/random?format=json

{
  "id": "img_01K3W8ZC4M9QX6PN2VYAH7T5RD",
  "url": "https://open.starhui.cc/i/8f3a....webp",
  "width": 1280,
  "height": 1920,
  "orientation": "portrait",
  "format": "webp",
  "bytes": 118420,
  "tags": ["outdoor"],
  "rating": "safe",
  "source": {
    "type": "collected",
    "author": null,
    "author_url": null,
    "origin_url": null
  }
}

source 描述图片来源。可识别作者时会返回署名信息。

缓存

随机接口本身带 Cache-Control: no-store——若被缓存住，它就不再随机。

而图片地址是内容寻址的，内容永不改变，因此带一年期 immutable 缓存。重复使用同一图片地址不会再产生流量。

限流

匿名调用按 IP 限流。响应同时携带两种格式的限流头：

RateLimit-Policy: "anon";q=20;w=60
RateLimit: "anon";q=20;r=18;t=42
RateLimit-Limit: 20
RateLimit-Remaining: 18
RateLimit-Reset: 42

前两个是 IETF 草案形式，后三个是被广泛部署的既有惯例，多数现成客户端库解析的是后者。两者同时发送，你用哪个都行。

触发限流返回 429 并带 Retry-After。图片下载另有单 IP 并发连接数限制。

错误

全部错误使用 RFC 9457 Problem Details，媒体类型为 application/problem+json：

{
  "type": "https://open.starhui.cc/docs/errors/invalid_parameter",
  "title": "参数取值不合法",
  "status": 400,
  "code": "invalid_parameter",
  "detail": "orientation 只允许 landscape、portrait、square、any",
  "instance": "/v1/images/random",
  "request_id": "req_01K3W8ZC4M9QX6PN2VYAH7T5RD"
}

程序判断请用 code，它是稳定的，只追加不修改。detail 面向人类阅读，措辞可能调整。反馈问题时请附上 request_id，它同时出现在 X-Request-Id 响应头中。

全部错误码见错误码列表。