Et design-API til udviklere: Gradiently API og MCP-server

Gradiently er et design-API og ikke kun et designværktøj. Med én begrænset nøgle kan du søge i Marks, oprette designs, der bærer dit brands Mark, ændre deres tekst, gemme kopier i andre størrelser og rendere resultatet til PNG eller PDF, alt sammen som JSON over HTTPS. De samme muligheder findes som en hostet MCP-server, så ChatGPT, Claude eller enhver assistent med understøttelse af eksterne MCP-servere kan gøre arbejdet ud fra en helt almindelig anmodning og give dig et link, der åbner i Studiet.

Denne side er udviklerens overblik: hvad API’et bruges til, hvordan nøgler og rettigheder fungerer, en første forespørgsel og de grænser, det er værd at designe efter. Den fulde reference findes på /developers.

Hvad Gradiently API kan gøre

API’et er det samme, som Gradiently-appen selv bruger, så en nøgle ser de samme data og består de samme kontroller, som personen bag den ville gøre i browseren. De nyttige opgaver falder i fem grupper.

• Find et udtryk. Søg i det offentlige Marked på navn, farveord eller kode, og læs hele opskriften på enhver offentlig Mark.
• Lav designs. Beskriv indhold og layout, og lad layoutmotoren placere det på brandets Mark, remix en af skabeloner i Gradiently, eller send et helt designdokument.
• Ændr designs. Redigér element for element, udskift teksten i udvalgte tekstelementer, læg en anden Mark på et design og gem kopier i andre størrelser.
• Render. Gør et gemt design til PNG eller PDF med Studiets egen motor, eller udgiv et visningslink til det.
• Læs arbejdsområdet. List brands, deres designs, uploads og medlemmer, og læs et brands skrifttyper, logoer og farver.

Typiske brugsscenarier: en butik, der renderer et produktkort for hver ny vare, en nyhedsredaktion, der gør hver overskrift til et billede til linkforhåndsvisning, eller et internt værktøj, der laver ugens opslag ud fra en indholdskalender. Hvis dine kildedata allerede ligger i et regneark, kan masseoprettelse i Studio måske klare opgaven helt uden kode.

API eller MCP-server

Et værktøjskald sender de samme forespørgsler som din kode, med den samme nøgle, så det tæller med i de samme grænser og fejler med de samme beskeder. Hvis MCP er nyt for dig, forklarer hvad er MCP det i almindeligt sprog, og forbind en AI-assistent gennemgår opsætningen af ChatGPT og Claude.

API-nøgler og rettigheder

Nøgler oprettes under Indstillinger › API og agenter, og kun ejere og admins af et arbejdsområde kan lave dem. En nøgle vises én gang, begynder med gr_live_, udløber aldrig og kan ikke redigeres: vil du ændre, hvad den kan, så lav en ny og tilbagekald den gamle. Den handler som den person, der oprettede den, i det ene arbejdsområde, den blev lavet til, og holder op med at virke, hvis personen forlader arbejdsområdet eller mister sine rettigheder.

Din første forespørgsel

1. 1

   Opret en nøgle

   Åbn Indstillinger › API og agenter, vælg arbejdsområde, giv nøglen navn efter det sted, den skal køre, og kopiér den, når den vises.

2. 2

   Søg i Markedet

   Et GET til /api/marks med ?q= returnerer 24 Marks pr. side og en nextCursor til næste side.

3. 3

   Sæt et design op

   Send tekst til POST /api/agent/compose med en størrelsesforudindstilling og et layout. Du får et design-id, et Studio-link og eventuelle gennemgangspunkter.

4. 4

   Render det

   Kald POST /api/designs/:id/render med bredde, højde og format, og afkod den base64-fil, du får tilbage.

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

Fordi designet ligger på en Mark, er læsbarheden klaret for dig: Markens roligste område flytter sig bag teksten, og Auto-blæk vælger lys eller mørk skrift linje for linje. Vil du levere det samme opslag som story og som X-opslag, gemmer MCP-værktøjet resize_copies kopier i op til otte størrelser på én gang, omsat som i Studiet. Kopiér til størrelser forklarer omsætningen.

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 }

Kreditter, grænser og fejl

Når din egen assistent sætter et design op med tegne- og redigeringsværktøjerne, bruges der ingen AI-kreditter hos Gradiently. Når du beder Designer i Gradiently via /api/agent, /api/batches eller værktøjet design, bruger det arbejdsområdets kreditter på samme måde som i Studiet. AI-kreditter forklaret gennemgår kvoten.

Fejl kommer tilbage som en statuskode med en læsbar error-besked. De hyppigste: 401 for en manglende eller tilbagekaldt nøgle, 403 for en manglende rettighed, 402 når der kræves en eksportlicens eller kreditter, 409 når et design er ændret, siden du læste det, og 422 når et felt ikke består valideringen. Send baseUpdatedAt med en PATCH for at få den 409 i stedet for at overskrive en kollegas ændring.

Hvad en nøgle aldrig kan

Nogle handlinger kræver altid en person, der er logget ind i Gradiently, uanset rettigheder. En nøgle kan ikke oprette eller tilbagekalde nøgler, ændre kontoen, nå fakturering eller betale for noget, overdrage, liste eller frigive en Mark, ændre medlemmers roller eller nå andre arbejdsområder end sit eget. Et krav om at sikre sig en Mark, der kræver betaling, stopper og beder om betaling i Gradiently. Grænserne er bevidste: en automatisering kan lave og rendere arbejde, men ejerskab og penge bliver hos mennesker. Roller er beskrevet i roller i arbejdsområdet.