Get model input schema

curl --request GET \
  --url https://api.magica.com/api/v1/models/{modelId}/schema \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.magica.com/api/v1/models/{modelId}/schema', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magica.com/api/v1/models/{modelId}/schema",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magica.com/api/v1/models/{modelId}/schema"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.magica.com/api/v1/models/{modelId}/schema")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

GET

models

{modelId}

schema

Get model input schema

curl --request GET \
  --url https://api.magica.com/api/v1/models/{modelId}/schema \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.magica.com/api/v1/models/{modelId}/schema', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magica.com/api/v1/models/{modelId}/schema",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magica.com/api/v1/models/{modelId}/schema"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.magica.com/api/v1/models/{modelId}/schema")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

string

required

Bearer API key. Format: Bearer gx_your_api_key.

Path parameters

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

string

Echoed back from the request.

string

Human-readable display name.

string

Model category (text-to-image, image-to-video, text-to-speech, utility, media-understanding, etc.).

string

Short description used in pickers.

string[]

Modality flags or feature labels for the model (e.g. image, Premium, High Quality).

object

Capability flags or limits (vision, audio, promptLimit, etc.). Merged from ui.capabilities and top-level model config.

array

Input field definitions in display order. Each entry:

Show Field properties

string

Field key — pass under input when running the model.

string

UI type (text, select, number, image, audio, video, …).

string

Underlying data type the gateway validator expects (string, number, boolean, string[], …).

boolean

Present and true only when the field is required.

any[]

Enum options for select-type fields. Omitted otherwise.

any

Default value applied when the caller omits the field.

string

Merged label + description + help text.

object

Conditional gate — the field is valid only when this condition holds (e.g. { "inputMode": "upload" }). Use to detect mutually-exclusive fields.

string

Suggested placeholder text.

number

Minimum value (numeric inputs).

number

Maximum value (numeric inputs).

number

Max length (text inputs).

object

Model-wide defaults (separate from per-field default). Currently empty for most models; reserved for future expansion.

Request

cURL
Node.js
Python

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

const modelId = "flux-2-max-text";
const res = await fetch(
  `https://api.magica.com/api/v1/models/${modelId}/schema`,
  { headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` } },
);

if (res.status === 404) {
  throw new Error(`Model "${modelId}" not found`);
}

const schema = await res.json();
const required = schema.fields.filter((f) => f.required);
console.log("Required:", required.map((f) => f.name));

import os, requests

model_id = "flux-2-max-text"
res = requests.get(
    f"https://api.magica.com/api/v1/models/{model_id}/schema",
    headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
)

if res.status_code == 404:
    raise RuntimeError(f'Model "{model_id}" not found')

schema = res.json()
required = [f for f in schema["fields"] if f.get("required")]
print("Required:", [f["name"] for f in required])

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

Status	Reason
`401`	Missing or invalid API key
`404`	Unknown `modelId` — use `GET /v1/models` to discover valid IDs
`500`	Server 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_..."
}

Overview

Workflows

Models

Nodes

Runs

System Workflows

Credits

Media Library

Bug Reports

Get model input schema

Authorizations

Path parameters

Response

Request

Response example — success

Errors

​Authorizations

​Path parameters

​Response

​Request

​Response example — success

​Errors

Authorizations

Path parameters

Response

Request

Response example — success

Errors