面向开发者的公开接口

免费随机二次元图片，以及基于授权离线快照的 IP 归属地与 ICP 备案查询。

随机图片

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 缓存。重复使用同一图片地址不会再产生流量。

付费数据查询

数据接口需要 API Key、有效套餐和对应权限。密钥只通过 Authorization: Bearer 传递，不支持放在 URL 中。test Key 使用独立的较低配额且永不计费，适合接入验证。

接口	权限	单位	说明
`GET /v1/ip/lookup?ip=...`	`ip:read`	1	查询 IPv4 或 IPv6 命中的最具体 CIDR 网段
`GET /v1/icp/lookup?domain=...`	`icp:read`	1	域名经 IDNA 规范化后，返回最长匹配的备案根域

curl -H 'Authorization: Bearer sk_test_...' \
  'https://open.starhui.cc/v1/ip/lookup?ip=203.0.113.8'

curl -H 'Authorization: Bearer sk_test_...' \
  'https://open.starhui.cc/v1/icp/lookup?domain=foo.example.com'

成功响应包含 dataset：数据类型、版本、来源、授权说明、导入时间、过期时间和记录数。平台只查询运营已经取得授权并导入 PostgreSQL 的 active 快照，不在请求时转发第三方 API。快照过期后接口返回 503，不会把陈旧数据继续作为当前事实。

{
  "ip": "203.0.113.8",
  "network": "203.0.113.0/24",
  "country_code": "CN",
  "country_name": "中国",
  "region": "浙江",
  "city": "宁波",
  "dataset": {
    "kind": "ip",
    "version": "供应商版本",
    "source": "已登记的数据来源",
    "license": "已登记的授权说明",
    "imported_at": "2026-08-24T00:00:00Z",
    "expires_at": "2026-09-24T00:00:00Z",
    "record_count": 100000
  }
}

只有 2xx 查询消耗日/月单位。参数错误、未命中和数据集不可用不会消耗单位；它们仍计入每分钟请求数并保留非成功计量明细。超出套餐额度返回 429 和重置时间。

限流

匿名调用按 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 响应头中。

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