Design-API for utviklere: API og MCP-server fra Gradiently

Gradiently er et design-API i tillegg til et designverktøy. Med én avgrenset nøkkel kan du søke etter Marks, lage design som bærer merkets Mark, endre ordene, lagre kopier i andre størrelser og rendre resultatet til PNG eller PDF, alt som JSON over HTTPS. De samme mulighetene finnes som en driftet MCP-server, så ChatGPT, Claude eller en hvilken som helst assistent som støtter eksterne MCP-servere, kan gjøre jobben ut fra en vanlig forespørsel og gi deg en lenke som åpnes i Studio.

Denne siden er utviklerens oversikt: hva API-et er til, hvordan nøkler og tillatelser virker, en første forespørsel og grensene det lønner seg å planlegge rundt. Den fullstendige referansen finner du på /developers.

Dette kan Gradiently-API-et gjøre

API-et er det samme som Gradiently-appen selv bruker, så en nøkkel ser de samme dataene og går gjennom de samme kontrollene som skaperen ville gjort i nettleseren. De nyttige jobbene faller i fem grupper.

• Finn en look. Søk i det offentlige Markedet etter navn, fargeord eller kode, og les hele oppskriften til en hvilken som helst offentlig Mark.
• Lag design. Beskriv innhold og layout og la layoutmotoren plassere det på merkets Mark, remiks en av Gradiently sine maler, eller send et komplett designdokument.
• Endre design. Rediger element for element, bytt ut ordene i utvalgte tekstelementer, sett en annen Mark på et design og lagre kopier i andre størrelser.
• Rendre. Gjør et lagret design om til PNG eller PDF med Studios egen motor, eller publiser en visningslenke til det.
• Les arbeidsområdet. List opp merker, designene deres, opplastinger og medlemmer, og les et merkes fonter, logoer og farger.

Typiske bruksområder: en nettbutikk som rendrer et produktkort for hver ny vare, en redaksjon som gjør hver overskrift om til et forhåndsvisningsbilde for lenker, eller et internt verktøy som lager ukens innlegg fra en innholdskalender. Ligger kildedataene dine allerede i et regneark, kan masseoppretting i Studio gjøre jobben helt uten kode.

API eller MCP-server

Et verktøykall gjør de samme forespørslene som koden din ville gjort, med den samme nøkkelen, så det teller mot de samme grensene og feiler med de samme meldingene. Er MCP nytt for deg, forklarer hva er MCP det med enkle ord, og koble til en AI-assistent viser oppsettet for ChatGPT og Claude.

API-nøkler og tillatelser

Nøkler opprettes i Innstillinger › API og agenter, og bare eiere og admin i et arbeidsområde kan lage dem. En nøkkel vises én gang, starter med gr_live_, utløper aldri og kan ikke redigeres: vil du endre hva den kan gjøre, lager du en ny og tilbakekaller den gamle. Den handler som personen som opprettet den, i det ene arbeidsområdet den ble laget for, og slutter å virke hvis personen forlater arbeidsområdet eller får en lavere rolle.

Din første forespørsel

1. 1

   Opprett en nøkkel

   Åpne Innstillinger › API og agenter, velg arbeidsområdet, gi nøkkelen navn etter hvor den skal kjøre, og kopier den når den vises.

2. 2

   Søk i Markedet

   En GET mot /api/marks med ?q= returnerer 24 Marks per side og en nextCursor for neste side.

3. 3

   Sett opp et design

   Send tekst til POST /api/agent/compose med en forhåndsinnstilt størrelse og en layout. Du får en design-id, en lenke til Studio og eventuelle funn fra gjennomgangen.

4. 4

   Rendre det

   Kall POST /api/designs/:id/render med bredde, høyde og format, og dekod base64-filen du får tilbake.

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 lesbarheten tatt hånd om: Markens roligste område flytter seg bak ordene, og Automatisk blekk velger lys eller mørk tekst for hver linje. Skal det samme innlegget ut som story og som X-innlegg, lagrer MCP-verktøyet resize_copies kopier i opptil åtte størrelser på én gang, omflytet slik Studio gjør det. Kopier til størrelser forklarer omflytingen.

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, grenser og feil

Når din egen assistent setter opp et design med tegne- og redigeringsverktøyene, brukes ingen AI-kreditter fra Gradiently. Ber du Gradiently sin egen Designer om hjelp, via /api/agent, /api/batches eller verktøyet design, brukes arbeidsområdets kreditter akkurat som i Studio. AI-kreditter forklart går gjennom kvoten.

Feil kommer tilbake som en statuskode med en lesbar error-melding. De du oftest ser: 401 for en manglende eller tilbakekalt nøkkel, 403 for en manglende tillatelse, 402 når det trengs eksportlisens eller kreditter, 409 når et design er endret siden du leste det, og 422 når et felt ikke består valideringen. Send baseUpdatedAt med en PATCH for å få den 409-feilen i stedet for å overskrive en kollegas endring.

Dette kan en nøkkel aldri gjøre

Noen handlinger krever alltid en person som er logget inn i Gradiently, uansett tillatelser. En nøkkel kan ikke opprette eller tilbakekalle nøkler, endre kontoen, nå fakturering eller betale for noe, overføre, legge ut eller frigi en Mark, endre medlemmers roller eller nå andre arbeidsområder enn sitt eget. Å sikre seg en Mark som krever betaling, stopper opp og ber om kassen i Gradiently. Grensene er bevisste: en automatisering kan lage og rendre arbeid, men eierskap og penger blir hos mennesker. Roller er forklart i roller i arbeidsområdet.