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

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

En nyckel, en arbetsyta, åtta behörigheter. Så söker du Marks, lägger ut designer, gör andra storlekar och renderar färdiga filer från din egen kod eller en AI-assistent, med de gränser och fel du kommer att möta.

## The short version

- Gradiently har ett JSON-baserat design-API under https://gradiently.design/api och en värdbaserad MCP-server, och båda bygger på samma endpoints.
- Varje anrop har en API-nyckel för arbetsytan, som en ägare eller admin skapar under Inställningar › API och agenter.
- En nyckel fungerar i exakt en arbetsyta, agerar som den som skapade den och kommer bara åt de endpoints som dess behörigheter tillåter.
- API:t kan söka i Marknaden, lägga ut och redigera designer på ett varumärkes Mark, spara kopior i andra storlekar och rendera sparade designer till PNG eller PDF.
- En nyckel kan aldrig hantera nycklar, komma åt fakturering, ändra kontot eller ge bort en Mark. Det kräver alltid en inloggad person.

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](https://gradiently.design/sv/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](https://gradiently.design/sv/guide/link-preview-image), 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](https://gradiently.design/sv/guide/bulk-create-from-spreadsheet) i Studion klara jobbet helt utan kod.

## API eller MCP-server

### MCP-server

- För AI-assistenter som stöder fjärr-MCP-servrar.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Verktygen slår upp ditt varumärke, sparar designer och returnerar Studio-länkar.
- Bäst när du vill be om arbete med vanliga ord.

### HTTP-API

- För skript, backend-system och automatiseringar.
- JSON över HTTPS under `https://gradiently.design/api`.
- Du väljer varumärke, skickar innehållet och hanterar varje svar.
- Bäst när du behöver exakt, repeterbart resultat.

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](https://gradiently.design/sv/guide/what-is-mcp) det med enkla ord, och [att ansluta en AI-assistent](https://gradiently.design/sv/guide/connect-ai-assistant) 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.

| Behörighet | I Inställningar | Vad den tillåter |
| --- | --- | --- |
| `designs:read` | Läsa designer | Varumärken, designer, miniatyrer, uppladdningar och renderingar |
| `designs:write` | Skapa och redigera designer | Skapa, ändra, duplicera och ta bort designer, ladda upp bilder, köra Designern |
| `marks:read` | Söka efter Marks | Söka i Marknaden och läsa Marks |
| `marks:claim` | Säkra Marks | Säkra en tillgänglig Mark åt nyckelns skapare |
| `brand:generate` | Generera varumärken | Endpoints för varumärkesgenerering |
| `workspaces:read` | Läsa arbetsytan | Arbetsytan, dess medlemmar och granskningslogg |
| `personalities:write` | Redigera varumärken | Skapa, byta namn på och ta bort varumärken, byta ett varumärkes Mark |
| `members:write` | Bjuda in medlemmar | Skicka inbjudningar till arbetsytan |

De åtta behörigheterna. En ny nyckel börjar med de fem som det mesta arbetet behöver. Säkra Marks är avstängt tills du väljer det, eftersom ett säkrande gör dig till innehavare av en Mark.

> **En nyckel är ett lösenord** Förvara den i en miljövariabel eller ett hemligt valv, en nyckel per verktyg, med så få behörigheter som jobbet kräver. Lägg aldrig en nyckel på en webbsida, i en mobilapp eller i ett arkiv: Gradiently sparar bara en hash, så en läckt nyckel måste återkallas och ersättas.

## Ditt första anrop

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. **Sök i Marknaden** Ett `GET` till `/api/marks` med `?q=` ger 24 Marks per sida och en `nextCursor` till nästa.
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. **Rendera den** Anropa `POST /api/designs/:id/render` med bredd, höjd och format, och avkoda den base64-fil du får tillbaka.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Att söka i Marknaden kräver `marks:read`. Koder fungerar med eller utan punkter, med stora eller små bokstäver.

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

Varumärken kallas personalities i API:t. Layouterna är statement, editorial, poster, split, stat, quote, list, event och minimal.

Ett stående Instagram-inlägg med texten Nybakat bröd från 07 och en liten rad Välkommen in, på en levande gradientbakgrund

Det här ger anropet: texten placerad av layoutmotorn på varumärkets Mark, i Instagrams stående format 1080×1350.

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](https://gradiently.design/sv/guide/copy-to-sizes) förklarar omflödet.

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

Bredd och höjd går från 1 till 4096. För rendering krävs samma exportlicens för designens Mark som i Studion. Utan den blir svaret 402.

## 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](https://gradiently.design/sv/guide/ai-credits-explained) går igenom tillgodohavandet.

| Gräns | Tillåtet |
| --- | --- |
| Varje anrop med en nyckel | 120 per minut och nyckel |
| Skrivningar (POST, PATCH, DELETE) | 90 per minut och konto, delat med appen |
| Renderingar | 10 per minut och konto |
| Nya designer och dubbletter | 60 per minut och konto |
| Uppladdningar | 60 per minut och konto |

Glidande minutfönster. Går du över gränsen svarar API:t 429 med en `Retry-After`-header i sekunder: vänta så länge och försök inte igen direkt.

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

## FAQ

### Har Gradiently ett API?

Ja. Det finns ett JSON-API under `https://gradiently.design/api` och en värdbaserad MCP-server, båda med en API-nyckel för arbetsytan eller, för ChatGPT och Claude, inloggning med OAuth.

### Vem kan skapa en API-nyckel i Gradiently?

Ägare och admins i en arbetsyta, under Inställningar › API och agenter. Nyckeln visas en gång och fungerar bara i den arbetsytan.

### Kan jag rendera en design till PNG med API:t?

Ja. `POST /api/designs/:id/render` returnerar en PNG eller PDF som base64, upp till 4096 pixlar per sida, så länge du har exportlicensen för designens Mark.

### Förbrukar API:t AI-krediter?

Inte när du lägger ut, redigerar och renderar designer. När du ber Gradientlys egen Designer via API:t eller verktyget `design` förbrukas arbetsytans AI-krediter.

### Vilka gränser gäller för API-anrop?

120 anrop per minut och nyckel, med lägre gränser för skrivningar, renderingar och uppladdningar. Går du över får du 429 med en `Retry-After`-header.