API de design para programadores: a API e o servidor MCP do Gradiently

O Gradiently é uma API de design além de uma ferramenta de design. Com uma só chave limitada podes pesquisar Marks, criar designs que vestem o Mark da tua marca, mudar-lhes as palavras, guardar cópias noutros tamanhos e gerar o resultado em PNG ou PDF, tudo em JSON por HTTPS. As mesmas capacidades estão disponíveis num servidor MCP alojado, para que o ChatGPT, o Claude ou qualquer assistente com suporte para servidores MCP remotos faça o trabalho a partir de um pedido simples e te entregue uma ligação que abre no Studio.

Esta página é a visão geral para programadores: para que serve a API, como funcionam as chaves e os âmbitos, um primeiro pedido e os limites que convém ter em conta. A referência completa está em /developers.

O que a API do Gradiently pode fazer

A API é a mesma que a própria aplicação Gradiently usa, por isso uma chave vê os mesmos dados e passa as mesmas verificações que o seu criador passaria no navegador. As tarefas úteis dividem-se em cinco grupos.

• Encontrar um visual. Pesquisa o Mercado público por nome, palavras de cor ou código, e lê a receita completa de qualquer Mark público.
• Criar designs. Descreve o conteúdo e uma composição e deixa o motor de composição colocá-lo no Mark da marca, remistura um dos modelos do Gradiently ou envia um documento de design completo.
• Alterar designs. Edita elemento a elemento, substitui as palavras de elementos de texto escolhidos, põe outro Mark num design e guarda cópias noutros tamanhos.
• Gerar. Transforma um design guardado em PNG ou PDF com o motor do próprio Studio, ou publica uma ligação de visualização.
• Ler o espaço de trabalho. Lista marcas, os seus designs, carregamentos e membros, e lê os tipos de letra, logótipos e cores de uma marca.

Usos típicos: uma loja que gera um cartão de produto para cada novo artigo, uma redação que transforma cada título numa imagem de pré-visualização de ligação, ou uma ferramenta interna que cria as publicações da semana a partir de um calendário de conteúdos. Se os teus dados já estão numa folha de cálculo, a criação em massa no Studio pode resolver sem uma linha de código.

API ou servidor MCP

Uma chamada de ferramenta faz os mesmos pedidos que o teu código, com a mesma chave, por isso conta para os mesmos limites e falha com as mesmas mensagens. Se o MCP é novidade para ti, o que é o MCP explica-o em palavras simples, e ligar um assistente de IA guia-te na configuração do ChatGPT e do Claude.

Chaves de API e âmbitos

As chaves criam-se em Definições › API e agentes, e só os proprietários e administradores de um espaço de trabalho as podem fazer. Uma chave aparece uma vez, começa por gr_live_, nunca expira e não se edita: para mudar o que pode fazer, cria uma nova e revoga a antiga. Age como a pessoa que a criou, dentro do único espaço de trabalho para que foi feita, e deixa de funcionar se essa pessoa sair ou for despromovida.

O teu primeiro pedido

1. 1

   Cria uma chave

   Abre Definições › API e agentes, escolhe o espaço de trabalho, dá à chave o nome do sítio onde vai correr e copia-a quando aparecer.

2. 2

   Pesquisa o Mercado

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

3. 3

   Compõe um design

   Envia o texto para POST /api/agent/compose com um tamanho predefinido e uma composição. Recebes o id do design, uma ligação do Studio e eventuais problemas a rever.

4. 4

   Gera-o

   Chama POST /api/designs/:id/render com largura, altura e formato, e descodifica o ficheiro em base64 que 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 está num Mark, a legibilidade fica tratada por ti: a zona mais calma do Mark passa para trás das palavras e a tinta automática escolhe tipo claro ou escuro em cada linha. Para publicar a mesma imagem como story e como publicação no X, a ferramenta MCP resize_copies guarda cópias em até oito tamanhos de uma vez, reorganizadas como o Studio faz. Copiar para tamanhos explica a reorganização.

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 teu próprio assistente compõe um design através das ferramentas de desenho e edição, não se gastam créditos de IA do Gradiently. Pedir ao Designer do Gradiently, através de /api/agent, /api/batches ou da ferramenta design, gasta os créditos do espaço de trabalho exatamente como no Studio. Os créditos de IA explicados cobre a quota.

Os erros chegam como código de estado com uma mensagem error legível. Os mais comuns: 401 para uma chave em falta ou revogada, 403 para um âmbito em falta, 402 quando é preciso uma licença de exportação ou créditos, 409 quando o design mudou desde que o leste, e 422 quando um campo falha a validação. Envia baseUpdatedAt num PATCH para receberes esse 409 em vez de apagares a edição de um colega.

O que uma chave nunca pode fazer

Certas ações exigem sempre uma pessoa com sessão iniciada no Gradiently, sejam quais forem os âmbitos. Uma chave não pode criar nem revogar chaves, alterar a conta, aceder à faturação ou pagar seja o que for, transferir, listar ou libertar um Mark, mudar as funções dos membros, nem chegar a outro espaço de trabalho além do seu. Uma reserva que exija pagamento pára e pede o pagamento no Gradiently. Estes limites são deliberados: uma automatização pode criar e gerar trabalho, mas a propriedade e o dinheiro ficam com as pessoas. As funções estão explicadas em funções no espaço de trabalho.