ai-api 图片转发网关 · 接口文档

对外一个极简接口做图片生成；内部转发到 highwayapi / otuapi，单入口 + 自动故障转移，出图落地成本站稳定 URL。

概览

鉴权

除只读/页面类端点外，写操作需在请求头带网关 key：

复制Authorization: Bearer <你的网关KEY>

key 错误或缺失 → 401。新增/吊销 key 由服务端 .env 管理（一行一个，行首加 # 即吊销）。

生成图片

POST/v1/images

请求字段

ratio 取值： auto1:13:44:32:33:29:1616:91:22:11:33:19:2121:9

示例 · 文生图（curl）

复制curl -X POST https://ai-api.dahe2016.com/v1/images \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"小红书封面 香港保险避坑 扁平插画 红黄撞色大标题","ratio":"3:4","n":2}'

示例 · 图生图（curl）

复制curl -X POST https://ai-api.dahe2016.com/v1/images \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"i2i","image":"https://example.com/ref.jpg","prompt":"改成夜景霓虹风格","ratio":"3:4"}'

没有在线 URL（只有本地图）时，把 image 换成图片的 base64 即可，例如 Python：image = base64.b64encode(open("a.png","rb").read()).decode() 再放进 body。

复制import httpx
r = httpx.post(
  "https://ai-api.dahe2016.com/v1/images",
  headers={"Authorization": "Bearer "+KEY},
  json={"prompt":"...", "ratio":"3:4", "n":1},
  timeout=320)
for it in r.json()["data"]:
    print(it["url"])

复制const r = await fetch("/v1/images", {
  method:"POST",
  headers:{ "Content-Type":"application/json",
            "Authorization":"Bearer "+KEY },
  body: JSON.stringify({prompt:"...", ratio:"3:4", n:1})
});
const d = await r.json();
console.log(d.data.map(x=>x.url));

响应

响应体永远是 JSON。HTTP 状态：200=至少 1 张成功（可能部分失败，看 errors）｜502=全部失败｜400=参数错误｜401=key 无效。

下面这个例子请求 2 张（n=2），成功 1 张、失败 1 张——同时展示 data[] 和 errors[] 两种结构：

复制{
  "created": 1782286822,
  "ratio": "3:4", "mode": "t2i", "size": "1k",
  "requested": 2, "succeeded": 1, "failed": 1,
  "data": [
    {
      "url": "https://ai-api.dahe2016.com/img/5a8e1395abcd.png",
      "provider": "otuapi",
      "upstream_size": "auto",
      "width": 1086, "height": 1448,
      "bytes": 2000215, "elapsed_ms": 51000
    }
  ],
  "errors": [
    {
      "index": 1,
      "tried": [
        { "channel": "otuapi",     "error": "HTTP 403: insufficient_user_quota" },
        { "channel": "highwayapi", "error": "failed after 4 retries: HTTP 504" }
      ],
      "elapsed_ms": 62000
    }
  ]
}

顶层字段

data[] — 每张成功图

errors[] — 每个失败项

图片托管

GET/img/{filename} — 网关把上游图下载落地后，以本站稳定 URL 提供（免鉴权，可直接 <img> 引用）。

健康检查

GET/healthz

复制{ "ok":true, "primary":"highwayapi", "order":["highwayapi","otuapi"],
  "failover":true, "available":["highwayapi","otuapi"],
  "gateway_keys":1, "auth":"enabled", "otu_key":true, "hw_key":true }

请求统计

按网关 key（标签）统计请求次数 + 出图成功/失败数 + 各渠道分担。统计随每次 /v1/images 累加，持久化、重启不丢。可视化见 /admin。

GET/v1/stats — 读取统计（需 KEY）

复制{
  "since": 1782200000,
  "total": { "requests": 128, "images_ok": 240, "images_failed": 3 },
  "by_key": {
    "default":  { "requests": 100, "images_ok": 190, "images_failed": 2, "last_ts": 1782284733 },
    "partner1": { "requests": 28,  "images_ok": 50,  "images_failed": 1, "last_ts": 1782280000 }
  },
  "by_channel": { "highwayapi": 230, "otuapi": 10 }
}

POST/v1/stats/reset — 清零（需 KEY，用于新计费周期）

比例 ↔ 后端 映射参考

调用方只传 ratio，网关按下表翻译。highwayapi 走精确 size，otuapi 走提示词描述。

注：highwayapi 某档无对应精确尺寸时回退到 1k 表；再没有则用 auto + 提示词兜底。1:2 / 2:1 / 1:3 / 3:1 也支持（1k）。

错误与坑

• 延迟：单张约 20–90s（同步出图 = 整张图生成时间）；客户端超时建议 ≥300s。
• 并发：对外可并发；网关对上游始终 n=1 多次请求（传 N 会掉质量）。
• 冷启动 504：highwayapi 偶发，网关已自动重试 3 次；仍失败才转备用。
• 图别长期引用上游链：用网关返回的 url（本站落地，永久有效）。

在线试一试

复制