Ett design-API för utvecklare: Gradiently API och MCP-server

Gradiently är ett design-API lika mycket som ett designverktyg. Med en enda nyckel med begränsad behörighet kan du söka efter Marks, skapa designer som bär ditt varumärkes Mark, ändra deras text, spara kopior i andra storlekar och rendera resultatet till PNG eller PDF, allt som JSON över HTTPS. Samma funktioner finns som en värdbaserad MCP-server, så att ChatGPT, Claude eller någon annan assistent som stöder fjärr-MCP kan göra jobbet utifrån en vanlig förfrågan och ge dig en länk som öppnas i Studion.

Den här sidan är utvecklarens översikt: vad API:t är till för, hur nycklar och behörigheter fungerar, ett första anrop och de gränser det lönar sig att designa efter. Den fullständiga referensen finns på /developers.

Det här kan Gradiently API göra

API:t är samma som Gradiently-appen själv använder, så en nyckel ser samma data och klarar samma kontroller som dess skapare skulle göra i webbläsaren. De användbara uppgifterna delas in i fem grupper.

• Hitta en look. Sök i den publika Marknaden på namn, färgord eller kod och läs hela receptet för en publik Mark.
• Skapa designer. Beskriv innehåll och layout och låt layoutmotorn placera det på varumärkets Mark, remixa en av Gradientlys mallar eller skicka ett helt designdokument.
• Ändra designer. Redigera per element, byt ut texten i valda textelement, lägg en annan Mark på en design och spara kopior i andra storlekar.
• Rendera. Gör om en sparad design till PNG eller PDF med Studions egen motor, eller publicera en visningslänk till den.
• Läs arbetsytan. Lista varumärken, deras designer, uppladdningar och medlemmar, och läs ett varumärkes typsnitt, logotyper och färger.

Typiska användningar: en butik som renderar ett produktkort för varje ny vara, en redaktion som gör varje rubrik till en förhandsbild för länkar, eller ett internt verktyg som gör veckans inlägg utifrån en innehållskalender. Om dina källdata redan finns i ett kalkylark kan massskapande i Studion klara jobbet helt utan kod.

API eller MCP-server

Ett verktygsanrop gör samma förfrågningar som din kod skulle göra, med samma nyckel, så det räknas mot samma gränser och misslyckas med samma meddelanden. Om MCP är nytt för dig förklarar vad är MCP det med enkla ord, och att ansluta en AI-assistent går igenom installationen för ChatGPT och Claude.

API-nycklar och behörigheter

Nycklar skapas under Inställningar › API och agenter, och bara ägare och admins i en arbetsyta kan göra det. En nyckel visas en enda gång, börjar med gr_live_, går aldrig ut och kan inte redigeras: vill du ändra vad den kan göra skapar du en ny och återkallar den gamla. Den agerar som den som skapade den, inom den enda arbetsyta den gjordes för, och slutar fungera om personen lämnar arbetsytan eller får lägre roll.

Ditt första anrop

1. 1

   Skapa en nyckel

   Öppna Inställningar › API och agenter, välj arbetsyta, döp nyckeln efter var den ska köras och kopiera den när den visas.

2. 2

   Sök i Marknaden

   Ett GET till /api/marks med ?q= ger 24 Marks per sida och en nextCursor till nästa.

3. 3

   Lägg ut en design

   Skicka texten till POST /api/agent/compose med en storleksförinställning och en layout. Du får tillbaka ett design-id, en Studio-länk och eventuella granskningsanmärkningar.

4. 4

   Rendera den

   Anropa POST /api/designs/:id/render med bredd, höjd och format, och avkoda den base64-fil du får tillbaka.

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

Eftersom designen ligger på en Mark sköts läsbarheten åt dig: Markens lugnaste område flyttas bakom texten och Auto-bläck väljer ljus eller mörk text per rad. För att få samma inlägg som story och som X-inlägg sparar MCP-verktyget resize_copies kopior i upp till åtta storlekar på en gång, omflödade som Studion gör det. Kopiera och ändra storlek förklarar omflödet.

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 }

Krediter, gränser och fel

När din egen assistent lägger ut en design med rit- och redigeringsverktygen går det inga Gradiently AI-krediter åt. När du ber Gradientlys egen Designer, via /api/agent, /api/batches eller verktyget design, förbrukas arbetsytans krediter precis som i Studion. AI-krediter förklarade går igenom tillgodohavandet.

Fel kommer tillbaka som en statuskod med ett läsbart error-meddelande. De du oftast ser: 401 för en saknad eller återkallad nyckel, 403 för en saknad behörighet, 402 när en exportlicens eller krediter behövs, 409 när en design ändrats sedan du läste den och 422 när ett fält inte klarar valideringen. Skicka baseUpdatedAt med en PATCH för att få den 409:an i stället för att skriva över en kollegas ändring.

Det en nyckel aldrig kan göra

Vissa åtgärder kräver alltid en person som är inloggad i Gradiently, oavsett behörigheter. En nyckel kan inte skapa eller återkalla nycklar, ändra kontot, komma åt fakturering eller betala för något, överlåta, lista eller släppa en Mark, ändra medlemmars roller eller nå någon annan arbetsyta än sin egen. Ett säkrande som kräver betalning stannar och ber om kassa i Gradiently. Gränserna är avsiktliga: en automatisering kan göra och rendera arbete, men ägande och pengar stannar hos människor. Roller beskrivs i roller i arbetsytan.