API 网关（/v1）
网关提供同步模型调用，媒体模型另支持 异步任务，鉴权统一使用 API Key：
Authorization: Bearer mf-...所有端点都接受 Content-Type: application/json，请求体上限 100 MB。
GET /v1/models
列出当前可用的模型。
curl "$API_BASE/models" -H "Authorization: Bearer $MODELFOLD_API_KEY"{ "object": "list", "data": [
{ "id": "google/imagen4-fast", "modality": "image", "credits": 6 },
{ "id": "kling/v3-turbo-text-to-video", "modality": "video", "credits": 81,
"pricing": { "unit": "second", "credits_per_second": 27, "min_seconds": 3, "start_params": { "resolution": "720p" } } }
] }credits 是起价。按秒计费的视频模型带 pricing：credits = 最低档（start_params）× 最短时长（min_seconds）的实扣，credits_per_second 是该档每秒价格；更高分辨率、开音频、更长时长按实际参数计价，实扣以返回的 usage.credits 为准。
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":"seedream/5-pro-text-to-image","prompt":"a paper boat in the rain","aspect_ratio":"1:1","quality":"basic"}'响应：
{
"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/v3-turbo-text-to-video","prompt":"a paper boat in the rain","duration":"3","resolution":"720p"}'返回结构与图像端点相同，data[0].url 指向生成的视频。
模型专有参数
上表仅列通用字段。不同模型还可能必填 quality、aspect_ratio、image_urls、video_url 或 audio_url 等参数，须按模型完整参数页填写。参数可以放在请求体顶层，也可以放在 params 对象中（params 优先）；不要套 input。网关不转发回调地址和出图张数参数，每次按模型默认数量生成。
请求等待生成完成后返回 data[].url，长视频建议客户端超时至少设置为 20 分钟；支持的媒体模型另可使用 异步任务、轮询与回调。
POST /v1/audio/generations
语音生成使用此端点。可用 prompt 传入待朗读文本，并按模型支持情况传 voice；对应模型也支持原生 text/voice 或 speakers/dialogue_turns 结构。待朗读文本总长必须非空且不超过 5000 字；各模型必填字段见模型参数页。响应结构与图像生成相同。
POST /v1/chat/completions
此端点仅返回完整 JSON，不转发 stream、tools 等上游专有参数；流式和原生智能体协议接入见 AI Agent。
对话补全，请求与响应结构与 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 }
}计费与保护
网关对每个请求执行同样的流程：
- 先查余额：不足直接返回
402，不消耗上游额度、也不记账。 - 扣费：媒体类按模型固定积分扣；对话类按预估 token 预扣。
- 调用上游。
- 结算：对话类按上游返回的真实用量多退少补，每一笔都写流水。
- 失败退款：上游报错时自动原路退还本次积分，并返回
502。 - 留痕：无论成功与否都写一条调用记录，可在控制台的调用记录中查看。
积分与上游用量的关系
媒体类模型的积分是按上游成本加价得到的固定值，每个模型页都会列出它的上游成本与计价单位；对话类模型在模型页列出输入 / 输出每百万 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 | 该模型的上游未配置 |