第一个请求

下面给出三种典型调用的完整示例。把所有请求里的 API_BASE 和 MODELFOLD_API_KEY 换成你自己的值即可直接运行。

export API_BASE="https://ai.modelfold.online/v1"   # 正式域名上线后为 https://ai.modelfold.online/v1
export MODELFOLD_API_KEY="mf-..."

图像生成

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 drifting down a rainy street, cinematic lighting",
    "resolution": "1K"
  }'

字段	必填	说明
model	是	模型 ID，必须是图像类模型，可在 图像生成模型 中查
prompt	是	提示词，字符串，最长 2000 字
image_url	否	图生图 / 编辑类模型参考图地址
resolution	否	分辨率档位

返回：

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

视频生成

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 drifting down a rainy street",
    "duration": 5,
    "resolution": "720p"
  }'

视频类模型的请求字段与图像类一致，另有 duration（秒）与 resolution。可选模型见 视频生成模型。

对话补全

对话接口与 OpenAI 的 chat/completions 兼容：

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
  }'

字段	必填	说明
model	是	必须是对话类模型，见 对话模型
messages	是	非空数组，元素形如 { "role": "user", "content": "..." }
max_tokens	否	默认 1024，用于预估预扣积分
temperature	否	采样温度

返回：

{
  "ok": true,
  "object": "chat.completion",
  "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 }
}

对话按 token 计费，usage.credits 是结算后的真实扣积分，与预估预扣可能不同。

错误处理

所有错误响应的结构一致：

{ "ok": false, "error": { "type": "insufficient_credits", "message": "积分不足：需要 18，当前 5" } }

HTTP	error.type	含义与处理
400	unsupported_model	模型不存在，或与端点不匹配（例如把对话模型发到图像端点）
400	invalid_prompt	prompt 缺失或超过 2000 字
400	invalid_messages	messages 缺失或为空数组
401	unauthorized	Key 无效或已吊销
402	insufficient_credits	余额不足，未调用上游，未扣费
429	rate_limited	触发速率限制
502	upstream_failed	上游调用失败，已自动退款
503	upstream_unavailable	该模型的上游尚未配置

下一步

• API 参考 —— 网关端点的完整参数与响应
• 定价 —— 计费口径与全量价格表
• 模型总览 —— 挑一个模型开始