Search models

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

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

fetch('https://api.magica.com/api/v1/models/search', 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/search",
  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/search"

	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/search")

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

{
  "modelCatalog": {},
  "categoryRoles": {},
  "usage": "<string>",
  "hint": "<string>",
  "noMatch": "<string>",
  "categoryRoleHints": {}
}

GET

models

Search models

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

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

fetch('https://api.magica.com/api/v1/models/search', 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/search",
  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/search"

	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/search")

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

{
  "modelCatalog": {},
  "categoryRoles": {},
  "usage": "<string>",
  "hint": "<string>",
  "noMatch": "<string>",
  "categoryRoleHints": {}
}

Returns a catalog of available generation models, grouped by category (text-to-image, image-to-video, lipsync, text-to-speech, …). Use the optional query parameter to filter to a single category or keyword.

This is the REST equivalent of the MCP search_tools tool. Both wrap the same searchTools 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.

Query parameters

string

Optional category or keyword filter. Examples: image (all image categories), video, text-to-speech, lipsync, transcription, music-generation, sound-effects, image-to-video (animate stills). Omit to receive the full catalog.

Response

object

Map keyed by category (e.g. text-to-image). Each entry holds the list of models in that category. Present whenever the query matches at least one category — i.e. not present on noMatch responses.

object

Map keyed by category, value is one of GENERATE (creates a new asset from text — text-to-image, text-to-video, TTS), EDIT (modifies an existing asset — image-to-image, voice-changing, upscalers), TRANSFORM (converts across media types — image-to-video, lipsync, audio-translation), or TRANSCRIBE / UNDERSTAND (transcription, multimodal LLM analysis).

string

Long-form usage guidance — primarily written for LLM consumers but useful as a reminder for human readers. Documents the typical workflow: search → model-schema → pricing → estimate → run.

string

Optional suggestion (e.g. “Use a query to filter…”). Present when no query was supplied.

string

Present only when query was supplied but matched no categories. Replaces modelCatalog in that case.

object

Returned alongside noMatch. Map of role → list of category keywords you could try instead.

Request

cURL
Node.js
Python

# All categories
curl https://api.magica.com/api/v1/models/search \
  -H "Authorization: Bearer $MAGICA_API_KEY"

# Filtered to text-to-speech models only
curl 'https://api.magica.com/api/v1/models/search?query=text-to-speech' \
  -H "Authorization: Bearer $MAGICA_API_KEY"

const res = await fetch(
  "https://api.magica.com/api/v1/models/search?query=image-to-video",
  { headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` } },
);
const payload = await res.json();

if (payload.noMatch) {
  console.warn(payload.noMatch);
} else {
  // List every modelId in every category
  const modelIds = Object.values(payload.modelCatalog).flatMap(
    (entries) => entries.map((e) => e.modelId),
  );
  console.log(modelIds);
}

import os, requests

res = requests.get(
    "https://api.magica.com/api/v1/models/search",
    params={"query": "lipsync"},
    headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
)
payload = res.json()

if "noMatch" in payload:
    print(payload["noMatch"])
else:
    for category, models in payload["modelCatalog"].items():
        role = payload["categoryRoles"].get(category)
        print(f"{category} ({role}):", [m["modelId"] for m in models])

Response example — success

{
  "modelCatalog": {
    "text-to-image": [
      { "modelId": "flux-2-max-pro", "name": "FLUX 2 Max Pro" },
      {
        "modelId": "nano-banana-2-text",
        "name": "Nano Banana 2 — Text to Image"
      }
    ],
    "image-to-image": [
      { "modelId": "nano-banana-pro-edit", "name": "Nano Banana Pro — Edit" }
    ]
  },
  "categoryRoles": {
    "text-to-image": "GENERATE",
    "image-to-image": "EDIT"
  },
  "usage": "Categories in `modelCatalog` are labelled in `categoryRoles` with one of: GENERATE / EDIT / TRANSFORM / TRANSCRIBE…"
}

Response example — no match

{
  "noMatch": "No models matching \"hologram\". Try category keywords: image, video, audio, text-to-image, image-to-image, image-to-video, video-to-video, lipsync, text-to-speech, music-generation, sound-effects, voice-changing, transcription.",
  "categoryRoleHints": {
    "GENERATE": [
      "text-to-image",
      "text-to-video",
      "text-to-speech",
      "music-generation",
      "sound-effects"
    ],
    "EDIT": ["image-to-image", "video-to-video", "voice-changing", "upscaler"],
    "TRANSFORM": ["image-to-video", "lipsync", "audio-translation"]
  },
  "usage": "Categories in `modelCatalog` are labelled in `categoryRoles` with one of: GENERATE / EDIT / TRANSFORM / TRANSCRIBE…"
}

The HTTP status is 200 in both cases — always check for noMatch before consuming modelCatalog.

Typical workflow

GET /v1/models/search?query=<category> — get the list of modelIds in that category.

Inspect inputs

GET /v1/models/{modelId}/schema — learn what fields the model expects.

(Optional) Estimate cost

POST /v1/nodes/estimate-credits — confirm the run won’t blow your budget.

Check balance

GET /v1/credits/balance — confirm the account can cover the estimated cost.

Run

POST /v1/nodes/{nodeType}/run — start the generation.

Errors

Status	Reason
`401`	Missing or invalid API key
`500`	Catalog assembly failed

Overview

Workflows

Models

Nodes

Runs

System Workflows

Credits

Media Library

Bug Reports

Search models

Authorizations

Query parameters

Response

Request

Response example — success

Response example — no match

Typical workflow

Errors

​Authorizations

​Query parameters

​Response

​Request

​Response example — success

​Response example — no match

​Typical workflow

​Errors

Authorizations

Query parameters

Response

Request

Response example — success

Response example — no match

Typical workflow

Errors