Get model input schema

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

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

fetch('https://inference.magica.com/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://inference.magica.com/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://inference.magica.com/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://inference.magica.com/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>",
  "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://inference.magica.com/v1/models/{modelId}/schema \
  --header 'Authorization: <authorization>'

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

fetch('https://inference.magica.com/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://inference.magica.com/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://inference.magica.com/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://inference.magica.com/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>",
  "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 catalog source as MCP, so the response shape is consistent across public interfaces.

Use the returned fields and capabilities to discover the selected model’s current controls, defaults, accepted values, and limits. Fetch model pricing for its billing rules and a sample-input estimate.

Authorizations

string

required

Bearer API key. Format: Bearer gx_your_api_key.

Path parameters

string

required

Either a subModelId (e.g. nano-banana-pro-text, nano-banana-pro-edit, gpt-image-2-text) or a nodeType (e.g. nano_banana_pro, 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.

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://inference.magica.com/v1/models/nano-banana-pro-text/schema \
  -H "Authorization: Bearer $MAGICA_API_KEY"

const modelId = "nano-banana-pro-text";
const res = await fetch(
  `https://inference.magica.com/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 = "nano-banana-pro-text"
res = requests.get(
    f"https://inference.magica.com/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/nano-banana-pro-text/schema:

{
  "modelId": "nano-banana-pro-text",
  "name": "Nano Banana Pro",
  "category": "text-to-image",
  "description": "Google's Gemini 3 Pro Image model with web search grounding.",
  "capabilities": {
    "promptLimit": 50000,
    "promptLimitType": "characters"
  },
  "fields": [
    {
      "name": "prompt",
      "type": "textarea",
      "dataType": "string",
      "required": true,
      "description": "Text prompt describing the image to generate, max 50000 characters, required",
      "placeholder": "Describe the image you want to create...",
      "max": 50000
    },
    {
      "name": "resolution",
      "type": "select",
      "dataType": "string",
      "options": ["1K", "2K", "4K"],
      "default": "1K",
      "description": "Output image resolution tier with default 1K, options are 1K, 2K, 4K"
    },
    {
      "name": "aspect_ratio",
      "type": "select",
      "dataType": "string",
      "options": [
        "auto",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "21:9",
        "5:4",
        "4:5"
      ],
      "default": "1:1",
      "description": "Output image aspect ratio with default 1:1, options are auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 5:4, 4:5"
    },
    {
      "name": "enable_web_search",
      "type": "toggle",
      "dataType": "boolean",
      "default": false,
      "description": "Enable Google Search grounding for real-world context, default is false (disabled). When enabled, the model uses web search results to inform image generation — Use Google Search for context and grounding"
    },
    {
      "name": "num_images",
      "type": "select",
      "dataType": "number",
      "options": [1, 2, 3, 4],
      "default": 1,
      "description": "Number of images to generate with default 1, options are 1, 2, 3, 4"
    },
    {
      "name": "output_format",
      "type": "select",
      "dataType": "string",
      "options": ["PNG", "JPEG", "WebP"],
      "default": "PNG",
      "description": "Output file format of the generated image with default PNG, options are PNG, JPEG, WebP"
    },
    {
      "name": "seed",
      "type": "number",
      "dataType": "number",
      "description": "Optional seed number for reproducible image generation, default is null (random). Enter any integer to get the same result each time — Random seed for reproducible generation",
      "placeholder": "Enter a number for reproducible results",
      "min": 0,
      "max": 2147483646
    },
    {
      "name": "system_prompt",
      "type": "textarea",
      "dataType": "string",
      "default": "",
      "description": "Optional system prompt to steer the model's style or persona, max 5000 characters. Leave blank to omit. — Sent to the model alongside the user prompt",
      "placeholder": "e.g. 'Always render in watercolor style…'",
      "max": 5000
    }
  ],
  "defaults": {
    "resolution": "1K",
    "enable_web_search": false,
    "aspect_ratio": "1:1",
    "num_images": 1,
    "output_format": "PNG",
    "system_prompt": ""
  }
}

Errors

Status	Reason
`401`	Missing or invalid API key
`429`	API key rate limit exceeded
`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

Models

Standalone Model Runs

LLM Gateway

Credits

Generated Media

Get model input schema

Authorizations

Path parameters

Response

Request

Response example — success

Errors