# API di design per sviluppatori: API e MCP di Gradiently

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

Una chiave, uno spazio di lavoro, otto permessi. Come cercare i Mark, impaginare design, creare altri formati e generare i file finiti dal tuo codice o da un assistente IA, con i limiti e gli errori che incontrerai.

## The short version

- Gradiently ha un’API di design in JSON all’indirizzo https://gradiently.design/api e un server MCP ospitato, entrambi costruiti sugli stessi endpoint.
- Ogni richiesta porta una chiave API dello spazio di lavoro, creata in Impostazioni › API e agenti da un proprietario o da un amministratore dello spazio.
- Una chiave funziona in un solo spazio di lavoro, agisce come la persona che l’ha creata e raggiunge solo gli endpoint consentiti dai suoi permessi.
- L’API può cercare nel Mercato, impaginare e modificare design sul Mark di un brand, salvare copie in altri formati e generare PNG o PDF dai design salvati.
- Una chiave non può mai gestire le chiavi, accedere alla fatturazione, cambiare l’account né cedere un Mark: per questo serve sempre una persona con l’accesso effettuato.

Gradiently è un’**API di design** oltre che uno strumento di design. Con una sola chiave limitata puoi cercare Mark, creare design che portano il Mark del tuo brand, cambiarne i testi, salvare copie in altri formati e generare il risultato in PNG o PDF, tutto in JSON via HTTPS. Le stesse funzioni sono offerte come server MCP ospitato: ChatGPT, Claude o qualsiasi assistente che supporti i server MCP remoti può lavorare da una semplice richiesta e restituirti un link che si apre nello Studio.

Questa pagina è la panoramica per sviluppatori: a cosa serve l’API, come funzionano chiavi e permessi, una prima richiesta e i limiti da tenere in conto. Il riferimento completo è su [/developers](https://gradiently.design/it/developers).

## Cosa può fare l’API di Gradiently

L’API è la stessa che usa l’app di Gradiently, quindi una chiave vede gli stessi dati e supera gli stessi controlli di chi l’ha creata nel browser. I compiti utili si dividono in cinque gruppi.

- **Trovare uno stile.** Cerca nel Mercato pubblico per nome, parole di colore o codice e leggi la ricetta completa di qualsiasi Mark pubblico.
- **Creare design.** Descrivi contenuto e layout e lascia che il motore di impaginazione li disponga sul Mark del brand, rimixa uno dei template di Gradiently o invia un documento di design completo.
- **Modificare design.** Modifica per elemento, sostituisci i testi di elementi scelti, applica un altro Mark a un design e salva copie in altri formati.
- **Generare i file.** Trasforma un design salvato in PNG o PDF con il motore stesso dello Studio, oppure pubblica un link di visualizzazione.
- **Leggere lo spazio di lavoro.** Elenca brand, design, caricamenti e membri e leggi font, loghi e colori di un brand.

Usi tipici: un negozio che genera una scheda prodotto per ogni nuovo articolo, una redazione che trasforma ogni titolo in un’[immagine di anteprima del link](https://gradiently.design/it/guide/link-preview-image), o uno strumento interno che prepara i post della settimana da un calendario editoriale. Se i dati di partenza sono già in un foglio di calcolo, la [creazione in serie](https://gradiently.design/it/guide/bulk-create-from-spreadsheet) nello Studio può bastare, senza scrivere codice.

## API o server MCP

### Server MCP

- Per gli assistenti IA che supportano i server MCP remoti.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Gli strumenti cercano il tuo brand, salvano i design e restituiscono link allo Studio.
- Ideale quando vuoi chiedere il lavoro a parole semplici.

### API HTTP

- Per script, back end e automazioni.
- JSON via HTTPS sotto `https://gradiently.design/api`.
- Scegli tu il brand, invii il contenuto e gestisci ogni risposta.
- Ideale quando serve un risultato esatto e ripetibile.

Una chiamata a uno strumento fa le stesse richieste che farebbe il tuo codice, con la stessa chiave: conta quindi negli stessi limiti e fallisce con gli stessi messaggi. Se MCP è nuovo per te, [che cos’è MCP](https://gradiently.design/it/guide/what-is-mcp) lo spiega in parole semplici, e [collegare un assistente IA](https://gradiently.design/it/guide/connect-ai-assistant) guida la configurazione di ChatGPT e Claude.

## Chiavi API e permessi

Le chiavi si creano in **Impostazioni › API e agenti** e solo proprietari e amministratori di uno spazio di lavoro possono crearle. Una chiave si mostra una sola volta, inizia con `gr_live_`, non scade mai e non si può modificare: per cambiare ciò che può fare, creane una nuova e revoca la vecchia. Agisce come la persona che l’ha creata, nell’unico spazio di lavoro per cui è nata, e smette di funzionare se quella persona se ne va o perde il ruolo.

| Permesso | In Impostazioni | Cosa consente |
| --- | --- | --- |
| `designs:read` | Leggere i design | Brand, design, miniature, caricamenti e render |
| `designs:write` | Creare e modificare design | Creare, cambiare, duplicare ed eliminare design, caricare immagini, usare il Designer |
| `marks:read` | Cercare i Mark | Cercare nel Mercato e leggere i Mark |
| `marks:claim` | Riservare i Mark | Riservare un Mark disponibile per chi ha creato la chiave |
| `brand:generate` | Generare brand | Endpoint di generazione dei brand |
| `workspaces:read` | Leggere lo spazio di lavoro | Lo spazio di lavoro, i suoi membri e il registro delle attività |
| `personalities:write` | Modificare i brand | Creare, rinominare ed eliminare brand, cambiare il Mark di un brand |
| `members:write` | Invitare membri | Inviare inviti allo spazio di lavoro |

Gli otto permessi. Una nuova chiave parte con i cinque che servono alla maggior parte del lavoro; Riservare i Mark resta disattivato finché non lo scegli, perché riservare un Mark ti rende titolare di quel Mark.

> **Una chiave è una password** Tienila in una variabile d’ambiente o in un archivio di segreti, una chiave per strumento, con il minimo di permessi che basta. Non mettere mai una chiave in una pagina web, in un’app mobile o in un repository: Gradiently ne conserva solo un hash, quindi una chiave trapelata va revocata e sostituita.

## La tua prima richiesta

1. **Crea una chiave** Apri **Impostazioni › API e agenti**, scegli lo spazio di lavoro, dai alla chiave il nome del posto in cui girerà e copiala quando compare.
2. **Cerca nel Mercato** Una `GET` a `/api/marks` con `?q=` restituisce 24 Mark a pagina e un `nextCursor` per la successiva.
3. **Impagina un design** Invia i testi a `POST /api/agent/compose` con un formato predefinito e un layout. Ricevi l’id del design, un link allo Studio ed eventuali problemi da rivedere.
4. **Generalo** Chiama `POST /api/designs/:id/render` con larghezza, altezza e formato, e decodifica il file in base64 che restituisce.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Cercare nel Mercato richiede `marks:read`. I codici funzionano con o senza punti, in maiuscolo o minuscolo.

```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": [ … ] }
```

Nell’API i brand si chiamano personalities. I layout includono statement, editorial, poster, split, stat, quote, list, event e minimal.

Un post verticale di Instagram con la scritta Pane fresco dalle 7 e una piccola riga Vieni a trovarci, su uno sfondo sfumato vivo

Cosa produce quella richiesta: le parole disposte dal motore di impaginazione sul Mark del brand, nel formato verticale di Instagram 1080×1350.

Poiché il design sta su un Mark, la leggibilità è gestita per te: la zona più calma del Mark si sposta dietro le parole e l’inchiostro automatico sceglie testo chiaro o scuro riga per riga. Per pubblicare lo stesso post come storia e come post su X, lo strumento MCP `resize_copies` salva copie in un massimo di otto formati in un colpo solo, riadattate come fa lo Studio. [Copia nei formati](https://gradiently.design/it/guide/copy-to-sizes) spiega il riadattamento.

```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 }
```

Larghezza e altezza vanno da 1 a 4096. Il render richiede la stessa licenza di esportazione del Mark del design che serve nello Studio; senza, la risposta è 402.

## Crediti, limiti ed errori

Quando il tuo assistente impagina un design con gli strumenti di disegno e modifica, non si spende alcun credito IA di Gradiently. Chiedere al Designer di Gradiently, tramite `/api/agent`, `/api/batches` o lo strumento `design`, consuma i crediti dello spazio di lavoro esattamente come nello Studio. [I crediti IA spiegati](https://gradiently.design/it/guide/ai-credits-explained) tratta l’assegnazione.

| Limite | Quota |
| --- | --- |
| Ogni richiesta con una chiave | 120 al minuto per chiave |
| Scritture (POST, PATCH, DELETE) | 90 al minuto per account, condivise con l’app |
| Render | 10 al minuto per account |
| Nuovi design e duplicati | 60 al minuto per account |
| Caricamenti | 60 al minuto per account |

Finestre mobili di un minuto. Superare il limite restituisce 429 con un’intestazione `Retry-After` in secondi: aspetta quel tempo, non riprovare subito.

Gli errori tornano come codice di stato con un messaggio `error` leggibile. I più frequenti: 401 per una chiave mancante o revocata, 403 per un permesso mancante, 402 quando servono una licenza di esportazione o crediti, 409 quando un design è cambiato dopo la tua lettura e 422 quando un campo non supera la validazione. Invia `baseUpdatedAt` con un `PATCH` per ricevere quel 409 invece di sovrascrivere la modifica di un collega.

## Cosa non può mai fare una chiave

Alcune azioni richiedono sempre una persona con l’accesso a Gradiently, qualunque siano i permessi. Una chiave non può creare né revocare chiavi, cambiare l’account, accedere alla fatturazione o pagare qualcosa, cedere, elencare o rilasciare un Mark, cambiare i ruoli dei membri o raggiungere uno spazio di lavoro diverso dal proprio. Una riserva che richiede un pagamento si ferma e chiede il checkout in Gradiently. Questi limiti sono voluti: un’automazione può creare e generare lavoro, ma proprietà e denaro restano alle persone. I ruoli sono trattati in [ruoli nello spazio di lavoro](https://gradiently.design/it/guide/workspace-roles).

## FAQ

### Gradiently ha un’API?

Sì. Ha un’API JSON all’indirizzo `https://gradiently.design/api` e un server MCP ospitato, entrambi usati con una chiave API dello spazio di lavoro o, per ChatGPT e Claude, con l’accesso OAuth.

### Chi può creare una chiave API di Gradiently?

Proprietari e amministratori di uno spazio di lavoro, in Impostazioni › API e agenti. La chiave si mostra una volta e funziona solo in quello spazio.

### Posso generare un PNG da un design con l’API?

Sì. `POST /api/designs/:id/render` restituisce un PNG o un PDF in base64, fino a 4096 pixel per lato, purché tu abbia la licenza di esportazione del Mark del design.

### L’uso dell’API consuma crediti IA?

Impaginare, modificare e generare design non ne consuma. Chiedere al Designer di Gradiently tramite l’API o lo strumento `design` consuma i crediti IA dello spazio di lavoro.

### Quali sono i limiti di frequenza dell’API?

120 richieste al minuto per chiave, con limiti più bassi per scritture, render e caricamenti. Oltre il limite ricevi un 429 con un’intestazione `Retry-After`.