# API de design para desenvolvedores: a API e o servidor MCP [Canonical HTML page](https://gradiently.design/pt-br/guide/gradiently-for-developers) Uma chave, um espaço de trabalho, oito escopos. Como buscar Marks, montar designs, gerar outros tamanhos e renderizar arquivos prontos a partir do seu código ou de um assistente de IA, com os limites e erros que você vai encontrar pelo caminho. ## The short version - O Gradiently tem uma API de design em JSON em https://gradiently.design/api e um servidor MCP hospedado, e os dois são construídos sobre os mesmos endpoints. - Toda requisição leva uma chave de API do espaço de trabalho, criada em Configurações › API e agentes por um proprietário ou administrador do espaço. - Uma chave funciona em exatamente um espaço de trabalho, age como a pessoa que a criou e só alcança os endpoints que seus escopos permitem. - A API pode buscar no Mercado, montar e editar designs no Mark de uma marca, salvar cópias em outros tamanhos e renderizar designs salvos em PNG ou PDF. - Uma chave nunca pode gerenciar chaves, acessar a cobrança, alterar a conta ou dar um Mark; isso sempre exige uma pessoa conectada. 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](https://gradiently.design/pt-br/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](https://gradiently.design/pt-br/guide/link-preview-image), 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](https://gradiently.design/pt-br/guide/bulk-create-from-spreadsheet) no Studio pode resolver sem nenhum código. ## API ou servidor MCP ### Servidor MCP - Para assistentes de IA que aceitam servidores MCP remotos. - Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`. - As ferramentas consultam sua marca, salvam designs e devolvem links do Studio. - Melhor quando você quer pedir o trabalho em palavras simples. ### API HTTP - Para scripts, back ends e automações. - JSON via HTTPS em `https://gradiently.design/api`. - Você escolhe a marca, envia o conteúdo e trata cada resposta. - Melhor quando você precisa de um resultado exato e repetível. 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](https://gradiently.design/pt-br/guide/what-is-mcp) explica em palavras simples, e [conectar um assistente de IA](https://gradiently.design/pt-br/guide/connect-ai-assistant) 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. | Escopo | Em Configurações | O que permite | | --- | --- | --- | | `designs:read` | Ler designs | Marcas, designs, miniaturas, uploads e renderizações | | `designs:write` | Criar e editar designs | Criar, alterar, duplicar e excluir designs, enviar imagens, usar o Designer | | `marks:read` | Buscar Marks | Buscar no Mercado e ler Marks | | `marks:claim` | Reservar Marks | Reservar um Mark disponível para quem criou a chave | | `brand:generate` | Gerar marcas | Endpoints de geração de marca | | `workspaces:read` | Ler o espaço de trabalho | O espaço de trabalho, seus membros e o registro de auditoria | | `personalities:write` | Editar marcas | Criar, renomear e excluir marcas, trocar o Mark de uma marca | | `members:write` | Convidar membros | Enviar convites para o espaço de trabalho | Os oito escopos. Uma chave nova começa com os cinco de que a maior parte do trabalho precisa; Reservar Marks fica desligado até você escolher, porque uma reserva faz de você o dono de um Mark. > **Uma chave é uma senha** Guarde-a numa variável de ambiente ou num cofre de segredos, uma chave por ferramenta, com o mínimo de escopos que resolvam o trabalho. Nunca coloque uma chave numa página web, num app de celular ou num repositório: o Gradiently guarda só um hash, então uma chave vazada precisa ser revogada e substituída. ## Sua primeira requisição 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. **Busque no Mercado** Um `GET` para `/api/marks` com `?q=` devolve 24 Marks por página e um `nextCursor` para a próxima. 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. **Renderize** Chame `POST /api/designs/:id/render` com largura, altura e formato, e decodifique o arquivo em base64 que ele devolve. ```bash export GRADIENTLY_API_KEY="gr_live_…" curl "https://gradiently.design/api/marks?q=deep%20teal" \ -H "Authorization: Bearer $GRADIENTLY_API_KEY" ``` Buscar no Mercado exige `marks:read`. Os códigos funcionam com ou sem os pontos, em maiúsculas ou minúsculas. ```json 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": [ … ] } ``` Na API, as marcas se chamam personalities. Os layouts incluem statement, editorial, poster, split, stat, quote, list, event e minimal. Um post vertical do Instagram com o texto Pão fresquinho a partir das 7h e uma pequena linha Venha nos visitar, sobre um fundo vivo em gradiente O que essa requisição produz: o texto posicionado pelo motor de layout no Mark da marca, no tamanho vertical de 1080×1350 do Instagram. 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](https://gradiently.design/pt-br/guide/copy-to-sizes) explica a remontagem. ```json 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 } ``` Largura e altura vão de 1 a 4096. Renderizar exige a mesma licença de exportação do Mark do design que o Studio exige; sem ela a resposta é 402. ## 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](https://gradiently.design/pt-br/guide/ai-credits-explained) detalha a cota. | Limite | Cota | | --- | --- | | Toda requisição com chave | 120 por minuto por chave | | Escritas (POST, PATCH, DELETE) | 90 por minuto por conta, compartilhado com o app | | Renderizações | 10 por minuto por conta | | Novos designs e duplicações | 60 por minuto por conta | | Uploads | 60 por minuto por conta | Janelas móveis de um minuto. Ultrapassar responde 429 com um cabeçalho `Retry-After` em segundos: espere esse tempo, não tente de novo na hora. 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](https://gradiently.design/pt-br/guide/workspace-roles). ## FAQ ### O Gradiently tem API? Tem. Uma API em JSON em `https://gradiently.design/api` e um servidor MCP hospedado, os dois usados com uma chave de API do espaço de trabalho ou, no ChatGPT e no Claude, com login via OAuth. ### Quem pode criar uma chave de API do Gradiently? Proprietários e administradores de um espaço de trabalho, em Configurações › API e agentes. A chave aparece uma única vez e só funciona naquele espaço de trabalho. ### Posso renderizar um design em PNG com a API? Pode. `POST /api/designs/:id/render` devolve um PNG ou PDF em base64, com até 4096 pixels por lado, desde que você tenha a licença de exportação do Mark do design. ### Usar a API gasta créditos de IA? Montar, editar e renderizar designs não gasta. Pedir ao Designer do próprio Gradiently pela API ou pela ferramenta `design` gasta os créditos de IA do espaço de trabalho. ### Quais são os limites de requisição da API? 120 requisições por minuto por chave, com limites menores para escritas, renderizações e uploads. Acima do limite você recebe um 429 com um cabeçalho `Retry-After`.