Your first request

The examples below cover three common requests. Set API_BASE and MODELFOLD_API_KEY before running them.

export API_BASE="https://modelfold.ai/v1"   # Production API base URL
export MODELFOLD_API_KEY="mf-..."

Image generation

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

Field	Required	Description
model	Yes	Image model ID; see Image models
prompt	Yes	Prompt string, up to 2,000 characters
image_url	No	Reference image URL for image-to-image or editing models
resolution	No	Resolution tier

Response:

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

Video generation

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

Video requests use the same fields as image requests, with duration (seconds) and resolution for video settings. See Video models for available models.

Chat completions

The chat API is compatible with OpenAI's chat/completions format:

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

Field	Required	Description
model	Yes	Chat model ID; see Chat models
messages	Yes	Non-empty array of objects such as { "role": "user", "content": "..." }
max_tokens	No	Defaults to 1024; used to estimate the credit reservation
temperature	No	Sampling temperature

Response:

{
  "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 }
}

Chat is billed by token usage. usage.credits is the final charge after settlement, which may differ from the initial reservation.

Error handling

Errors use a consistent response structure:

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

HTTP	error.type	Meaning and action
400	unsupported_model	Unknown model or endpoint mismatch, such as a chat model sent to the image endpoint
400	invalid_prompt	Missing prompt or more than 2,000 characters
400	invalid_messages	Missing messages or an empty array
401	unauthorized	Invalid or revoked key
402	insufficient_credits	Insufficient balance; no provider call or charge was made
429	rate_limited	Rate limit exceeded
502	upstream_failed	Provider call failed; credits have been refunded automatically
503	upstream_unavailable	The provider for this model has not been configured

Next steps

• Gateway reference: complete endpoint parameters and responses
• Model catalog: choose a model