GenMagic

Servidor MCP hospedado para mais de 450 modelos de IA: gere imagens, vídeo, fala, música e texto com uma única chave de API e um saldo pré-pago. Escolha qualquer modelo por id (list_models mostra ids e preços) ou deixe o GenMagic escolher; o vídeo é cobrado apenas quando é concluído.

Ver em genmagic.coExperimente este MCPPatrocinado

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

A API GenMagic

Endpoints compatíveis com OpenAI para todos os modelos de texto e visão, para geração de imagens, para fala e música, e para vídeo, uma chamada texto tipada para artefatos alinhados à marca, além de um servidor MCP para agentes. Aponte qualquer SDK OpenAI para sua URL base, insira uma chave e publique. Uma chamada do seu código custa exatamente o que uma chamada do estúdio custa: o mesmo saldo de créditos, pelo mesmo preço. Toda modalidade que o estúdio oferece, seu código também oferece.

URL base e autenticação

A API é servida a partir do seu domínio GenMagic sob /api/v1. Autentique com uma chave secreta no cabeçalho Authorization. Crie chaves nas configurações da sua conta; uma chave é exibida apenas uma vez, então guarde-a em um local seguro.

https://genmagic.co/api/v1

Authorization: Bearer gm_live_...

Mantenha as chaves no lado do servidor. Nunca incorpore uma chave em um pacote de navegador ou aplicativo móvel: qualquer pessoa que a ler pode gastar seus créditos.

Sua primeira chamada

POST /chat/completions é a chamada principal. Ela é compatível com OpenAI, então os SDKs oficiais da OpenAI funcionam sem alterações: basta definir a URL base e sua chave GenMagic.

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

Defina "stream": true para receber tokens como eventos enviados pelo servidor, no mesmo formato de chunks que a OpenAI usa. O uso é medido pela contagem autoritativa de tokens do provedor quando o stream termina.

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." }]
  }'

Raciocínio, parâmetros e cache

/chat/completions encaminha o corpo da sua solicitação ao modelo sem alterações, então todo parâmetro que o modelo suporta funciona como enviado: temperature, tools, response_format, seed e demais. Cada modelo lista aqueles que honra em supported_parameters em GET /models.

Modelos de raciocínio aceitam reasoning_effort, ou a forma de objeto reasoning: { effort, enabled, max_tokens }. Os valores de esforço que um modelo aceita estão em seu capabilities.reasoning_efforts; quando capabilities.reasoning_mandatory é verdadeiro, o pensamento não pode ser desativado e "enabled": false é recusado com um erro 400. Tokens de raciocínio são relatados em 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?" }]
  }'

Cada chamada cobra o custo de uso do próprio provedor do modelo, então entrada em cache e prompts longos custam o que o modelo cobra por eles: tokens de entrada em cache a pricing.cache_read_usd_per_million (gravações de cache a cache_write_usd_per_million) onde um modelo os publica, e um prompt que atinge o min_prompt_tokens de uma faixa em pricing.tiers aos preços dessa faixa.

Gerar

Texto tipado e alinhado à marca

POST /text retorna um ARTEFATO de texto específico, direcionado à marca da mesma forma que o estúdio faz: passe um type e receba o resultado finalizado. Com a personalização de marca ativada, um svg e um website saem na sua paleta e tipografia exatas, e writing e code carregam sua voz. Esta é a diferença em relação a /chat/completions: esse endpoint é a chamada bruta de modelo compatível com OpenAI (sua VOZ de marca é aplicada, mas não tem noção de tipo de artefato), enquanto /text adiciona o prompt de sistema do tipo e, para svg / website, a paleta visual e a tipografia. Um SVG é retornado com metadados de proveniência de conteúdo incorporados.

type é um de writing, code, svg ou website (omita para uma geração simples, com voz de marca). Cada tipo escolhe um modelo padrão sensato, ou defina model você mesmo a partir de /models. O opcional system adiciona uma orientação extra além da sua marca, e attachments permitem que o modelo leia uma imagem de referência, PDF ou documento.

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 (uma página de destino na sua marca)

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"])

A resposta é { created, model, type?, text, usage }. O custo e o saldo restante voltam nos cabeçalhos X-Cost-Cents e X-Credits-Remaining (veja Erros), igual a toda chamada medida. Um svg ou website gerado com personalização de marca ativada também retorna X-Brand-Fit (on_brand, wrong_palette ou monochrome): uma leitura das cores do artefato (os preenchimentos do vetor, ou o CSS da página), para que você possa regenerar um que saiu fora da sua paleta. É uma dica de melhor esforço, presente apenas quando a saída pôde ser medida em relação a uma cor de marca.

Imagens

POST /images/generations gera imagens, no formato de imagem da OpenAI, então client.images.generate(...) funciona sem alterações. Escolha qualquer modelo de imagem de /models (ou omita model para o padrão recomendado). Defina size (por exemplo, 1024x1024, 1792x1024) e response_format (url ou b64_json).

Imagem para imagem (referências). Passe um image (uma URL https ou uma URL data:image) para TRANSFORMAR essa imagem em vez de gerar do zero: envie um personagem ou produto e ele é mantido, não substituído. O modelo recebe a referência (uma inutilizável é rejeitada, nunca descartada silenciosamente). Adicione "type": "logo" para direcionar o resultado como uma marca. A referência chega ao modelo de forma idêntica ao estúdio.

curl https://genmagic.co/api/v1/images/generations \
  -H "Authorization: Bearer $GENMAGIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "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"
  }'

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-3.1-flash-image",
    prompt="A cobalt prism refracting into a spectrum, dark studio, 3D render",
    size="1024x1024",
)
print(img.data[0].url)

Fala e música

POST /audio/speech transforma texto em áudio falado, no formato de fala da OpenAI, então client.audio.speech.create(...) funciona sem alterações. POST /audio/music gera uma faixa musical original a partir de uma descrição. Ambos retornam os bytes brutos de áudio (o contêiner nativo do modelo, por exemplo, audio/mpeg); a URL hospedada durável volta no cabeçalho de resposta X-Media-Url.

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

Com a personalização de marca ativada, a música é ajustada automaticamente ao clima da marca. A fala é vocalizada literalmente, então nunca é alterada.

Gerar

Vídeo

O vídeo é assíncrono (um clipe leva de segundos a minutos), então é um fluxo de duas etapas baseado em polling. POST /videos inicia um trabalho e retorna seu id imediatamente; então faça polling de GET /videos/{id} até que status seja completed, momento em que você obtém um url durável. Nada é cobrado até o clipe ser concluído, e um trabalho finalizado é cobrado exatamente uma vez, não importa quantas vezes você faça polling.

Os clipes são feitos a partir do seu prompt, então escolha um modelo cujo capabilities.text_to_video seja true em GET /models?category=video (ou omita model para o padrão). Modelos que editam, aumentam a resolução ou animam mídia fornecida por você são listados com false e recusados com 400 model_not_supported.

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"
  }'
# -> { "id": "vid_...", "status": "queued", "status_url": "/api/v1/videos/vid_..." }

curl https://genmagic.co/api/v1/videos/vid_... \
  -H "Authorization: Bearer $GENMAGIC_API_KEY"
# -> { "status": "processing" }   ... keep polling ...
# -> { "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()

while True:
    s = requests.get(f"{base}/videos/{job['id']}", headers=headers).json()
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(3)

print(s.get("url") or s.get("error"))

Com a personalização de marca ativada, o clipe é direcionado à marca (paleta e estética) automaticamente, exatamente como uma imagem. Os status são queued, processing, completed e failed.

Listando modelos

GET /models retorna todos os modelos disponíveis no momento, no formato de lista da OpenAI, com os detalhes completos de cada modelo: nome, descrição, comprimento do contexto, modalidades de entrada/saída, capabilities (raciocínio, visão, ferramentas, saída estruturada, vozes), pricing na unidade real de cada modelo (um unit de token, imagem, minuto ou segundo, com usd_per_unit, e para vídeo a faixa por segundo mais toda resolução suportada e comprimento de clipe), e pontuações de benchmark quando publicadas. O catálogo é ao vivo: novos modelos aparecem no dia do lançamento, sem necessidade de atualização do SDK. Esta é uma consulta pura: não precisa de chave de API e gasta zero créditos. Uma solicitação que envia uma chave tem a chave verificada e contabilizada no limite de taxa por chave (veja Erros), então armazene em cache o catálogo e atualize-o periodicamente em vez de fazer polling em um loop apertado.

Filtre com ?category= (texto, imagem, áudio, vídeo), ?capability= (raciocínio, visão, ferramentas, estruturado) e ?search= (id ou nome). Recupere um modelo com GET /models/{id} (o id contém uma barra, por exemplo, /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"

A lista retorna { "object": "list", "data": [ ... ] }; cada entrada (e a resposta de recuperação) é um objeto de modelo. Modelos de texto carregam pricing por token (prompt_usd_per_million, completion_usd_per_million e, onde o modelo os publica, cache_read_usd_per_million, cache_write_usd_per_million, reasoning_usd_per_million e tiers de contexto longo), os parâmetros de solicitação que honram em supported_parameters e, para modelos de raciocínio, capabilities.reasoning_efforts e reasoning_mandatory (veja Raciocínio); imagem, áudio e vídeo carregam uma estimativa por geração. Todo modelo também carrega um único est_per_generation_usd comparável.

{
  "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": "generation",
    "image_output_usd_per_token": 0.00003,
    "est_per_generation_usd": 0.0387
  }
}

Seu agente, pela API

POST /agent/turn é a face de API do seu agente GenMagic: envie uma conversa e ele responde no personagem E retorna o conjunto de ativos a serem criados entre modalidades, alinhados à marca. Ele planeja, você cria. O planejamento não é cobrado; você então gera cada ativo retornado chamando o endpoint de sua modalidade (/chat/completions para texto, /images/generations para imagem, /audio/speech ou /audio/music para áudio, /videos para vídeo).

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." }
    ]
  }'

A resposta é { reply, assets: [{ modality, title, prompt, aspect_ratio?, voice? }] }. Alimente o prompt de cada ativo ao endpoint correspondente para gerá-lo.

Agentes

Use a partir de um agente (MCP)

GenMagic também é um servidor Model Context Protocol, então um agente de IA pode gerar através dele diretamente. Aponte qualquer cliente MCP (Claude Desktop, Cursor ou o seu próprio) para o endpoint abaixo com sua chave, e o agente recebe sete ferramentas: generate_text, generate_image, generate_speech, generate_music, para vídeo create_video + get_video (create retorna um id de trabalho, get_video faz polling até o clipe estar pronto) e list_models. Uma chamada de ferramenta é cobrada exatamente como qualquer outra chamada e sai alinhada à marca quando a personalização está ativada.

Qualquer modelo, por id. Toda ferramenta de geração aceita um model opcional: os mesmos ids da API REST e da biblioteca de modelos. O agente os encontra com list_models (filtre por category ou search), que não precisa de chave e retorna o preço de cada modelo, as vozes dos modelos de fala e as resoluções, comprimentos de clipe e suporte de som dos modelos de vídeo, além do padrão que cada ferramenta executa quando nenhum modelo é nomeado. create_video também aceita duration, resolution e generate_audio. Um id que uma ferramenta não executa é recusado com um ponteiro para list_models, nunca trocado por outro modelo, e todo resultado nomeia o modelo que executou.

https://genmagic.co/api/mcp

A maioria dos clientes aceita uma pequena configuração com a URL e um cabeçalho Authorization:

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

Por baixo dos panos, é JSON-RPC puro, então você pode chamá-lo com qualquer coisa:

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 (liste modelos de vídeo com seus preços e opções; nenhuma chave necessária)

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 (gere uma imagem com um modelo escolhido)

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 (inicie um vídeo e depois faça polling de 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>" }

Todo resultado de ferramenta autodescreve seu gasto. Um corpo JSON-RPC não tem cabeçalhos por chamada, então cada resultado de ferramenta carrega sua medição no campo MCP padrão _meta, sob a chave genmagic.ai/usage: cost_cents (quanto a chamada custou), credits_remaining (seu saldo após ela) e um objeto rate (limit, remaining, reset). É o espelho MCP dos cabeçalhos de resposta REST abaixo, então um agente se controla e acompanha o gasto a partir do resultado que já tem. Um envio de create_video e um polling de get_video ainda renderizando não cobram nada, então relatam apenas folga de taxa; o custo do clipe cai no polling que o conclui. Campos são omitidos, nunca falsificados, quando um valor é desconhecido. Chamadas visuais também reportam adequação à marca. Quando você gera uma logo, um svg com marca ou um website com marca e sua marca possui um conjunto de cores definido, o _meta do resultado carrega um objeto brand_fit: label é on_brand, wrong_palette (a saída veio em uma cor fora da marca, valendo regenerar) ou monochrome (intencionalmente sem cor, não é um problema), junto com uma fração presence e um sinalizador foreign_dominant_hue. Um agente pode ler isso e regenerar um artefato que saiu fora da marca, sem precisar de um humano no processo. Ele está presente apenas quando a saída pode realmente ser medida, portanto está simplesmente ausente em chamadas de prosa/código ou em um formato que não decodificamos.

Integrações

Use com o Vercel AI SDK

O GenMagic funciona com o Vercel AI SDK por meio do provedor compatível com OpenAI, então não há pacote GenMagic para instalar. Crie o provedor com sua URL base e chave de API, depois use generateText, streamText, chamada de ferramentas e generateImage com qualquer id de modelo do catálogo.

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);

Imagens passam por generateImage. O AI SDK lê imagens como base64, então peça b64_json com uma opção de provedor identificada pelo nome do provedor que você escolheu:

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

Os ids de modelo vêm de GET /models, que não exige chave (filtre com ?category=text ou ?category=image). A chamada de ferramentas funciona com modelos cujo capabilities.tools é verdadeiro. Fala, música e vídeo usam os endpoints REST acima. Testado em 03/10/2026 com ai 7.0.127 e @ai-sdk/openai-compatible 3.0.62, e com ai 6.0.300 e @ai-sdk/openai-compatible 2.0.81.

Integrações

Use no Dify

O GenMagic é um plugin no Dify Marketplace, então os fluxos de trabalho e agentes que você cria no Dify também podem gerar com ele. Instale o plugin, cole sua chave de API nas configurações e você terá seis ferramentas: Generate image, Generate video e Check video, Generate speech, Generate music e Generate text. Cada ferramenta lista os modelos ativos com seus preços (ou deixa o GenMagic escolher um) e retorna o arquivo gerado para o fluxo de trabalho.

O plugin é gratuito; as gerações usam o mesmo saldo de créditos de qualquer outra chamada. O código-fonte está no GitHub.

Use no n8n

O GenMagic é um nó comunitário para n8n, publicado no npm como n8n-nodes-genmagic. Em um n8n auto-hospedado, um proprietário ou administrador abre Configurações › Nós da Comunidade, seleciona Instalar e insere o nome do pacote:

n8n-nodes-genmagic

Depois adicione uma credencial GenMagic API com sua chave (o n8n a verifica lendo seu saldo, o que não custa nada). Um nó cobre Image (gerar ou editar uma imagem de referência, até 4 por execução), Video (gerar, aguardando a renderização ou retornando o id do job, e obter), Audio (fala e música), Text, Model (o catálogo ativo) e Account (seu saldo). Cada menu suspenso de modelo lista o catálogo ativo com preços, ou deixa o GenMagic escolher. Os arquivos gerados voltam como dados binários, prontos para os nós que fazem upload, publicam ou enviam por e-mail, com o cost_usd da geração e seu balance_usd restante. O Agente de IA do n8n também pode usar o nó como ferramenta.

O nó é gratuito e licenciado sob MIT; as gerações usam o mesmo saldo de créditos de qualquer outra chamada. O código-fonte está no GitHub.

Integrações

Use no Zapier

O GenMagic tem uma integração com o Zapier em beta. Até o Zapier listá-lo no diretório de aplicativos, você o adiciona à sua conta do Zapier com este link de convite e depois o conecta com sua chave de API (o Zapier verifica a chave lendo seu saldo, o que não custa nada). Qualquer Zap pode então usar cinco etapas: Generate Image (uma imagem ou um logotipo, opcionalmente a partir de uma imagem de referência), Generate Text (escrita, código, um gráfico SVG ou uma página web), Generate Speech, Start Video e Find Video. Cada campo de modelo lista o catálogo ativo com preços, ou deixe-o vazio para usar o padrão.

O Zapier dá a cada etapa 30 segundos, então vídeo leva duas etapas: Iniciar Vídeo retorna um id de job imediatamente, e Encontrar Vídeo, em uma etapa posterior ou Zap, retorna o clipe quando estiver pronto. Etapas de imagem e fala retornam uma URL de arquivo hospedado e etapas de texto retornam o texto, cada uma com o cost_usd da chamada; Encontrar Vídeo adiciona o custo do clipe quando ele é concluído. A integração é gratuita; as gerações usam o mesmo saldo de créditos de qualquer outra chamada.

Integrações

Experimente no Postman

Todos os endpoints estão prontos para envio no workspace público do Postman do GenMagic, importados da especificação OpenAPI. Faça um fork da coleção GenMagic API para seu próprio workspace, defina o token Bearer como sua chave e envie qualquer requisição. GET /models responde sem chave, então você pode navegar pelo catálogo ativo e seus preços primeiro.

Cobrança

Créditos: uma chamada é uma chamada

Não há medidor de API separado. Cada geração, do estúdio ou do seu código, é cobrada da mesma forma: o custo real do provedor é deduzido do seu único saldo de créditos. Recarregue ou assine pela sua conta, e o mesmo saldo alimenta ambos.

Se uma chamada deixaria seu saldo negativo, ela é recusada com HTTP 402 e um erro insufficient_quota, exatamente como um SDK OpenAI espera, então suas tentativas e tratamento de erros funcionam sem alterações.

Ver preços

Erros

Todo erro usa o envelope OpenAI, então um SDK OpenAI o analisa sem alterações: { "error": { "message", "type", "code", "param" } }. Os códigos de status:

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 to continue
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

Chamadas de consulta (/models, /usage) não gastam créditos, então nunca retornam um 402: elas só retornam 401 (chave inválida), 429 (limite de taxa) ou, para um modelo ausente, 404.

Limites de taxa. Cada chave permite até 300 requisições por minuto (janela fixa). Exceder isso retorna 429 com um cabeçalho Retry-After (segundos até a janela reiniciar) junto com X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Respeite Retry-After e tente novamente. Isso limita uma chave vazada; seu saldo de créditos é o limite real de gastos. Precisa de um limite maior para uma carga pesada? Peça para aumentarmos na sua chave.

Cabeçalhos de resposta. Toda chamada bem-sucedida reporta sua própria medição, então um agente pode se autolimitar e acompanhar gastos sem uma segunda requisição. O trio de limite de taxa (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) está em toda resposta autenticada, incluindo consultas, e X-Credits-Remaining reporta seu saldo após qualquer chamada não-streaming que gastou créditos. Gerações de imagem, áudio, vídeo e /text tipado também carregam X-Cost-Cents (quanto aquela chamada custou); um vídeo reporta seu custo na consulta que o conclui, e /text adicionalmente retorna suas contagens de tokens no objeto usage da resposta. Conclusões de chat, em vez disso, precificam do jeito OpenAI sem X-Cost-Cents: as contagens de tokens estão no objeto usage da resposta (no quadro SSE final ao fazer streaming, que é por isso que uma chamada em streaming carrega apenas os cabeçalhos de taxa). Uma geração logo (e um svg ou website com marca de /text) também carrega X-Brand-Fit (on_brand, wrong_palette ou monochrome), a forma compacta do objeto brand_fit do MCP acima, presente apenas quando a saída pôde ser medida. Os valores são dicas de melhor esforço; GET /usage continua sendo o saldo autoritativo.

Verifique seu saldo

GET /usage retorna o saldo de créditos ativo da sua chave e o gasto total, para que um programa ou agente possa verificar o orçamento restante antes de uma grande execução e nunca ser surpreendido por um 402. Ele lê o mesmo saldo que qualquer outra chamada usa.

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 }

Na marca

Personalização

Abra Personalize suas saídas no aplicativo e conecte seu site ou LinkedIn uma vez. O GenMagic aprende sua voz, público e cores. Enquanto a personalização estiver ativa, toda geração de API é automaticamente moldada por esse perfil de marca: suas respostas saem na marca sem mudar uma linha do seu código.

É um único interruptor. Desligue-o lá e as chamadas de API rodam exatamente como escritas, sem contexto de marca adicionado. Seus prompts e mensagens de sistema são sempre preservados; o contexto de marca é adicionado como uma mensagem de sistema inicial apenas enquanto o interruptor estiver ativo.