L’API è la stessa che usa l’app di Gradiently, quindi una chiave vede gli stessi dati e supera gli stessi controlli che supererebbe chi l’ha creata nell’app, limitata a un solo spazio di lavoro e ai suoi permessi. Una chiave che chiama un endpoint non coperto da nessuno dei suoi permessi riceve un 403.
URL di base e autenticazione
Tutti i percorsi qui sotto si trovano sotto https://. Invia la tua chiave come token bearer con ogni richiesta. I corpi sono JSON con Content-Type: application/, tranne i caricamenti.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Una chiave è sempre legata allo spazio di lavoro in cui è stata creata. Non devi indicare lo spazio di lavoro; se invii
X-Workspaceo?workspace=, deve essere quello della chiave, altrimenti la richiesta fallisce con 403. - I corpi delle richieste vengono controllati in modo rigoroso: un campo che l’endpoint non conosce fallisce con 422.
- Le risposte sono JSON salvo dove indicato (immagini, reindirizzamenti e il flusso del Designer). I messaggi di errore per le chiavi API sono in inglese.
- Una chiave agisce come chi l’ha creata. I design e i brand che crea appartengono allo spazio di lavoro; i Mark che riserva appartengono a chi l’ha creata.
Spazio di lavoro
/ api/ mePermesso
workspaces:read e designs:readCosa fa
/ api/ workspacesPermesso
workspaces:readCosa fa
/ api/ workspaces/ :idPermesso
workspaces:readCosa fa
/ api/ workspaces/ :id/ membersPermesso
workspaces:readCosa fa
/ api/ workspaces/ :id/ auditPermesso
workspaces:readCosa fa
/ api/ workspaces/ :id/ invitesPermesso
members:writeCosa fa
GET /api/me
{
"viewer": { "id": "…", "name": "Ada Moss", "handle": "ada", "workspaceId": "…" },
"workspaces": [{ "id": "…", "name": "Hearth", "role": "owner" }],
"activeWorkspaceId": "…",
"personalities": [{ "id": "…", "slug": "hearth", "name": "Hearth", "markId": "…" }]
}POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }
{ "id": "…", "expiresInDays": 7 }role è admin, editor o viewer. La persona deve verificare lo stesso indirizzo email prima di accettare.Brand
/ api/ personalitiesPermesso
designs:readCosa fa
{ items }./ api/ personalitiesPermesso
personalities:writeCosa fa
/ api/ personalities/ :idPermesso
personalities:writeCosa fa
/ api/ personalities/ :idPermesso
personalities:writeCosa fa
/ api/ personalities/ :id/ designsPermesso
designs:readCosa fa
/ api/ personalities/ :id/ brandPermesso
designs:readCosa fa
POST /api/personalities
{ "name": "Hearth Bakery", "markId": "…" }
PATCH /api/personalities/:id
{ "profile": { "about": "A neighbourhood bakery", "voice": "warm, plain" } }
{ "id": "…", "slug": "hearth-bakery", "name": "Hearth Bakery", "markId": "…", "profile": { … } }markId alla creazione è facoltativo. Un profilo può contenere anche audience, uses, keywords, dos, donts, website, handle e fonts.L’elenco dei design accetta ?q= per cercare nei titoli e ?mark= per filtrare per Mark. Ogni elemento ha id, personalityId, markId, title, form, thumb, shared e updatedAt, senza il documento.
Design
/ api/ agent/ composePermesso
designs:writeCosa fa
/ api/ designsPermesso
designs:writeCosa fa
/ api/ designs/ :idPermesso
designs:readCosa fa
/ api/ designs/ :idPermesso
designs:writeCosa fa
/ api/ designs/ :idPermesso
designs:writeCosa fa
/ api/ designs/ :id/ duplicatePermesso
designs:writeCosa fa
/ api/ designs/ :id/ thumbPermesso
designs:readCosa fa
/ api/ designs/ :id/ renderPermesso
designs:readCosa fa
Il modo più semplice per creare un design da codice è POST /: descrivi il contenuto e il motore di impaginazione lo posiziona con il Mark del brand. Lo stesso endpoint rielabora un modello (template con text, photos, icons, hide) oppure, con designId e ops, modifica un design salvato.
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": [ … ] }issues elenca cosa ha trovato la verifica (margini, sovrapposizioni, gerarchia, contrasto).POST /api/designs
{
"personalityId": "…",
"form": "blank",
"title": "Launch post",
"doc": { "ratio": "custom", "width": 1080, "height": 1350, "shift": [0.5, 0.5, 0.5, 0.5], "elements": [] }
}
{ "id": "…", "personalityId": "…", "markId": null, "title": "Launch post", "form": "blank", "doc": { … }, "updatedAt": "…", "thumb": null, "shared": false }markId è facoltativo; senza, il design usa il Mark del brand. Leggi un design da GET / api/ designs/ :id per vedere un documento completo.PATCH / accetta uno qualsiasi tra title, doc, markId e shared. Impostare shared a true pubblica un link di visualizzazione su /. Invia baseUpdatedAt, l’ultimo updatedAt che hai letto, per far rifiutare il salvataggio con 409 se qualcuno ha cambiato il design nel frattempo.
POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }
{ "id": "…", "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }page parte da 0; un PDF senza page contiene tutte le pagine, ciascuna al suo formato nello Studio, a cui la richiesta deve corrispondere. Prevedi fino a tre minuti.La generazione richiede la stessa licenza di esportazione per il Mark del design richiesta dallo Studio; senza, la risposta è 402. La generazione non pubblica mai il design né archivia un file.
Caricamenti
/ api/ uploadsPermesso
designs:writeCosa fa
/ api/ uploadsPermesso
designs:readCosa fa
/ api/ uploads/ :idPermesso
designs:readCosa fa
?w= chiede una larghezza./ api/ uploads/ :idPermesso
designs:writeCosa fa
curl https://gradiently.design/api/uploads \
-H "Authorization: Bearer $GRADIENTLY_API_KEY" \
-F "file=@shopfront.jpg;type=image/jpeg"
# { "id": "…", "url": "/api/uploads/…" }file: PNG, JPEG, WebP, GIF o AVIF, al massimo 8 MB, con un tipo che corrisponde al contenuto. Usa l’url restituito come src di un’immagine o come foto di un modello.Video, audio e sottotitoli
Carica video e audio nel campo multipart file di POST /. I limiti sono 100 MB per i video, 25 MB per l’audio e un’ora per sorgente. La risposta include l’url privata e la duration verificata. GET / elenca i contenuti multimediali dello spazio di lavoro; GET / verifica i metadati reali. La lettura richiede designs:read; il caricamento e l’eliminazione richiedono designs:write.
Mark
/ api/ marksPermesso
marks:readCosa fa
/ api/ marks/ :codePermesso
marks:readCosa fa
/ api/ marks/ minePermesso
marks:readCosa fa
/ api/ agent/ markPermesso
marks:readCosa fa
/ api/ marksPermesso
brand:generateCosa fa
/ api/ marks/ :idPermesso
brand:generateCosa fa
/ api/ marks/ :code/ claimPermesso
marks:claimCosa fa
/ api/ marks/ :code/ buyPermesso
marks:claimCosa fa
GET / accetta q (nome o codice), tone (dark o light), material, status (listed, house o sale) e cursor. Risponde { "items": [ … ], "nextCursor": "…" } con 24 Mark per pagina. Un Mark ha id, code, name, recipe, status, creator, holder e createdAt.
Una riserva viene fatta per chi ha creato la chiave, mai per lo spazio di lavoro. Le riserve gratuite, e quelle coperte da un credito di riserva, si completano subito. Una riserva che richiede un pagamento risponde 402 con checkout: true, e buy risponde 409 con checkout: true; completale in Gradiently, perché una chiave non può pagare. buy accetta { "priceCents": … }, il prezzo di vendita che hai visto, e fallisce con 409 se è cambiato.
Il Designer
/ api/ agentPermesso
designs:writeCosa fa
/ api/ batchesPermesso
designs:writeCosa fa
/ api/ batchesPermesso
designs:readCosa fa
/ api/ batches/ :idPermesso
designs:readCosa fa
/ api/ batches/ :idPermesso
designs:writeCosa fa
/ api/ agent/ runs?designId=Permesso
designs:readCosa fa
/ api/ agent/ runs/ :idPermesso
designs:writeCosa fa
POST /api/batches
{
"personalityId": "…",
"see": false,
"plan": {
"brief": "Autumn menu launch, Saturday 4 October",
"items": [
{ "size": "ig-post", "brief": "The announcement" },
{ "size": "ig-story", "brief": "Three new loaves, one line each" }
]
}
}
{ "id": "…", "state": "running", "items": [{ "index": 0, "title": "…", "state": "…" }] }GET / api/ batches/ :id; ogni elemento riceve un designId e un url una volta salvato. state termina come done, stopped o failed.Il Designer consuma i crediti IA dello spazio di lavoro. Quando il saldo è inferiore a quanto richiede un turno, / e / rispondono 402 con code: "credits". Al massimo due serie per persona vengono eseguite insieme. Lo strumento design in MCP e assistenti IA legge il flusso del Designer e salva il risultato per te, il che è più semplice che gestire il flusso da solo.
Errori
Un errore risponde con un codice di stato e un corpo JSON con un messaggio error leggibile. Alcuni aggiungono campi, indicati qui sotto. L’unica eccezione è /: un corpo che non è JSON valido risponde 400 con un oggetto di errore JSON-RPC al suo posto, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Quando
Quando
checkout: true), nessuna licenza di esportazione, o crediti IA insufficienti (code: "credits").Quando
Quando
Quando
Quando
Quando
Retry-After e riprova.Quando
Retry-After.Quando
Limiti di frequenza
I limiti si contano su una finestra mobile di un minuto, salvo dove indicato. Superarli dà una risposta 429 con un header Retry-After in secondi e un campo retryAfter nel corpo. Rallenta e riprova dopo quel tempo; non riprovare subito.
Quota
Quota
Quota
Quota
Quota
Quota
Quota
Le esportazioni e il Designer hanno anche una capacità condivisa. Quando è piena la risposta è 503 o 429 con Retry-After, anche se sei entro i tuoi limiti. Tramite MCP, una chiamata a uno strumento conta una volta per la richiesta MCP e una volta per ogni richiesta API fatta dallo strumento.
Paginazione
Gli elenchi restituiscono una pagina alla volta. Chiedi la pagina successiva con ?cursor=.
- Ricerca nel Mercato (
/): 24 per pagina. Passa ilapi/ marks nextCursordella risposta; è null nell’ultima pagina. - Versioni dei Mark: passa il valore
nextdella risposta; è null nell’ultima pagina. - Design di un brand: 100 per pagina, dal più recente. Passa l’
iddell’ultimo design ricevuto. - Caricamenti: 60 per pagina, dal più recente. Passa l’
iddell’ultimo caricamento. - Brand, spazi di lavoro, membri e registro attività: 100 per pagina. Passa l’
iddell’ultimo elemento (userIdper i membri). I brand sono elencati da/comeapi/ personalities { items }.
Chiavi, permessi e rotazione sono in Chiavi API e permessi. Se un endpoint che ti serve non è qui, diccelo.