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

[Canonical HTML page](https://gradiently.design/da/guide/gradiently-for-developers)

Én nøgle, ét arbejdsområde, otte rettigheder. Sådan søger du i Marks, sætter designs op, laver andre størrelser og renderer færdige filer fra din egen kode eller en AI-assistent, med de grænser og fejl, du vil møde undervejs.

## The short version

- Gradiently har et JSON-design-API på https://gradiently.design/api og en hostet MCP-server, og begge bygger på de samme endpoints.
- Hver forespørgsel bærer en API-nøgle til arbejdsområdet, som en ejer eller admin opretter under Indstillinger › API og agenter.
- En nøgle virker i præcis ét arbejdsområde, handler som den person, der oprettede den, og kan kun nå de endpoints, dens rettigheder tillader.
- API’et kan søge i Markedet, sætte designs op og redigere dem på et brands Mark, gemme kopier i andre størrelser og rendere gemte designs til PNG eller PDF.
- En nøgle kan aldrig administrere nøgler, nå fakturering, ændre kontoen eller give en Mark væk; det kræver altid en person, der er logget ind.

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](https://gradiently.design/da/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](https://gradiently.design/da/guide/link-preview-image), eller et internt værktøj, der laver ugens opslag ud fra en indholdskalender. Hvis dine kildedata allerede ligger i et regneark, kan [masseoprettelse](https://gradiently.design/da/guide/bulk-create-from-spreadsheet) i Studio måske klare opgaven helt uden kode.

## API eller MCP-server

### MCP-server

- Til AI-assistenter, der understøtter eksterne MCP-servere.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Værktøjerne slår dit brand op, gemmer designs og returnerer Studio-links.
- Bedst, når du vil bede om arbejde med almindelige ord.

### HTTP-API

- Til scripts, backends og automatiseringer.
- JSON over HTTPS under `https://gradiently.design/api`.
- Du vælger brand, sender indholdet og håndterer hvert svar.
- Bedst, når du har brug for præcist, gentageligt output.

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](https://gradiently.design/da/guide/what-is-mcp) det i almindeligt sprog, og [forbind en AI-assistent](https://gradiently.design/da/guide/connect-ai-assistant) 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.

| Rettighed | I Indstillinger | Hvad den tillader |
| --- | --- | --- |
| `designs:read` | Læs designs | Brands, designs, miniaturer, uploads og renderinger |
| `designs:write` | Opret og redigér designs | Oprette, ændre, duplikere og slette designs, uploade billeder, køre Designer |
| `marks:read` | Søg i Marks | Søge i Markedet og læse Marks |
| `marks:claim` | Sikr dig Marks | Sikre sig en ledig Mark til nøglens opretter |
| `brand:generate` | Generér brands | Endpoints til brandgenerering |
| `arbejdsområder:read` | Læs arbejdsområdet | Arbejdsområdet, dets medlemmer og revisionslog |
| `personalities:write` | Redigér brands | Oprette, omdøbe og slette brands, skifte et brands Mark |
| `members:write` | Invitér medlemmer | Sende invitationer til arbejdsområdet |

De otte rettigheder. En ny nøgle starter med de fem, som det meste arbejde kræver; Sikr dig Marks er slået fra, til du vælger det, fordi det at sikre sig en Mark gør dig til dens indehaver.

> **En nøgle er en adgangskode** Opbevar den i en miljøvariabel eller et secret store, én nøgle pr. værktøj, med så få rettigheder som muligt. Læg aldrig en nøgle på en webside, i en mobilapp eller i et repository: Gradiently gemmer kun en hash, så en lækket nøgle skal tilbagekaldes og erstattes.

## Din første forespørgsel

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. **Søg i Markedet** Et `GET` til `/api/marks` med `?q=` returnerer 24 Marks pr. side og en `nextCursor` til næste side.
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. **Render det** Kald `POST /api/designs/:id/render` med bredde, højde og format, og afkod den base64-fil, du får tilbage.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

curl "https://gradiently.design/api/marks?q=deep%20teal" \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"
```

At søge i Markedet kræver `marks:read`. Koder virker med eller uden punktummer, med store eller små bogstaver.

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

Brands hedder personalities i API’et. Layouts omfatter statement, editorial, poster, split, stat, quote, list, event og minimal.

Et stående Instagram-opslag med teksten Frisk brød fra kl. 7 og en lille linje med Kom forbi, sat på en levende gradientbaggrund

Det, forespørgslen giver: teksten placeret af layoutmotoren på brandets Mark, i Instagrams stående format på 1080×1350.

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](https://gradiently.design/da/guide/copy-to-sizes) forklarer omsætningen.

```json
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 }
```

Bredde og højde går fra 1 til 4096. Rendering kræver samme eksportlicens til designets Mark som Studiet; uden den er svaret 402.

## 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](https://gradiently.design/da/guide/ai-credits-explained) gennemgår kvoten.

| Grænse | Kvote |
| --- | --- |
| Hver forespørgsel med en nøgle | 120 i minuttet pr. nøgle |
| Skrivninger (POST, PATCH, DELETE) | 90 i minuttet pr. konto, delt med appen |
| Renderinger | 10 i minuttet pr. konto |
| Nye designs og dubletter | 60 i minuttet pr. konto |
| Uploads | 60 i minuttet pr. konto |

Glidende vinduer på ét minut. Overskrider du dem, svarer API’et 429 med en `Retry-After`-header i sekunder: vent så længe, og forsøg ikke igen med det samme.

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](https://gradiently.design/da/guide/workspace-roles).

## FAQ

### Har Gradiently et API?

Ja. Det har et JSON-API under `https://gradiently.design/api` og en hostet MCP-server, begge brugt med en API-nøgle til arbejdsområdet eller, for ChatGPT og Claude, med OAuth-login.

### Hvem kan oprette en Gradiently API-nøgle?

Ejere og admins af et arbejdsområde, under Indstillinger › API og agenter. Nøglen vises én gang og virker kun i det arbejdsområde.

### Kan jeg rendere et design til PNG med API’et?

Ja. `POST /api/designs/:id/render` returnerer en PNG eller PDF som base64, op til 4096 pixel på hver led, så længe du har eksportlicensen til designets Mark.

### Bruger API’et AI-kreditter?

Opsætning, redigering og rendering af designs gør ikke. Når du beder Designer i Gradiently via API’et eller værktøjet `design`, bruges arbejdsområdets AI-kreditter.

### Hvad er API’ets grænser for forespørgsler?

120 forespørgsler i minuttet pr. nøgle, med lavere grænser for skrivninger, renderinger og uploads. Over en grænse får du en 429 med en `Retry-After`-header.