ai-api 多模型网关 · 接口文档

图片生成（gpt-image-2 / banana）+ 文本对话 13 模型（claude-opus-5 / claude-opus-4-8 / claude-sonnet-4-6 / claude-sonnet-5 / claude-fable-5 / gpt-5.4 / gpt-5.5 / gpt-5.6-luna / gpt-5.6-sol / gpt-5.6-terra / kimi-k3 / deepseek-v4-flash / deepseek-v4-pro，对外都兼容 OpenAI 接口）。单入口、多渠道主备 + 自动故障转移，对调用方透明。

概览

鉴权

除只读/页面类端点外，写操作需在请求头带网关 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": "otuapi", "error": "HTTP 403: insufficient_user_quota" }
      ],
      "elapsed_ms": 62000
    }
  ]
}

顶层字段

data[] — 每张成功图

errors[] — 每个失败项

文本 / 对话 · 13 个模型

13 个文本模型：claude 系与 gpt 系多渠道主备 + 自动故障转移；kimi-k3/deepseek-v4-flash/deepseek-v4-pro 直连原厂单渠道无备用。对外都兼容 OpenAI 接口 /v1/chat/completions；claude 系另外支持 Anthropic 原生 /v1/messages。渠道切换对调用方透明。

鉴权：与图片同一套网关 key，Authorization: Bearer <KEY> 或 x-api-key: <KEY>（Anthropic SDK 习惯）都认。

示例 · OpenAI 兼容 /v1/chat/completions（13 模型通用）

复制curl -X POST https://ai-api.dahe2016.com/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.5","stream":true,
       "messages":[{"role":"user","content":"从1数到20"}]}'

OpenAI Python SDK：OpenAI(base_url="https://ai-api.dahe2016.com/v1", api_key=KEY)，model 填 13 个 id 任一（如 claude-opus-4-8 / gpt-5.4 / kimi-k3 / deepseek-v4-pro）。

示例 · Anthropic 原生 /v1/messages（仅 claude 系）

复制curl -X POST https://ai-api.dahe2016.com/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,
       "messages":[{"role":"user","content":"你好"}]}'

Anthropic 官方 Python SDK：Anthropic(base_url="https://ai-api.dahe2016.com", api_key=KEY)，model 填 claude-opus-4-8 或 claude-sonnet-4-6，tool use 照常。

接 Open WebUI

Open WebUI 原生只认 OpenAI 兼容协议，所以走 /v1/chat/completions——claude 系网关后端转成 Anthropic 原生，其余纯透传，13 个模型都能用。

图片托管

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

健康检查

GET/healthz — 免鉴权，只报活（拿来做探活/监控即可）。

复制{ "ok": true }

请求统计

按网关 key、并在每个 key 下再按模型统计请求次数 + 成功/失败（一个 key 可能调多个模型）。统计随每次 /v1/images 累加，持久化、重启不丢。可视化见 /admin。

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

复制{
  "since": 1782200000,
  "total": { "requests": 128, "images_ok": 240, "images_failed": 3 },
  "by_key": {
    "pic-banana": {
      "requests": 50, "images_ok": 95, "images_failed": 2, "last_ts": 1782284733,
      "models": {                                    // ← 该 key 按模型细分
        "gpt-image-2": { "requests": 30, "ok": 58, "failed": 1 },
        "banana":      { "requests": 20, "ok": 37, "failed": 1 }
      }
    }
  },
  "by_channel": { "hfsyapi": 60, "apiyi": 35, "otuapi": 5 },
  "by_model":   { "gpt-image-2": 58, "banana": 37 }
}

POST/v1/stats/reset — 清零（仅管理员：`x-admin-password` 头；计费周期动作，调用方 KEY 无权）

比例 ↔ 后端 映射参考

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

注：size 是给上游的入参，成品实际分辨率更高（如 3:4 传 768×1024，出图 1086×1448）。hfsyapi 只有 1K 档，2k/4k 入参无效。

错误与坑

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

在线试一试

复制