> ## Documentation Index
> Fetch the complete documentation index at: https://magica.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get model input schema

> Return the input parameter schema for a single model — types, defaults, conditional fields, and ranges. Use this before running a model.

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`](/api-reference/nodes/run).

<Note>
  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.
</Note>

## Authorizations

<ParamField header="Authorization" type="string" required>
  Bearer API key. Format: `Bearer gx_your_api_key`.
</ParamField>

## Path parameters

<ParamField path="modelId" type="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`](/api-reference/nodes/list-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.
</ParamField>

## Response

<ResponseField name="modelId" type="string">
  Echoed back from the request.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable display name.
</ResponseField>

<ResponseField name="category" type="string">
  Model category (`text-to-image`, `image-to-video`, `text-to-speech`,
  `utility`, `media-understanding`, etc.).
</ResponseField>

<ResponseField name="description" type="string">
  Short description used in pickers.
</ResponseField>

<ResponseField name="features" type="string[]">
  Modality flags or feature labels for the model (e.g. `image`, `Premium`, `High
      Quality`).
</ResponseField>

<ResponseField name="capabilities" type="object">
  Capability flags or limits (`vision`, `audio`, `promptLimit`, etc.). Merged
  from `ui.capabilities` and top-level model config.
</ResponseField>

<ResponseField name="fields" type="array">
  Input field definitions in display order. Each entry:

  <Expandable title="Field properties">
    <ResponseField name="name" type="string">Field key — pass under `input` when running the model.</ResponseField>
    <ResponseField name="type" type="string">UI type (`text`, `select`, `number`, `image`, `audio`, `video`, …).</ResponseField>
    <ResponseField name="dataType" type="string">Underlying data type the gateway validator expects (`string`, `number`, `boolean`, `string[]`, …).</ResponseField>
    <ResponseField name="required" type="boolean">Present and `true` only when the field is required.</ResponseField>
    <ResponseField name="options" type="any[]">Enum options for `select`-type fields. Omitted otherwise.</ResponseField>
    <ResponseField name="default" type="any">Default value applied when the caller omits the field.</ResponseField>
    <ResponseField name="description" type="string">Merged label + description + help text.</ResponseField>
    <ResponseField name="showWhen" type="object">Conditional gate — the field is valid only when this condition holds (e.g. `{ "inputMode": "upload" }`). Use to detect mutually-exclusive fields.</ResponseField>
    <ResponseField name="placeholder" type="string">Suggested placeholder text.</ResponseField>
    <ResponseField name="min" type="number">Minimum value (numeric inputs).</ResponseField>
    <ResponseField name="max" type="number">Maximum value (numeric inputs).</ResponseField>
    <ResponseField name="maxLength" type="number">Max length (text inputs).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="defaults" type="object">
  Model-wide defaults (separate from per-field `default`). Currently empty for
  most models; reserved for future expansion.
</ResponseField>

## Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.magica.com/api/v1/models/flux-2-max-text/schema \
      -H "Authorization: Bearer $MAGICA_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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));
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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])
    ```
  </Tab>
</Tabs>

## Response example — success

Real response from `GET /v1/models/flux-2-max-text/schema`:

```json theme={null}
{
  "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`](/api-reference/nodes/list-models) to discover valid IDs |
| `500`  | Server error while resolving model definitions                                                     |

A 404 response uses the standard REST error envelope:

```json theme={null}
{
  "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_..."
}
```