API Reference

ModelFold exposes two groups of HTTP APIs:

Group	Prefix	Authentication	Purpose
Model gateway	/v1	API key	Call image, video and chat models
Console APIs	/api	Session token (JWT)	Registration, login, profile, API keys, wallet and email

Both groups use the same domain:

https://modelfold.ai          # Current deployment URL
https://modelfold.ai     # Production domain

Model gateway /v1

Method	Path	Description
GET	/v1/models	List available models
POST	/v1/images/generations	Generate or edit images
POST	/v1/videos/generations	Generate videos
POST	/v1/chat/completions	OpenAI-compatible chat completions

See the Gateway reference.

Console APIs /api

Method	Path	Description
POST	/api/auth/register	Register
POST	/api/auth/login	Sign in and receive a JWT
GET	/api/auth/me	Get the signed-in user
POST	/api/auth/logout	Sign out and revoke the current session
GET	/api/account	Account overview
PUT	/api/account/profile	Update display name
POST	/api/account/avatar	Upload avatar
DELETE	/api/account/avatar	Delete avatar
POST	/api/account/password	Change password
GET	/api/account/sessions	List signed-in devices
DELETE	/api/account/sessions/:id	Sign out a specific device
DELETE	/api/account/sessions	Sign out all other devices
GET	/api/keys	List API keys
POST	/api/keys	Create an API key
DELETE	/api/keys/:id	Revoke an API key
GET	/api/wallet	Balance and transactions
POST	/api/wallet/topup	Top up credits
GET	/api/wallet/usage	Usage history
GET	/api/mail/status	Mail transport status
POST	/api/mail/test	Send a test email
POST	/api/email/verify	Verify email
POST	/api/email/resend	Resend verification email
POST	/api/email/forgot	Request password reset
POST	/api/email/reset	Reset password with a token
GET	/api/health	Health check

Lists return a fixed number of recent records: 50 transactions or 100 model requests. Pagination parameters are not currently provided.

Detailed references: Authentication, Account, API Keys, Wallet, Email.

Response format

Success:

{ "ok": true, "...": "各接口自有字段" }

Failure:

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

Some console endpoints return error as a string rather than an object. For example, failed login returns {"ok":false,"error":"invalid_credentials"}. Refer to each endpoint's reference page.

Rate limits

Scope	Limit
/v1 gateway	60 requests per key per minute
API key creation	30 requests per account per minute
Registration / login	30 requests per IP per ten minutes
Password changes	30 requests per account per ten minutes
Top-ups	10 requests per account per minute
Email resend / recovery / reset	10 requests per IP per ten minutes
Test email	5 requests per account per ten minutes

Exceeding a limit returns 429. Responses use the draft-7 RateLimit and RateLimit-Policy headers.

Status codes

HTTP	Meaning
400	Invalid parameters, such as email format, password strength or model/endpoint mismatch
401	Missing or invalid credentials
402	Insufficient balance
403	Account suspended
404	Resource not found
409	Conflict, such as an already registered email
429	Rate limit exceeded
500	Server error
502	Provider call failed; gateway credits refunded automatically
503	Provider not configured

Health check

curl https://modelfold.ai/api/health

{ "ok": true, "db": "up" }

If the database is unavailable, returns 503 with {"ok":false,"db":"down"}.