GenMagic

Servidor MCP alojado para más de 450 modelos de IA: genera imágenes, video, voz, música y texto con una sola clave de API y un saldo de pago por uso. Elige cualquier modelo por id (list_models muestra ids y precios) o deja que GenMagic elija; el video se cobra solo cuando se completa.

Servidor MCP alojado

npx add-mcp 'https://genmagic.co/api/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

The GenMagic API

OpenAI-compatible endpoints for every text and vision model, for image generation, for speech and music, and for video, a typed /text call for on-brand artifacts, plus an MCP server for agents. Point any OpenAI SDK at your base URL, drop in a key, and ship. A call from your code costs exactly what a call from the studio costs: the same credit balance, at the same price. Every modality the studio makes, your code makes too.

Building with a coding agent (Claude Code, Codex, Cursor, Copilot)? Run npx skills add https://genmagic.co/ to teach it images, video, speech and music on GenMagic, or point it at llms.txt and this page. It reads your key from GENMAGIC_API_KEY.

On this page

Setup

Realtime

Control

Catalog

Orchestrate

Agents

For platforms

Reference

On-brand

Help

Base URL and authentication

The API is served from your GenMagic domain under /api/v1. Authenticate with a secret key in the Authorization header. Create a key on the API keys page of your account (sign up free if you have none, and verify your email to unlock the free starter credit, one per person). A key is shown once, so store it somewhere safe.

https://genmagic.co/api/v1
Authorization: Bearer gm_live_...

Keep keys server-side. Never embed a key in a browser bundle or mobile app: anyone who reads it can spend your credits.

Your first call

POST /chat/completions is the core call. It is OpenAI-compatible, so the official OpenAI SDKs work unchanged: just set the base URL and your GenMagic key.

curl https://genmagic.co/api/v1/chat/completions \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "Write a haiku about shipping fast." }]
  }'
from openai import OpenAI

client = OpenAI(
    base_url="https://genmagic.co/api/v1",
    api_key="YOUR_GENMAGIC_API_KEY",
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Write a haiku about shipping fast."}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://genmagic.co/api/v1",
  apiKey: process.env.GENMAGIC_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-5",
  messages: [{ role: "user", content: "Write a haiku about shipping fast." }],
});
console.log(resp.choices[0].message.content);

Streaming

Set "stream": true to receive tokens as server-sent events, in the same chunk format OpenAI uses. Usage is metered from the provider’s authoritative token count when the stream finishes.

curl https://genmagic.co/api/v1/chat/completions \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "stream": true,
    "messages": [{ "role": "user", "content": "Stream a short story." }]
  }'

Reasoning, parameters and caching

/chat/completions forwards your request body to the model unchanged, so every parameter the model supports works as sent: temperature, tools, response_format, seed and the rest. Each model lists the ones it honours in supported_parameters on GET /models.

Reasoning models take reasoning_effort, or the object form reasoning: { effort, enabled, max_tokens }. The effort values a model accepts are in its capabilities.reasoning_efforts; when capabilities.reasoning_mandatory is true, thinking cannot be switched off and "enabled": false is refused with a 400. Reasoning tokens are reported in usage.completion_tokens_details.reasoning_tokens.

curl https://genmagic.co/api/v1/chat/completions \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "reasoning_effort": "high",
    "messages": [{ "role": "user", "content": "How many weekdays are there in March 2027?" }]
  }'

Every model’s full price sheet is in GET /models, and a call costs exactly what it lists, cached input and long prompts included: cached input tokens at pricing.cache_read_usd_per_million (cache writes at cache_write_usd_per_million) where a model publishes them, and a prompt that reaches a band’s min_prompt_tokens in pricing.tiers at that band’s prices.

Generate

Typed, on-brand text

POST /text returns a specific text ARTIFACT, steered on-brand the way the studio does: pass a type and get back the finished thing. With brand personalization on, an svg and a website come out in your exact palette and typeface, and writing and code carry your voice. This is the difference from /chat/completions: that endpoint is the raw OpenAI-compatible model call (your brand VOICE is applied, but it has no notion of an artifact type), while /text adds the type’s system prompt and, for svg / website, the visual palette and typeface. An SVG is returned with content-provenance metadata embedded.

type is one of writing, code, svg, or website (omit it for a plain, voice-branded generation). Each type picks a sensible default model, or set model yourself from /models. Optional system adds an extra steer on top of your brand, and attachments let the model read a reference image, PDF, or document.

curl https://genmagic.co/api/v1/text \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "svg",
    "prompt": "A geometric mountain badge, flat, three shapes"
  }'
# -> { "created": ..., "model": "...", "type": "svg", "text": "<svg ...>...</svg>",
#      "usage": { "input_tokens": ..., "output_tokens": ... } }

curl (a landing page in your brand)

curl https://genmagic.co/api/v1/text \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "website",
    "prompt": "A landing page for a small-batch coffee roaster, warm and minimal"
  }'
import requests

r = requests.post(
    "https://genmagic.co/api/v1/text",
    headers={"Authorization": "Bearer YOUR_GENMAGIC_API_KEY"},
    json={"type": "svg", "prompt": "A minimalist wifi icon"},
).json()
print(r["text"])

The response is { created, model, type?, text, usage }. Cost and the balance left come back in the X-Cost-Cents and X-Credits-Remaining headers (see Errors), the same as every metered call. An svg or website generated with brand personalization on also returns X-Brand-Fit (on_brand, wrong_palette, or monochrome): a read-back of the artifact’s colors (the vector’s fills, or the page’s CSS), so you can regenerate one that came out off your palette. It is a best-effort hint, present only when the output could be measured against a brand color.

Generate

Images

POST /images/generations generates images, in OpenAI’s image shape, so client.images.generate(...) works unchanged. Choose any image model from /models (or omit model for the recommended default). Set size (e.g. 1024x1024, 1792x1024) and response_format (url or b64_json). Any width x height works: the image is made in the closest shape the model renders, listed as capabilities.aspect_ratios in /models (1024x768 is 4:3). A model’s listed price per image is for 1024x1024; a size with a long side of 1536 or more is made at 2K, which costs more on the models that bill by size (FLUX bills by the pixel), and the answer’s X-Cost-Cents header says what each image cost. An app with OpenAI’s model names built in works by changing only its base URL and key: a bare name such as gpt-image-2 runs as openai/gpt-image-2 (the answer’s model says which ran), and with no response_format a request written for OpenAI’s GPT Image API (a bare GPT Image name, or its fields such as quality: "auto") is answered in b64_json, as OpenAI answers it, so n8n’s OpenAI node and LibreChat’s image tool work as they are. A request that still names dall-e-3 or dall-e-2, which OpenAI removed from its API on May 12, 2026, runs on GPT Image 1 Mini, OpenAI’s own named replacement (the answer’s model says so).

Image-to-image (references). Pass an image (an https URL or a data:image URL) to TRANSFORM that image instead of generating from scratch: send a character or product and it is kept, not replaced. A Google Drive or Dropbox share link works too: it is read as the file it points to (share the file with anyone who has the link). The model receives the reference (an unusable one is rejected, never silently dropped). Add "type": "logo" to steer the result as a brand mark. The reference reaches the model identically to the studio. Every image model's price is on image API pricing.

Several references in one image. Send image as a list (up to 16) and the model follows them together, for example a layout to keep and two characters to place in it. Each keeps its own role: say in the prompt which is which, in the order sent (“image 1 is the layout, image 2 the first character”). Models that read several pictures, such as Nano Banana and Qwen Image, use them all. OpenAI's images list and several image[] files on /images/edits work the same way.

curl https://genmagic.co/api/v1/images/generations \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-nano-banana-2.1",
    "prompt": "A cobalt prism refracting into a spectrum, dark studio, 3D render",
    "size": "1024x1024"
  }'
curl https://genmagic.co/api/v1/images/generations \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "the same character as a marble statue on a plinth",
    "image": "https://your-cdn.com/green-frog-knight.png"
  }'

curl (several references: a layout and two characters)

curl https://genmagic.co/api/v1/images/generations \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen-image-3",
    "prompt": "Image 1 is the layout: keep this house and camera angle. Image 2 and image 3 are two characters: place them on the terrace, each keeping their exact look.",
    "image": [
      "https://your-cdn.com/layout.png",
      "https://your-cdn.com/character-1.png",
      "https://your-cdn.com/character-2.png"
    ]
  }'
from openai import OpenAI

client = OpenAI(base_url="https://genmagic.co/api/v1", api_key="YOUR_GENMAGIC_API_KEY")

img = client.images.generate(
    model="google/gemini-nano-banana-2.1",
    prompt="A cobalt prism refracting into a spectrum, dark studio, 3D render",
    size="1024x1024",
)
print(img.data[0].url)

Moving image code off a lab's own API? Our GPT Image API guide covers OpenAI's shutdown of GPT Image 1, what each quality setting costs per image, and every platform that resells it; the Nano Banana API guide does the same for Google's image models, and our guides to the FLUX, Seedream, Qwen Image, Krea and Recraft APIs cover Black Forest Labs, ByteDance, Alibaba, Krea and Recraft, whose vector models return real SVG files. Coming from Midjourney, which has no API? Our Midjourney API guide maps each Midjourney job to a model you can call.

Speech and music

POST /audio/speech turns text into spoken audio, in OpenAI’s speech shape, so client.audio.speech.create(...) works unchanged. POST /audio/music generates an original music track from a description. Both return the raw audio bytes (the model’s native container, e.g. audio/mpeg); the durable hosted URL comes back in the X-Media-Url response header.

curl https://genmagic.co/api/v1/audio/speech \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Welcome to the future of on-brand generation.",
    "voice": "alloy"
  }' --output speech.mp3
from openai import OpenAI

client = OpenAI(base_url="https://genmagic.co/api/v1", api_key="YOUR_GENMAGIC_API_KEY")

with client.audio.speech.with_streaming_response.create(
    model="openai/gpt-audio-mini",
    voice="alloy",
    input="Welcome to the future of on-brand generation.",
) as response:
    response.stream_to_file("speech.mp3")
curl https://genmagic.co/api/v1/audio/music \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "warm lo-fi hip hop, mellow keys, soft vinyl crackle, 80 bpm"
  }' --output track.wav

With brand personalization on, music is nudged on-brand in mood automatically. Speech is voiced verbatim, so it is never altered. Looking for a Suno API? Suno has none open to the public yet; our Suno API guide covers its invite-only beta and the music APIs you can call today.

Generate

Video

Video is asynchronous (a clip takes seconds to minutes), so it is a two-step, poll-based flow. POST /videos starts a job and returns its id immediately; then poll GET /videos/{id} until status is completed, at which point you get a durable url. Nothing is charged until the clip completes, and a finished job is billed exactly once no matter how many times you poll it.

Clips are made from your prompt, so pick a model whose capabilities.text_to_video is true in GET /models?category=video (or omit model for the default), or a talking-photo model (below). Models that edit or upscale media you supply are listed with false and refused with 400 model_not_supported.

Animate an image. Pass image (an https URL or a data:image URL) and the clip opens on that still, with the prompt describing the motion; models that take one also accept a last_frame to end on. Each video model lists the frames it takes in capabilities.frame_images. Most models bill it like a clip from a prompt alone. Where one does not, its pricing.video says so: image_to_video_usd_per_second is a rate of its own, and image_input_usd is a fee for each image you supply. Every video model's price per second, side by side, is on video API pricing.

curl https://genmagic.co/api/v1/videos \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0-fast",
    "prompt": "the boat drifts toward the camera as rain ripples the water",
    "image": "https://example.com/paper-boat.png"
  }'

Make a photo talk. A talking-photo model (capabilities.talking_photo, such as HeyGen Avatar IV) takes a portrait as image and says prompt word for word, lip-synced, in the voice you name from its capabilities.voices. There is no duration: the clip lasts as long as the words take to say and is billed for those seconds.

curl https://genmagic.co/api/v1/videos \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen/avatar-iv",
    "image": "https://example.com/presenter.jpg",
    "prompt": "Welcome to the first lesson. This takes ten minutes.",
    "voice": "Cassidy"
  }'

Keep characters and objects consistent. Pass references, up to nine images (https or data:image URLs) of the people, props or look the clip should keep, none of them a frame of it, and say in the prompt who is who. Models made for it have capabilities.references set to true; with no model, one of them is chosen. A clip follows references or opens on an image, not both.

For a series, send the same character sheets in references on every clip, keep one model per episode, and end every prompt with the same style line. To pick up exactly where a clip ended, take its last frame (for example ffmpeg -sseof -0.1 -i clip.mp4 -frames:v 1 last.png) and send it as image for the next clip. The whole workflow: how to make an AI cartoon series.

curl https://genmagic.co/api/v1/videos \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "the doctor from the first image walks through the clinic door from the second and greets the camera",
    "references": ["https://example.com/doctor.png", "https://example.com/clinic-door.png"]
  }'
curl https://genmagic.co/api/v1/videos \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a paper boat sailing down a rain gutter, cinematic, slow motion",
    "aspect_ratio": "16:9"
  }'
# -> 202 { "id": "gen-vid-...", "object": "video.generation", "model": "...",
#          "status": "queued", "created": 1791171015, "status_url": "/api/v1/videos/gen-vid-...",
#          "estimate": { "typical_seconds": 140, "slow_seconds": 200 } }
# estimate: how long this model usually takes on GenMagic (customers' clips, last 30 days), when measured
curl https://genmagic.co/api/v1/videos/gen-vid-... \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "id": "gen-vid-...", "object": "video.generation", "model": "...", "status": "processing" }
#    ... keep polling ...
# -> { "id": "gen-vid-...", "object": "video.generation", "model": "...", "status": "completed",
#      "url": "https://.../clip.mp4", "cost_cents": 25 }
import time, requests

base = "https://genmagic.co/api/v1"
headers = {"Authorization": "Bearer YOUR_GENMAGIC_API_KEY"}

job = requests.post(f"{base}/videos", headers=headers, json={
    "prompt": "a paper boat sailing down a rain gutter, cinematic, slow motion",
    "aspect_ratio": "16:9",
}).json()

# Poll about six times over the model's usual time (a Wan 3.0 clip takes minutes, Veo 3.1 Lite under one).
wait = max(5, min(30, job.get("estimate", {}).get("typical_seconds", 60) // 6))
while True:
    s = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(wait)

print(s.get("url") or s.get("error"))
curl "https://genmagic.co/api/v1/videos?limit=10" \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "object": "list", "has_more": true, "first_id": "gen-vid-...", "last_id": "gen-vid-...",
#      "data": [ { "id": "gen-vid-...", "model": "...", "status": "completed", "url": "https://.../clip.mp4", ... } ] }
# next page: ?limit=10&after=<last_id>

Code written for OpenAI's Videos API runs too. The OpenAI SDKs' client.videos.create, create_and_poll, retrieve and download_content work against this base URL: send seconds, size and an input_reference image as you did for Sora 2, with a GenMagic video model id. Code that still names sora-2 runs on Veo 3.1 Fast and sora-2-pro on Veo 3.1, and the answer's model names the model that ran. Those calls answer with OpenAI's Video object (an id starting video_, statuses queued, in_progress, completed, failed), and the clip downloads from /videos/{id}/content. Moving off Sora 2: what changes and what each model costs for a typical Sora call is on the Sora 2 API alternative page.

from openai import OpenAI

client = OpenAI(base_url="https://genmagic.co/api/v1", api_key="YOUR_GENMAGIC_API_KEY")

video = client.videos.create_and_poll(
    model="google/veo-3.1-lite",
    prompt="a paper boat sailing down a rain gutter, cinematic, slow motion",
    seconds="8",
    size="1280x720",
)
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("boat.mp4")

With brand personalization on, the clip is steered on-brand (palette and aesthetic) automatically, exactly like an image. Statuses are queued, processing, completed, and failed. A job the provider could not render is a failed poll at HTTP 200 whose error is a plain-text message (a string, not an object); url and cost_cents appear only once the clip is completed, as does the X-Cost-Cents header (X-Credits-Remaining comes only with the poll that settles the charge).

Coming from a lab's own video API? Each guide covers what that lab asks for, what it charges and every platform that resells it: Veo 3.1, Kling, Seedance 2.0, Wan 3.0, HappyHorse, Hailuo, Runway, Grok Imagine and HeyGen. Moving off OpenAI's Videos API, which shut down with Sora 2 on September 24, 2026? The same guide maps its fields to these.

Listing models

GET /models returns every model available right now, in OpenAI’s list shape, with each model’s full detail: name, description, context length, input/output modalities, capabilities (reasoning, vision, tools, structured output, voices), pricing in each model’s real unit (a unit of token, image, minute, or second, with usd_per_unit, and for video the per-second price at every supported resolution, with and without sound, plus the clip lengths), and benchmark scores where published. The catalog is live: new models appear the day they launch, no SDK update required. This is a pure lookup: it needs no API key and spends no credits. A request that does send a key has the key checked and counted toward its per-key rate limit (see Errors), so cache the catalog and refresh it periodically rather than polling on a tight loop.

The list is ordered newest first, by created (a Unix timestamp in seconds). Filter with ?category= (text, image, audio, video), ?capability= (reasoning, vision, tools, structured), ?audio_kind= (speech, music), and ?search= (id or name). Retrieve one model with GET /models/{id} (the id contains a slash, e.g. /models/openai/gpt-image-2).

# Every model, full detail
curl https://genmagic.co/api/v1/models \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"

# Only image models
curl "https://genmagic.co/api/v1/models?category=image" \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"

# One model's details
curl https://genmagic.co/api/v1/models/openai/gpt-image-2 \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"

The list returns { "object": "list", "data": [ ... ] }; each entry (and the retrieve response) is one model object. Text models carry per-token pricing (prompt_usd_per_million, completion_usd_per_million, and where the model publishes them cache_read_usd_per_million, cache_write_usd_per_million, reasoning_usd_per_million and long-context tiers), the request parameters they honour in supported_parameters, and for reasoning models capabilities.reasoning_efforts and reasoning_mandatory (see Reasoning); image, audio, and video carry a per-generation estimate. For an image model that is one 1024x1024 image from a short prompt (usd_per_unit); a model that bills its input also carries input_usd_per_million, the price of the prompt and of every reference image, charged on top of the image, and a larger size costs more. What each call cost comes back in its X-Cost-Cents header, and every creation's cost is listed in your library on the site. Audio models also carry audio_kind: speech for a model POST /audio/speech runs, music for one POST /audio/music runs. Every model also carries a single comparable est_per_generation_usd.

{
  "id": "openai/gpt-image-2",
  "object": "model",
  "created": 1751068800,
  "owned_by": "openai",
  "name": "OpenAI: GPT Image 2",
  "description": "Image generation and editing model.",
  "category": "image",
  "input_modalities": ["text", "image"],
  "output_modalities": ["image"],
  "context_length": 0,
  "capabilities": {
    "reasoning": false,
    "reasoning_by_default": false,
    "vision": true,
    "tools": false,
    "structured_output": false
  },
  "pricing": {
    "currency": "USD",
    "unit": "image",
    "image_output_usd_per_token": 0.000045,
    "input_usd_per_million": 12,
    "usd_per_unit": 0.0387,
    "est_per_generation_usd": 0.0387
  }
}

Your agent, over the API

POST /agent/turn is the API face of your GenMagic agent: send a conversation and it replies in character AND returns the set of assets to make across modalities, on brand. It plans, you make. Planning is not billed; you then generate each returned asset by calling the endpoint for its modality (/chat/completions for text, /images/generations for image, /audio/speech or /audio/music for audio, /videos for video).

curl https://genmagic.co/api/v1/agent/turn \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Make a launch tweet and a logo for a cold brew brand called Northwind." }
    ]
  }'

The response is { reply, assets: [{ modality, title, prompt, aspect_ratio?, voice? }] }. Feed each asset’s prompt to the matching endpoint to generate it.

Agents

Use it from an agent (MCP)

GenMagic is also a Model Context Protocol server, so an AI agent can generate through it directly. Point any MCP client (VS Code, Cursor, Claude Code, Claude Desktop, or your own) at the endpoint below with your key, and the agent gets seven tools: generate_text, generate_image, generate_speech, generate_music, for video create_video + get_video (create returns a job id, get_video polls it until the clip is ready), and list_models. A tool call is billed exactly like any other call, and comes out on-brand when personalization is on.

Any model, by id. Every generate tool takes an optional model: the same ids as the REST API and the model library. The agent finds them with list_models (filter by category or search), which needs no key and returns each model’s price, the voices of speech models and the resolutions, clip lengths and sound support of video models, plus the default each tool runs when no model is named. create_video also takes duration, resolution, generate_audio, and image / last_frame to animate a still. An id that a tool does not run is refused with a pointer to list_models, never swapped for another model, and every result names the model that ran.

https://genmagic.co/api/mcp

Claude and ChatGPT: sign in instead of a key. Their connector screens take an address but no header, so they use the sign-in address below: add it as a custom connector, sign in to GenMagic when asked and choose Allow. The app gets a key of its own, listed under API keys on your account page where you can revoke it, and every generation draws on your balance as usual. Any client that follows the MCP authorization spec (OAuth 2.1 with PKCE and dynamic client registration) can use it, Claude Code included. Step-by-step setup for each app is on the MCP server page.

https://genmagic.co/api/mcp/connect

Connect in one click. VS Code asks for your key once and keeps it as a secret. Cursor adds the server with a placeholder: replace YOUR_GENMAGIC_API_KEY with your key under Cursor Settings, MCP.

claude mcp add --transport http genmagic https://genmagic.co/api/mcp \
  --header "Authorization: Bearer $GENMAGIC_API_KEY"
{
  "inputs": [
    { "type": "promptString", "id": "genmagic-api-key", "description": "GenMagic API key", "password": true }
  ],
  "servers": {
    "genmagic": {
      "type": "http",
      "url": "https://genmagic.co/api/mcp",
      "headers": { "Authorization": "Bearer ${input:genmagic-api-key}" }
    }
  }
}

Cursor, Claude Desktop, Windsurf and most other clients take the same URL and an Authorization header under mcpServers:

{
  "mcpServers": {
    "genmagic": {
      "url": "https://genmagic.co/api/mcp",
      "headers": { "Authorization": "Bearer $GENMAGIC_API_KEY" }
    }
  }
}

Under the hood it is plain JSON-RPC, so you can call it with anything:

curl https://genmagic.co/api/mcp \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

curl (list video models with their prices and options; no key needed)

curl https://genmagic.co/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 5, "method": "tools/call",
    "params": { "name": "list_models", "arguments": { "category": "video", "limit": 10 } }
  }'

curl (generate an image with a chosen model)

curl https://genmagic.co/api/mcp \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "generate_image",
      "arguments": {
        "prompt": "a cobalt prism on black, 3D render",
        "size": "1024x1024",
        "model": "google/gemini-nano-banana-2.1"
      }
    }
  }'
curl https://genmagic.co/api/mcp \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {
      "name": "generate_music",
      "arguments": { "prompt": "warm lo-fi hip hop, mellow keys, 80 bpm" }
    }
  }'

curl (start a video, then poll get_video)

curl https://genmagic.co/api/mcp \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 4, "method": "tools/call",
    "params": {
      "name": "create_video",
      "arguments": {
        "prompt": "a paper boat sailing down a rain gutter, cinematic",
        "aspect_ratio": "16:9",
        "model": "google/veo-3.1-fast",
        "duration": 8,
        "resolution": "720p"
      }
    }
  }'
# then poll: params.name "get_video", arguments { "id": "<the returned job id>" }

Every tool result self-describes its spend. A JSON-RPC body has no per-call headers, so each tool result carries its metering in the standard MCP _meta field, under the key genmagic.ai/usage: cost_cents (what the call cost), credits_remaining (your balance after it), and a rate object (limit, remaining, reset). It is the MCP mirror of the REST response headers below, so an agent paces itself and tracks spend from the result it already has. A create_video submit and a still-rendering get_video poll charge nothing, so they report rate headroom only; the clip’s cost lands on the poll that completes it. Fields are omitted, never faked, when a value is unknown.

Visual calls also report brand fit. When you generate a logo, a branded svg, or a branded website and your brand has a color set, the result’s _meta carries a brand_fit object: label is on_brand, wrong_palette (the output came out in an off-brand color, worth regenerating), or monochrome (intentionally colorless, not a problem), alongside a presence fraction and a foreign_dominant_hue flag. An agent can read it and regenerate an artifact that drifted off-brand, without a human in the loop. It is present only when the output could actually be measured, so it is simply absent for prose/code calls or a format we do not decode.

Integrations

Use it with the Vercel AI SDK

GenMagic works with the Vercel AI SDK through its OpenAI-compatible provider, so there is no GenMagic package to install. Create the provider with your base URL and API key, then use generateText, streamText, tool calling, and generateImage with any model id from the catalog.

npm install ai @ai-sdk/openai-compatible
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText, streamText } from "ai";

const genmagic = createOpenAICompatible({
  name: "genmagic",
  apiKey: process.env.GENMAGIC_API_KEY,
  baseURL: "https://genmagic.co/api/v1",
  includeUsage: true, // token usage on streamed responses too
});

const { text } = await generateText({
  model: genmagic("anthropic/claude-sonnet-5"),
  prompt: "Write a haiku about shipping fast.",
});

const result = streamText({
  model: genmagic("google/gemini-3.5-flash"),
  prompt: "Count from 1 to 5, separated by spaces.",
});
for await (const part of result.textStream) process.stdout.write(part);

Images go through generateImage. The AI SDK reads images as base64, so ask for b64_json with a provider option keyed by the provider name you chose:

import { generateImage } from "ai";

const { image } = await generateImage({
  model: genmagic.imageModel("recraft/recraft-v4.1-flash"),
  prompt: "A watercolor fox reading a book under a tree",
  providerOptions: { genmagic: { response_format: "b64_json" } },
});
// image.uint8Array, image.base64, image.mediaType

Model ids come from GET /models, which needs no key (filter with ?category=text or ?category=image). Tool calling works with models whose capabilities.tools is true. Speech, music, and video use the REST endpoints above. Tested on 2026-10-03 with ai 7.0.127 and @ai-sdk/openai-compatible 3.0.62, and with ai 6.0.300 and @ai-sdk/openai-compatible 2.0.81.

Integrations

Use it in Dify

GenMagic is a plugin in the Dify Marketplace, so the workflows and agents you build in Dify can generate with it too. Install the plugin, paste your API key into its settings, and you get six tools: Generate image, Generate video and Check video, Generate speech, Generate music, and Generate text. Each tool lists the live models with their prices (or lets GenMagic pick one) and returns the generated file to the workflow.

The plugin is free; generations draw on the same credit balance as every other call. Its source is on GitHub.

Integrations

Use it in n8n

GenMagic is a verified community node for n8n, so it installs from the nodes panel on n8n Cloud and on self-hosted n8n alike: open the nodes panel, search for GenMagic, select it under More from the community, and select Install. An owner or admin installs it once for everyone on the instance (on n8n Cloud, verified community nodes can be turned on or off in the Cloud Admin Panel).

On a self-hosted n8n you can also install it by its npm package, n8n-nodes-genmagic: open Settings › Community Nodes, select Install, and enter the package name:

n8n-nodes-genmagic

Then add a GenMagic API credential with your key (n8n checks it by reading your balance, which costs nothing). One node covers Image (generate, or edit a reference image, up to 4 per run), Video (generate, waiting for the render or returning the job id, and get), Audio (speech and music), Text, Model (the live catalog), and Account (your balance). Each model dropdown lists the live catalog with prices, or lets GenMagic pick. Generated files come back as binary data, ready for the nodes that upload, post, or email them, with the generation’s cost_usd and your remaining balance_usd. n8n’s AI Agent can use the node as a tool, too.

To start from something that already runs, import one of the ready-made n8n workflows: a faceless YouTube Short (script, scene images and voiceovers) or a UGC video ad from a product photo.

The node is free and MIT-licensed; generations draw on the same credit balance as every other call. Its source is on GitHub.

Use it in ComfyUI

The GenMagic node pack is listed on the Comfy Registry and puts every model in ComfyUI without a GPU or a model download: GenMagic Image (text-to-image, or transform a connected reference image), GenMagic Video (text-to-video, or animate a connected first frame, and a last frame on models that take one), GenMagic Speech, GenMagic Music, and GenMagic Text (any language model, with an optional image to read, handy for writing prompts for the other nodes). Images come out as IMAGE, clips as VIDEO and sound as AUDIO, so they flow into ComfyUI’s own save, preview and editing nodes. Each model dropdown reads the live catalog, newest first.

Install it from ComfyUI Manager: open Custom Nodes Manager, search for GenMagic, install it and restart ComfyUI. With comfy-cli it is one command:

comfy node install genmagic

Paste your key in Settings › GenMagic › API key, or set GENMAGIC_API_KEY before starting ComfyUI. The key stays in your ComfyUI settings and never goes into a workflow you share. ComfyUI reruns a node only when an input changes, so queueing the same workflow again does not bill again: change the node’s seed for a new take. Each node’s info output names the model that ran, the cost and your balance. The pack is free and MIT-licensed, with example workflows, on GitHub.

Integrations

Use it in Zapier

GenMagic is in Zapier's app directory: search for GenMagic when you add a step to a Zap, then connect it with your API key (Zapier checks the key by reading your balance, which costs nothing). Any Zap can then use five steps: Generate Image (a picture or a logo, optionally from a reference image), Generate Text (writing, code, an SVG graphic or a web page), Generate Speech, Start Video, and Find Video. Each model field lists the live catalog with prices, or leave it empty to use the default.

Zapier gives every step 30 seconds, so video takes two steps: Start Video returns a job ID right away, and Find Video, in a later step or Zap, returns the clip once it is finished. Image and speech steps return a hosted file URL and text steps the text, each with the call’s cost_usd; Find Video adds the clip’s cost when it completes. The integration is free; generations draw on the same credit balance as every other call.

Integrations

Use it in Make

GenMagic has a Make app with every model. It is published and waiting for Make’s app review; until Make approves it, you install it in your Make organization with this invite link, then create a GenMagic connection with your API key. Its modules are Generate an image, Generate text, Generate speech, Create a video, Get a video, Search models and the universal Make an API call. Each returns the API’s own response plus what the call cost and your balance. Scenario ideas are on the Make page.

Integrations

Try it in Postman

Every endpoint is ready to send in GenMagic’s public Postman workspace, imported from the OpenAPI spec. Fork the GenMagic API collection into your own workspace, set its Bearer token to your key, and send any request. GET /models answers without a key, so you can browse the live catalog and its prices first.

Let your users connect their GenMagic account

Building an app, a plugin, a bot or a platform whose users should generate with their own GenMagic account? Let them connect it: they sign in to GenMagic (or create a free account), choose Allow, and your app receives a key of its own for that person. Every generation is paid from their balance at the listed price, so you handle no billing and no model accounts, and they can revoke your app on their account page at any time. Kit, Framer, Discord, Claude and ChatGPT connect to GenMagic this way.

It is standard OAuth (authorization code, RFC 6749). 1. Register your app once with POST /api/oauth/register and your client_name and redirect_uris. A server-side app asks for token_endpoint_auth_method: client_secret_post and gets a client secret and refresh tokens; an app without a server sends none and uses PKCE. 2. Send the person to /oauth/authorize with response_type=code, your client_id, redirect_uri and state. 3. Exchange the code at POST /api/oauth/token: the access_token is that person’s key for every /api/v1 call above. 4. When they disconnect, revoke it with POST /api/oauth/revoke. The full metadata is published at /.well-known/oauth-authorization-server.

curl https://genmagic.co/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Your App", "redirect_uris": ["https://yourapp.com/genmagic/callback"],
       "token_endpoint_auth_method": "client_secret_post"}'

Send X-GenMagic-Client: yourapp/1.0 on your calls so usage from your integration is counted as yours. Building one? Write to hello@genmagic.co: we help with testing, list working integrations on the integrations page, and creators who teach with GenMagic can earn through the creator program.

Billing

Credits: a call is a call

There is no separate API meter. Every generation, from the studio or from your code, costs the same: each model has its price, listed in GET /models and shown in the studio before you generate, and that price is deducted from your one credit balance. Top up or subscribe from your account, and the same balance powers both.

If a call would run your balance negative it is refused with HTTP 402 and an insufficient_quota error, exactly as an OpenAI SDK expects, so your retry and error handling work without changes.

Keep automations running with auto top-up. Turn it on from your balance in the studio and the balance refills from your saved card when it falls below a line you set. A call that needs more than your balance holds refills at that moment and then runs, instead of returning 402, so an n8n, Zapier or Make workflow never stops halfway. You choose the refill, the line and a monthly limit, every refill is emailed to you as a receipt, and on a plan refills add credit at your plan's rate.

See pricing

Errors

Every error uses the OpenAI envelope, so an OpenAI SDK parses it without changes: { "error": { "message", "type", "code", "param" } }. The status codes:

400  invalid_request_error   bad or missing parameter (e.g. no prompt, unknown model id)
401  authentication_error    missing, invalid, or revoked API key
402  insufficient_quota      balance would go negative; top up, or turn on auto top-up
404  invalid_request_error   model_not_found on GET /models/{id}
429  rate_limit_error        too many requests for this key; back off and retry
5xx  server_error            transient upstream/provider issue; retry with backoff

Lookup calls (/models, /usage) spend no credits, so they never return a 402: they only ever return 401 (bad key), 429 (rate limited), or, for a missing model, 404.

Rate limits. Each key allows up to 300 requests per minute (fixed window). Exceeding it returns 429 with a Retry-After header (seconds until the window resets) alongside X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Honor Retry-After and retry. This paces a leaked key; your credit balance is the real spend bound. Need a higher limit for a heavy workload? Ask us to raise it on your key.

Response headers. Every successful call reports its own metering, so an agent can pace itself and track spend without a second request. The rate-limit trio (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) is on every authenticated response, including lookups, and X-Credits-Remaining reports your balance after any non-streaming call that spent credits. Image, audio, video, and typed /text generations also carry X-Cost-Cents (what that call cost); a video reports its cost on the poll that completes it, and /text additionally returns its token counts in the response usage object. Chat completions instead price the OpenAI way with no X-Cost-Cents: the token counts are in the response usage object (in the terminal SSE frame when streaming, which is why a streamed call carries only the rate headers). A logo generation (and a branded svg or website from /text) also carries X-Brand-Fit (on_brand, wrong_palette, or monochrome), the compact form of the MCP brand_fit object above, present only when the output could be measured. Values are best-effort hints; GET /usage remains the authoritative balance.

Check your balance

GET /usage returns your key’s live credit balance and lifetime spend, so a program or agent can check its remaining budget before a big run and never be surprised by a 402. It reads the same balance every other call draws on.

curl https://genmagic.co/api/v1/usage \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "object": "usage", "currency": "usd",
#      "balance_cents": 3812.5, "balance_usd": 38.125,
#      "spent_cents": 2187.5, "spent_usd": 21.875, "generation_count": 148 }

On-brand

Personalization

Open Personalize your outputs in the app and connect your website or LinkedIn once. GenMagic learns your voice, audience, and colors. While personalization is on, every API generation is automatically shaped by that brand profile: your responses come out on-brand without changing a line of your code.

It is a single switch. Turn it off there and API calls run exactly as written, with no brand context added. Your prompts and system messages are always preserved; the brand context is prepended as a leading system message only while the switch is on.

Set up personalization

Help

Support

Write to hello@genmagic.co with the email of your GenMagic account, where you use it (the API, n8n, Zapier, Make, Discord, Canva or another app) and, for a generation that went wrong, the model, the time and the error message. We answer every message, usually within one working day.

Many answers are already on this page: what each error means is under Errors, your balance and spend under Check your balance, and every model with its current price on the models page. A generation that fails is not charged.