Gateway reference (/v1)

📝 TODO — this English page is a skeleton. The structure mirrors the Chinese page, which is fully written.

All gateway endpoints authenticate with an API key:

Authorization: Bearer mf-...

GET /v1/models

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

POST /v1/images/generations

Field	Type	Required	Notes
model	string	yes	Image model ID
prompt	string	yes	Up to 2000 characters
image_url	string	no	Reference image for edit models
resolution	string	no	Resolution preset

POST /v1/videos/generations

Same fields as images, plus:

Field	Type	Required	Notes
duration	number	no	Length in seconds
resolution	string	no	e.g. 720p

POST /v1/chat/completions

Field	Type	Required	Notes
model	string	yes	Chat model ID
messages	array	yes	Non-empty array of { role, content }
max_tokens	number	no	Defaults to 1024
temperature	number	no	Sampling temperature

Billing

1. Balance is checked first — 402 before the upstream is called.
2. Media is charged a fixed number of credits; chat is pre-authorized on an estimate.
3. Chat is settled from the real token usage (adjusted up or down).
4. Failures are refunded automatically and reported as 502.
5. Every request is logged, successful or not.

Errors

HTTP	error.type
400	unsupported_model / invalid_prompt / invalid_messages
401	unauthorized
402	insufficient_credits
429	rate_limited
502	upstream_failed (refunded)
503	upstream_unavailable