02 — 鉴权

一个项目一个令牌

所有 /v1/* 都要 Authorization: Bearer <令牌>。 /health 不要（给监控用）。

分开发令牌不是为了好看：N 个项目共用一份供应商额度， 不按项目记账就没法管谁把钱花光了 —— 这是第一天就会遇到的问题。 每个令牌能单独吊销、单独记账（GET /v1/usage）。

# 看自己项目最近 24 小时花了多少
curl -H "Authorization: Bearer $AICAP_TOKEN" \
  https://ai.nofuns.xyz/v1/usage?hours=24

返回里有一列 wasted_but_charged —— 图出了、钱收了、我们用不上 的次数。那是最该被看见的数字，藏起来的话这类浪费永远查不出来。

04 — 视频

文生视频 · 图生视频

视频一律异步 —— 拿 job_id 去轮询。跑 2~10 分钟， 同步等必然被网关掐断，那样你连轮询都没得轮。

curl -X POST https://ai.nofuns.xyz/v1/image2video \
  -H "Authorization: Bearer $AICAP_TOKEN" \
  -F "prompt=角色缓慢转头，眨眼，镜头锁死不动" \
  -F "image=@cat.png" \
  -F "last_image=@cat.png" \
  -F "duration=5"

# → {"job_id":"j_xxx","status":"pending"}  然后轮询 /v1/jobs/j_xxx

06 — 三维

文生 3D · 图生 3D

两家供应商：Meshy（默认）和 Tripo。异步。

curl -X POST https://ai.nofuns.xyz/v1/image2model \
  -H "Authorization: Bearer $AICAP_TOKEN" \
  -F "image=@front.png" -F "image=@left.png" \
  -F "provider=meshy" -F "quality=standard" \
  -F "formats=glb,fbx" -F "quad=true" -F "hi_poly=true"

08 — 客户端

拷走就能用

clients/aicap.py 和 clients/aicap.ts，零依赖， 单文件。轮询、下载、错误处理都封好了。

from aicap import AiCap, AiCapError

ai = AiCap("https://ai.nofuns.xyz", "tok_xxx")

# 图片：一步到位
png  = ai.text2image("扁平卡通的橘猫", quality="fast")[0]
png2 = ai.image2image([("ref.png", png)], "改成绿色")[0]

# 视频 / 3D：会一直等（几分钟），别放在请求处理里同步调
mp4   = ai.image2video(png, "缓慢转头", onProgress=print)
desc  = ai.video2text(mp4, "镜头怎么动的？")
files = ai.image2model([("front.png", png)], provider="meshy")
open("out.glb", "wb").write(files["glb.glb"])

# 要非阻塞就用 submit_* 拿 job_id，自己轮询
job = ai.submit_image2video(png, "缓慢转头")
# … 过一会儿 …
done = ai.wait(job)

import { AiCap } from "./aicap";

const ai = new AiCap("https://ai.nofuns.xyz", process.env.AICAP_TOKEN!);

const [png] = await ai.text2image("扁平卡通的橘猫", { quality: "fast" });
const mp4   = await ai.image2video(png, "缓慢转头");
const desc  = await ai.video2text(mp4, "镜头怎么动的？");
const files = await ai.image2model(
  [{ name: "front.png", data: png }], { provider: "meshy" });

10 — 勘误

踩过的坑

这些都写成了数据，由路由层自动过滤，不靠人记。 列在这里是让你知道服务替你挡掉了什么 —— 以及为什么别绕过它。

1. 一个总是快速失败的候选，比没有候选更糟。它不但不顶用，还要吃掉一次重试和一次退避。修掉一个这样的候选之后，一趟作业从 11.0 分钟降到 3.4 分钟。
2. 链必须按端点分。gpt-image-2-low 在 /images/edits 上 8/8 全 400（它不支持这个端点），但在 /images/generations 上是最快最便宜的那个。用一个端点的观测推另一个端点的结论，栽过四次。
3. 能力不能靠猜。要透明底时 low 5/5 返回不透明图，每次 1.7 秒就返回 —— 那速度根本不是在出图，但上游照样收钱。另一个模型更狠：直接把棋盘格画进像素里当假透明。
4. 尺寸约束不能一刀切。某个模型要 ≥2048，拿 1024 发它 44 次调用 44 次 400，每张白花 7.4 秒 —— 而且当年被误判成「它不支持透明底」，一个尺寸问题被记成了能力问题。
5. 「同步端点」也可能返回任务号。gpt-image-2-low 走 /images/generations 回的不是图，是 {"id":"…","status":"pending"}。不轮询的话它每次都被判成失败、每次都掉回贵的那个 —— 配了等于没配。
6. 信封不是内容。Tripo 的响应外层 status:"success" 是接口调用成功，内层 data.status 才是任务状态。读错的话任务跑到 5% 就被当成完成，然后报「成功了但没有产物」。
7. 两步的事别只做一步。Meshy 文生 3D 是 preview 出几何 → refine 上贴图，只发第一步交付的是个白模，而调用方要点开才会发现。
8. 限流按账号算，不按 key 算。12 并发全压 1 个 key 和均摊到 3 个 key 都是 12/12、零 429。⇒ 加 key 不加容量，加账号才加。
9. 并发提高反而更慢。池 8→20 的实测：11.0 分钟 → 13.1 分钟。负反馈：错误率↑ → 退避重试 → 有效吞吐↓。顶着天花板跑，抖动一下就全挂。
10. 「能连上」不等于「能用」。栽过的每一次，curl 都是 200。所以冒烟检查的不是状态码，是产物本身 —— 图能不能解码、GLB 的魔数对不对、描述是不是空的。