Skip to main content
GET
/
v1
/
models
/
{modelId}
/
schema
Get model input schema
curl --request GET \
  --url https://api.magica.com/api/v1/models/{modelId}/schema \
  --header 'Authorization: <authorization>'
{
  "modelId": "<string>",
  "name": "<string>",
  "category": "<string>",
  "description": "<string>",
  "features": [
    "<string>"
  ],
  "capabilities": {},
  "fields": [
    {
      "name": "<string>",
      "type": "<string>",
      "dataType": "<string>",
      "required": true,
      "options": [
        "<any>"
      ],
      "default": "<any>",
      "description": "<string>",
      "showWhen": {},
      "placeholder": "<string>",
      "min": 123,
      "max": 123,
      "maxLength": 123
    }
  ],
  "defaults": {}
}
Returns a normalized input schema for one model. Each field carries its type, dataType, required flag, default value, options, showWhen conditional gate, and range/length limits. Use it to build a form, validate inputs client-side, or discover what fields a model accepts before estimating credits or calling POST /v1/nodes/{nodeType}/run.
This is the REST equivalent of the MCP get_model_schema tool. Both wrap the same buildSchemaPayload helper server-side, so the response shape is identical across REST and MCP.

​
Authorizations

​
Authorization
string
required
Bearer API key. Format: Bearer gx_your_api_key.

​
Path parameters

​
modelId
string
required
Either a subModelId (e.g. flux-2-max-text, flux-2-max-edit, nano-banana-pro-text) or a nodeType (e.g. flux_2_max, crop_image). For multi-mode models (those with a subModels[] array in GET /v1/models), passing the nodeType returns the default sub-model’s schema — pass the specific subModelId to inspect a non-default mode. For single-mode models (gateway or utility), the nodeType and modelId are effectively the same.

​
Response

​
modelId
string
Echoed back from the request.
​
name
string
Human-readable display name.
​
category
string
Model category (text-to-image, image-to-video, text-to-speech, utility, media-understanding, etc.).
​
description
string
Short description used in pickers.
​
features
string[]
Modality flags or feature labels for the model (e.g. image, Premium, High Quality).
​
capabilities
object
Capability flags or limits (vision, audio, promptLimit, etc.). Merged from ui.capabilities and top-level model config.
​
fields
array
Input field definitions in display order. Each entry:
​
defaults
object
Model-wide defaults (separate from per-field default). Currently empty for most models; reserved for future expansion.

​
Request

curl https://api.magica.com/api/v1/models/flux-2-max-text/schema \
  -H "Authorization: Bearer $MAGICA_API_KEY"

​
Response example — success

Real response from GET /v1/models/flux-2-max-text/schema: 
{
  "modelId": "flux-2-max-text",
  "name": "FLUX 2 Max",
  "category": "text-to-image",
  "description": "State-of-the-art image generation with exceptional realism, precision, and consistency",
  "features": ["High Quality", "Premium"],
  "capabilities": {
    "promptLimit": 3500,
    "promptLimitType": "characters"
  },
  "fields": [
    {
      "name": "prompt",
      "type": "textarea",
      "dataType": "string",
      "required": true,
      "default": "",
      "description": "Text prompt describing the image to generate, up to 3500 characters, required",
      "placeholder": "Describe the image you want to create...",
      "max": 3500
    },
    {
      "name": "num_images",
      "type": "select",
      "dataType": "number",
      "options": [1, 2, 3, 4],
      "default": 1,
      "description": "Number of images to generate, default 1."
    },
    {
      "name": "image_size",
      "type": "composite-select",
      "dataType": "string",
      "options": ["Custom", "4:3", "16:9", "3:4", "9:16", "1:1"],
      "default": "4:3",
      "description": "Output image dimensions, default 4:3."
    },
    {
      "name": "seed",
      "type": "number",
      "dataType": "number",
      "default": null,
      "description": "Optional seed for reproducible generation. null = random.",
      "min": 0,
      "max": 2147483646
    },
    {
      "name": "output_format",
      "type": "select",
      "dataType": "string",
      "options": ["JPEG", "PNG"],
      "default": "JPEG",
      "description": "Output file format, default JPEG."
    }
  ],
  "defaults": {
    "prompt": "",
    "image_size": "4:3",
    "output_format": "JPEG",
    "num_images": 1,
    "sync_mode": false,
    "safety_tolerance": "5",
    "enable_safety_checker": false
  }
}

​
Errors

StatusReason
401Missing or invalid API key
404Unknown modelId — use GET /v1/models to discover valid IDs
500Server error while resolving model definitions
A 404 response uses the standard REST error envelope: 
{
  "error": "Model \"not-a-real-model\" not found. Load the model-recommendations Skill or use search_tools to find valid model IDs.",
  "message": "Model \"not-a-real-model\" not found. Load the model-recommendations Skill or use search_tools to find valid model IDs.",
  "code": "NOT_FOUND",
  "traceId": "req_..."
}