API de design para desenvolvedores: a API e o servidor MCP

O Gradiently é uma API de design, além de uma ferramenta de design. Com uma chave com escopos você pode buscar Marks, criar designs que usam o Mark da sua marca, mudar o texto deles, salvar cópias em outros tamanhos e renderizar o resultado em PNG ou PDF, tudo em JSON via HTTPS. Os mesmos recursos estão disponíveis num servidor MCP hospedado, então o ChatGPT, o Claude ou qualquer assistente que aceite servidores MCP remotos pode fazer o trabalho a partir de um pedido simples e devolver um link que abre no Studio.

Esta página é a visão geral para desenvolvedores: para que serve a API, como funcionam chaves e escopos, uma primeira requisição e os limites que vale considerar no projeto. A referência completa está em /developers.

O que a API do Gradiently pode fazer

A API é a mesma que o próprio app do Gradiently usa, então uma chave vê os mesmos dados e passa pelas mesmas verificações que quem a criou passaria no navegador. As tarefas úteis se dividem em cinco grupos.

• Encontrar um visual. Busque no Mercado público por nome, palavras de cor ou código, e leia a receita completa de qualquer Mark público.
• Criar designs. Descreva o conteúdo e um layout e deixe o motor de layout posicioná-lo no Mark da marca, remixe um dos templates do Gradiently ou envie um documento de design completo.
• Alterar designs. Edite por elemento, troque o texto de elementos escolhidos, coloque outro Mark num design e salve cópias em outros tamanhos.
• Renderizar. Transforme um design salvo em PNG ou PDF com o próprio motor do Studio, ou publique um link de visualização.
• Ler o espaço de trabalho. Liste marcas, seus designs, uploads e membros, e leia as fontes, logos e cores de uma marca.

Usos típicos: uma loja que renderiza um card de produto para cada item novo, uma redação que transforma cada manchete numa imagem de pré-visualização de link, ou uma ferramenta interna que monta os posts da semana a partir de um calendário de conteúdo. Se os seus dados já estão numa planilha, a criação em massa no Studio pode resolver sem nenhum código.

API ou servidor MCP

Uma chamada de ferramenta faz as mesmas requisições que o seu código faria, com a mesma chave, então conta nos mesmos limites e falha com as mesmas mensagens. Se MCP é novidade para você, o que é MCP explica em palavras simples, e conectar um assistente de IA mostra a configuração no ChatGPT e no Claude.

Chaves de API e escopos

As chaves são criadas em Configurações › API e agentes, e só proprietários e administradores de um espaço de trabalho podem criá-las. A chave aparece uma única vez, começa com gr_live_, nunca expira e não pode ser editada: para mudar o que ela pode fazer, crie uma nova e revogue a antiga. Ela age como a pessoa que a criou, dentro do único espaço de trabalho para o qual foi feita, e para de funcionar se essa pessoa sair ou perder o cargo.

Sua primeira requisição

1. 1

   Crie uma chave

   Abra Configurações › API e agentes, escolha o espaço de trabalho, dê à chave o nome de onde ela vai rodar e copie-a quando aparecer.

2. 2

   Busque no Mercado

   Um GET para /api/marks com ?q= devolve 24 Marks por página e um nextCursor para a próxima.

3. 3

   Monte um design

   Envie o texto para POST /api/agent/compose com um tamanho predefinido e um layout. Você recebe o id do design, um link do Studio e eventuais problemas de revisão.

4. 4

   Renderize

   Chame POST /api/designs/:id/render com largura, altura e formato, e decodifique o arquivo em base64 que ele devolve.

export GRADIENTLY_API_KEY="gr_live_…"

curl "https://gradiently.design/api/marks?q=deep%20teal" \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"

POST /api/agent/compose
{
  "personalityId": "…",
  "composition": {
    "size": "ig-post",
    "layout": "statement",
    "blocks": [
      { "role": "headline", "text": "Fresh bread from 7am" },
      { "role": "cta", "text": "Visit us" }
    ]
  }
}

{ "id": "…", "url": "/studio/…", "issues": [], "elements": [ … ] }

Como o design fica sobre um Mark, a legibilidade é resolvida para você: a região mais calma do Mark vai para trás do texto e a Tinta automática escolhe letras claras ou escuras por linha. Para publicar o mesmo post como story e como post no X, a ferramenta MCP resize_copies salva cópias em até oito tamanhos de uma vez, remontadas como o Studio faz. Copiar para tamanhos explica a remontagem.

POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }

{ "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }

Créditos, limites e erros

Quando o seu próprio assistente monta um design pelas ferramentas de desenho e edição, nenhum crédito de IA do Gradiently é gasto. Pedir ao Designer do próprio Gradiently, via /api/agent, /api/batches ou a ferramenta design, gasta os créditos do espaço de trabalho exatamente como no Studio. Créditos de IA explicados detalha a cota.

Os erros voltam como um código de status com uma mensagem error legível. Os que você mais vai ver: 401 para chave ausente ou revogada, 403 para escopo ausente, 402 quando é preciso uma licença de exportação ou créditos, 409 quando um design mudou desde a sua leitura, e 422 quando um campo não passa na validação. Envie baseUpdatedAt com um PATCH para receber esse 409 em vez de sobrescrever a edição de um colega.

O que uma chave nunca pode fazer

Algumas ações sempre exigem uma pessoa conectada ao Gradiently, sejam quais forem os escopos. Uma chave não pode criar nem revogar chaves, alterar a conta, acessar a cobrança ou pagar nada, transferir, anunciar ou liberar um Mark, mudar os papéis dos membros ou acessar qualquer espaço de trabalho além do seu. Uma reserva que exige pagamento para e pede o checkout no Gradiently. Esses limites são intencionais: uma automação pode criar e renderizar trabalho, mas a posse e o dinheiro ficam com as pessoas. Os papéis estão em papéis no espaço de trabalho.