API di design per sviluppatori: API e MCP di Gradiently

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.

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, 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 nello Studio può bastare, senza scrivere codice.

API o server MCP

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 lo spiega in parole semplici, e collegare un assistente IA 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.

La tua prima richiesta

1. 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. 2

   Cerca nel Mercato

   Una GET a /api/marks con ?q= restituisce 24 Mark a pagina e un nextCursor per la successiva.

3. 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. 4

   Generalo

   Chiama POST /api/designs/:id/render con larghezza, altezza e formato, e decodifica il file in base64 che restituisce.

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

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 spiega il riadattamento.

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 }

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 tratta l’assegnazione.

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.