API Gateway (/v1)

The gateway is the entry point for model calls. All endpoints authenticate with an API key:

Authorization: Bearer mf-...

All endpoints accept Content-Type: application/json. The request body limit is 100 MB.

GET /v1/models

Lists currently available 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 is the starting price. Video models billed per second include pricing: credits is the charge for the lowest tier (start_params) at the minimum duration (min_seconds), and credits_per_second is that tier's per-second price. Higher resolution, audio and longer durations change the price. The final charge is returned in usage.credits.

POST /v1/images/generations

Generates or edits an image.

Parameter	Type	Required	Description
model	string	Yes	Image model ID
prompt	string	Yes	Prompt, up to 2,000 characters
image_url	string	No	Reference image or source image URL
resolution	string	No	Resolution tier, such as 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"}'

Response:

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

POST /v1/videos/generations

Generates a video. Supports the image endpoint's fields plus video duration and resolution.

Parameter	Type	Required	Description
model	string	Yes	Video model ID
prompt	string	Yes	Prompt, up to 2,000 characters
image_url	string	No	First-frame image URL for image-to-video
duration	number	No	Duration in seconds
resolution	string	No	Resolution tier, such as 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"}'

Uses the same response structure as the image endpoint. data[0].url points to the generated video.

Model-specific parameters

The tables above list common fields only. Each model can require different fields, such as quality, aspect_ratio, image_urls, video_url or audio_url. Pass these fields at the top level, or inside params (params takes precedence). Do not wrap parameters in input. The gateway blocks callback URLs and output-count parameters; one request generates the model default number of outputs. Use the per-model parameter reference.

Requests wait for generation and return data[].url; use a client timeout of at least 20 minutes for long videos. Supported media models also offer async jobs, polling and callbacks.

POST /v1/audio/generations

Speech generation uses this endpoint. Pass prompt with the text to read, plus voice if supported; native text/voice or speakers/dialogue_turns structures are also supported for the corresponding models. The total spoken text must be nonempty and no longer than 5000 characters. See each audio model for required fields. Response structure matches image generation.

POST /v1/chat/completions

This endpoint returns complete JSON only. stream, tools and upstream-only parameters are not forwarded. For streaming and native agent protocols, see AI Agent.

Chat completions use OpenAI-compatible request and response structures.

Parameter	Type	Required	Description
model	string	Yes	Chat model ID
messages	array	Yes	Non-empty array of { role, content } objects
max_tokens	number	No	Defaults to 1024
temperature	number	No	Sampling temperature

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

Response:

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

Billing and safeguards

Each request follows the same sequence:

1. Check balance. Insufficient balance returns 402 without a provider call or a ledger entry.
2. Charge or reserve credits. Media uses the model's credit price; chat reserves credits based on estimated token usage.
3. Call the provider.
4. Settle usage. Chat is settled against actual usage, with the difference refunded or charged. Every adjustment is recorded in the ledger.
5. Refund failures. Provider errors automatically refund the call's credits and return 502.
6. Record the request. Successful and failed calls appear in the console's usage history.

Credits and provider usage

Media credit prices are derived from provider costs with a markup. Each model page lists its cost basis and billing unit. Chat model pages list input and output credit prices per million tokens. See Pricing.

Errors

HTTP	error.type	Description
400	unsupported_model	Unknown model or endpoint mismatch
400	invalid_prompt	Missing prompt or more than 2,000 characters
400	invalid_messages	Missing or empty messages
401	unauthorized	Invalid or revoked key
402	insufficient_credits	Insufficient balance
429	rate_limited	More than 60 requests per minute
502	upstream_failed	Provider call failed; credits refunded
503	upstream_unavailable	Provider for this model is not configured