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

[Canonical HTML page](https://gradiently.design/pt-pt/guide/gradiently-for-developers)

Uma chave, um espaço de trabalho, oito âmbitos. Como pesquisar Marks, compor designs, criar outros tamanhos e gerar ficheiros finais a partir do teu código ou de um assistente de IA, com os limites e erros que vais encontrar.

## The short version

- O Gradiently tem uma API de design em JSON em https://gradiently.design/api e um servidor MCP alojado, ambos construídos sobre os mesmos endpoints.
- Cada pedido leva uma chave de API do espaço de trabalho, criada em Definições › API e agentes por um proprietário ou administrador do espaço.
- Uma chave funciona num único espaço de trabalho, age como a pessoa que a criou e só chega aos endpoints que os seus âmbitos permitem.
- A API pesquisa o Mercado, compõe e edita designs sobre o Mark de uma marca, guarda cópias noutros tamanhos e gera designs guardados em PNG ou PDF.
- Uma chave nunca pode gerir chaves, aceder à faturação, alterar a conta nem passar um Mark a outra pessoa; isso exige sempre uma pessoa com sessão iniciada.

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](https://gradiently.design/pt-pt/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](https://gradiently.design/pt-pt/guide/link-preview-image), 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](https://gradiently.design/pt-pt/guide/bulk-create-from-spreadsheet) no Studio pode resolver sem uma linha de código.

## API ou servidor MCP

### Servidor MCP

- Para assistentes de IA com suporte para servidores MCP remotos.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- As ferramentas consultam a tua marca, guardam designs e devolvem ligações do Studio.
- Ideal quando queres pedir trabalho por palavras simples.

### API HTTP

- Para scripts, back-ends e automatizações.
- JSON por HTTPS em `https://gradiently.design/api`.
- Escolhes a marca, envias o conteúdo e tratas cada resposta.
- Ideal quando precisas de resultados exatos e repetíveis.

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](https://gradiently.design/pt-pt/guide/what-is-mcp) explica-o em palavras simples, e [ligar um assistente de IA](https://gradiently.design/pt-pt/guide/connect-ai-assistant) 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.

| Âmbito | Nas Definições | O que permite |
| --- | --- | --- |
| `designs:read` | Ler designs | Marcas, designs, miniaturas, carregamentos e renderizações |
| `designs:write` | Criar e editar designs | Criar, alterar, duplicar e apagar designs, carregar imagens, usar o Designer |
| `marks:read` | Pesquisar Marks | Pesquisar o Mercado e ler Marks |
| `marks:claim` | Reservar Marks | Reservar um Mark disponível para o criador da chave |
| `brand:generate` | Gerar marcas | Endpoints de geração de marcas |
| `workspaces:read` | Ler o espaço de trabalho | O espaço de trabalho, os seus membros e o registo de auditoria |
| `personalities:write` | Editar marcas | Criar, mudar o nome e apagar marcas, mudar o Mark de uma marca |
| `members:write` | Convidar membros | Enviar convites para o espaço de trabalho |

Os oito âmbitos. Uma chave nova começa com os cinco de que a maioria do trabalho precisa; Reservar Marks fica desligado até o escolheres, porque uma reserva faz de ti o titular de um Mark.

> **Uma chave é uma palavra-passe** Guarda-a numa variável de ambiente ou num cofre de segredos, uma chave por ferramenta, com o mínimo de âmbitos que faz o trabalho. Nunca ponhas uma chave numa página web, numa aplicação móvel ou num repositório: o Gradiently guarda apenas um hash, por isso uma chave divulgada tem de ser revogada e substituída.

## O teu primeiro pedido

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. **Pesquisa o Mercado** Um `GET` a `/api/marks` com `?q=` devolve 24 Marks por página e um `nextCursor` para a seguinte.
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. **Gera-o** Chama `POST /api/designs/:id/render` com largura, altura e formato, e descodifica o ficheiro em base64 que devolve.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Pesquisar o Mercado exige `marks:read`. Os códigos funcionam com ou sem pontos, em qualquer caso.

```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 chamam-se personalities. As composições incluem statement, editorial, poster, split, stat, quote, list, event e minimal.

Uma publicação vertical de Instagram com a frase Pão fresco desde as 7h e uma pequena linha Visita-nos, sobre um fundo de gradiente vivo

O que esse pedido produz: as palavras colocadas pelo motor de composição no Mark da marca, no formato vertical do Instagram, 1080×1350.

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](https://gradiently.design/pt-pt/guide/copy-to-sizes) explica a reorganização.

```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. Gerar exige a mesma licença de exportação do Mark do design que o Studio; sem ela, a resposta é 402.

## 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](https://gradiently.design/pt-pt/guide/ai-credits-explained) cobre a quota.

| Limite | Quota |
| --- | --- |
| Todos os pedidos com uma chave | 120 por minuto por chave |
| Escritas (POST, PATCH, DELETE) | 90 por minuto por conta, partilhadas com a aplicação |
| Renderizações | 10 por minuto por conta |
| Novos designs e duplicados | 60 por minuto por conta |
| Carregamentos | 60 por minuto por conta |

Janelas deslizantes de um minuto. Ultrapassar responde 429 com um cabeçalho `Retry-After` em segundos: espera esse tempo, não voltes a tentar logo.

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](https://gradiently.design/pt-pt/guide/workspace-roles).

## FAQ

### O Gradiently tem uma API?

Sim. Tem uma API JSON em `https://gradiently.design/api` e um servidor MCP alojado, ambos usados com uma chave de API do espaço de trabalho ou, no ChatGPT e no Claude, com início de sessão OAuth.

### Quem pode criar uma chave de API do Gradiently?

Os proprietários e administradores de um espaço de trabalho, em Definições › API e agentes. A chave aparece uma vez e só funciona nesse espaço.

### Posso gerar um design em PNG com a API?

Sim. `POST /api/designs/:id/render` devolve um PNG ou PDF em base64, até 4096 píxeis por lado, desde que tenhas a licença de exportação do Mark do design.

### Usar a API gasta créditos de IA?

Compor, editar e gerar designs não gasta. Pedir ao Designer do Gradiently pela API ou pela ferramenta `design` gasta os créditos de IA do espaço de trabalho.

### Quais são os limites de pedidos da API?

120 pedidos por minuto por chave, com limites mais baixos para escritas, renderizações e carregamentos. Ao passar um limite recebes 429 com um cabeçalho `Retry-After`.