API 网关（/v1）

网关是调用模型的唯一入口，鉴权统一使用 API Key：

Authorization: Bearer mf-...

所有端点都接受 Content-Type: application/json，请求体上限 1 MB。

GET /v1/models

列出当前可用的模型。

curl "$API_BASE/models" -H "Authorization: Bearer $MODELFOLD_API_KEY"

{ "object": "list", "data": [ { "id": "nano-banana-2", "modality": "image", "credits": 8 } ] }

POST /v1/images/generations

图像生成与图像编辑。

参数	类型	必填	说明
model	string	是	图像类模型 ID
prompt	string	是	提示词，最长 2000 字
image_url	string	否	参考图 / 待编辑图片地址
resolution	string	否	分辨率档位，例如 1K

curl -X POST "$API_BASE/images/generations" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","prompt":"a paper boat in the rain","resolution":"1K"}'

响应：

{
  "ok": true,
  "created": 1792134000,
  "data": [{ "url": "https://.../result.png" }],
  "usage": { "credits": 8, "balance": 992, "latencyMs": 4310 }
}

POST /v1/videos/generations

视频生成，参数与图像端点一致，另支持时长与分辨率。

参数	类型	必填	说明
model	string	是	视频类模型 ID
prompt	string	是	提示词，最长 2000 字
image_url	string	否	首帧图（图生视频）地址
duration	number	否	时长（秒）
resolution	string	否	分辨率档位，例如 720p

curl -X POST "$API_BASE/videos/generations" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-2.6/text-to-video","prompt":"a paper boat in the rain","duration":5,"resolution":"720p"}'

返回结构与图像端点相同，data[0].url 指向生成的视频。

POST /v1/chat/completions

对话补全，请求与响应结构与 OpenAI 的 chat/completions 兼容。

参数	类型	必填	说明
model	string	是	对话类模型 ID
messages	array	是	非空数组，元素为 { role, content }
max_tokens	number	否	默认 1024
temperature	number	否	采样温度

curl -X POST "$API_BASE/chat/completions" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"你好"}],"max_tokens":512}'

响应：

{
  "ok": true,
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1792134000,
  "model": "claude-sonnet-4-6",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }],
  "usage": { "input_tokens": 18, "output_tokens": 96, "credits": 1, "balance": 991 }
}

计费与保护

网关对每个请求执行同样的流程：

1. 先查余额：不足直接返回 402，不消耗上游额度、也不记账。
2. 扣费：媒体类按模型固定积分扣；对话类按预估 token 预扣。
3. 调用上游。
4. 结算：对话类按上游返回的真实用量多退少补，每一笔都写流水。
5. 失败退款：上游报错时自动原路退还本次积分，并返回 502。
6. 留痕：无论成功与否都写一条调用记录，可在控制台的调用记录中查看。

积分与上游用量的关系

媒体类模型的积分是按上游成本加价得到的固定值，每个模型页都会列出它的上游成本与计价单位；对话类模型在模型页列出输入 / 输出每百万 token 的积分单价。具体口径见 定价。

错误

HTTP	error.type	说明
400	unsupported_model	模型不存在或与端点不匹配
400	invalid_prompt	prompt 缺失或超过 2000 字
400	invalid_messages	messages 缺失或为空
401	unauthorized	Key 无效或已吊销
402	insufficient_credits	余额不足
429	rate_limited	超过每分钟 60 次
502	upstream_failed	上游失败，已退款
503	upstream_unavailable	该模型的上游未配置