# Eine Design-API für Entwickler: API und MCP-Server von Gradiently

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

Ein Schlüssel, ein Arbeitsbereich, acht Berechtigungen. So durchsuchst du Marks, legst Designs an, erstellst weitere Größen und renderst fertige Dateien aus deinem eigenen Code oder einem KI-Assistenten, mit den Limits und Fehlern, die dir unterwegs begegnen.

## The short version

- Gradiently hat eine JSON-Design-API unter https://gradiently.design/api und einen gehosteten MCP-Server, und beide bauen auf denselben Endpunkten auf.
- Jede Anfrage trägt einen API-Schlüssel des Arbeitsbereichs, den ein Inhaber oder Admin unter Einstellungen › API und Agenten erstellt.
- Ein Schlüssel funktioniert in genau einem Arbeitsbereich, handelt als die Person, die ihn erstellt hat, und erreicht nur die Endpunkte, die seine Berechtigungen erlauben.
- Die API kann den Markt durchsuchen, Designs auf dem Mark einer Marke anlegen und bearbeiten, Kopien in anderen Größen speichern und gespeicherte Designs als PNG oder PDF rendern.
- Ein Schlüssel kann niemals Schlüssel verwalten, auf die Abrechnung zugreifen, das Konto ändern oder einen Mark weitergeben; dafür braucht es immer eine angemeldete Person.

Gradiently ist nicht nur ein Design-Tool, sondern auch eine **Design-API**. Mit einem Schlüssel und festgelegten Berechtigungen kannst du Marks durchsuchen, Designs erstellen, die den Mark deiner Marke tragen, ihre Wörter ändern, Kopien in anderen Größen speichern und das Ergebnis als PNG oder PDF rendern, alles als JSON über HTTPS. Dieselben Funktionen gibt es als gehosteten MCP-Server, sodass ChatGPT, Claude oder jeder Assistent, der Remote-MCP-Server unterstützt, die Arbeit aus einer einfachen Bitte erledigen und dir einen Link geben kann, der sich im Studio öffnet.

Diese Seite ist der Überblick für Entwickler: wofür die API gedacht ist, wie Schlüssel und Berechtigungen funktionieren, eine erste Anfrage und die Limits, die du beim Bauen berücksichtigen solltest. Die vollständige Referenz findest du unter [/developers](https://gradiently.design/de/developers).

## Was die API von Gradiently kann

Die API ist dieselbe, die auch die Gradiently-App nutzt, also sieht ein Schlüssel dieselben Daten und durchläuft dieselben Prüfungen wie sein Ersteller im Browser. Die nützlichen Aufgaben fallen in fünf Gruppen.

- **Einen Look finden.** Durchsuche den öffentlichen Markt nach Name, Farbwörtern oder Code und lies das vollständige Rezept jedes öffentlichen Marks.
- **Designs erstellen.** Beschreibe Inhalt und Layout und lass die Layout-Engine alles auf dem Mark der Marke platzieren, remixe eine der Vorlagen von Gradiently oder schick ein vollständiges Design-Dokument.
- **Designs ändern.** Bearbeite einzelne Elemente, ersetze die Wörter ausgewählter Textelemente, setze einen anderen Mark auf ein Design und speichere Kopien in anderen Größen.
- **Rendern.** Mach aus einem gespeicherten Design mit der Engine des Studios ein PNG oder PDF oder veröffentliche einen Link zum Ansehen.
- **Den Arbeitsbereich lesen.** Liste Marken, ihre Designs, Uploads und Mitglieder auf und lies Schriften, Logos und Farben einer Marke.

Typische Einsätze: ein Shop, der für jeden neuen Artikel eine Produktkarte rendert, eine Redaktion, die aus jeder Schlagzeile ein [Vorschaubild für Links](https://gradiently.design/de/guide/link-preview-image) macht, oder ein internes Tool, das die Posts der Woche aus einem Redaktionsplan erstellt. Liegen deine Daten schon in einer Tabelle, erledigt die [Massenerstellung](https://gradiently.design/de/guide/bulk-create-from-spreadsheet) im Studio die Aufgabe vielleicht ganz ohne Code.

## API oder MCP-Server

### MCP-Server

- Für KI-Assistenten, die Remote-MCP-Server unterstützen.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Tools schlagen deine Marke nach, speichern Designs und geben Links ins Studio zurück.
- Am besten, wenn du Arbeit in einfachen Worten anfragen willst.

### HTTP-API

- Für Skripte, Backends und Automatisierungen.
- JSON über HTTPS unter `https://gradiently.design/api`.
- Du wählst die Marke, schickst den Inhalt und verarbeitest jede Antwort.
- Am besten, wenn du exakte, wiederholbare Ergebnisse brauchst.

Ein Tool-Aufruf stellt dieselben Anfragen wie dein Code, mit demselben Schlüssel, zählt also gegen dieselben Limits und scheitert mit denselben Meldungen. Wenn MCP neu für dich ist, erklärt [Was ist MCP](https://gradiently.design/de/guide/what-is-mcp) es in einfachen Worten, und [einen KI-Assistenten verbinden](https://gradiently.design/de/guide/connect-ai-assistant) führt durch das Setup für ChatGPT und Claude.

## API-Schlüssel und Berechtigungen

Schlüssel werden unter **Einstellungen › API und Agenten** erstellt, und nur Inhaber und Admins eines Arbeitsbereichs können das. Ein Schlüssel wird einmal angezeigt, beginnt mit `gr_live_`, läuft nie ab und lässt sich nicht bearbeiten: Um zu ändern, was er darf, erstellst du einen neuen und widerrufst den alten. Er handelt als die Person, die ihn erstellt hat, in dem einen Arbeitsbereich, für den er gemacht wurde, und hört auf zu funktionieren, wenn diese Person geht oder herabgestuft wird.

| Berechtigung | In den Einstellungen | Was sie erlaubt |
| --- | --- | --- |
| `designs:read` | Designs lesen | Marken, Designs, Thumbnails, Uploads und Renderings |
| `designs:write` | Designs erstellen und bearbeiten | Designs erstellen, ändern, duplizieren und löschen, Bilder hochladen, den Designer ausführen |
| `marks:read` | Marks suchen | Den Markt durchsuchen und Marks lesen |
| `marks:claim` | Marks sichern | Einen verfügbaren Mark für den Ersteller des Schlüssels sichern |
| `brand:generate` | Marken generieren | Endpunkte zur Markengenerierung |
| `workspaces:read` | Arbeitsbereich lesen | Den Arbeitsbereich, seine Mitglieder und das Audit-Log |
| `personalities:write` | Marken bearbeiten | Marken erstellen, umbenennen und löschen, den Mark einer Marke ändern |
| `members:write` | Mitglieder einladen | Einladungen in den Arbeitsbereich verschicken |

Die acht Berechtigungen. Ein neuer Schlüssel startet mit den fünf, die die meiste Arbeit braucht; Marks sichern bleibt aus, bis du es wählst, denn ein Sichern macht dich zum Halter eines Marks.

> **Ein Schlüssel ist ein Passwort** Bewahre ihn in einer Umgebungsvariable oder einem Secret Store auf, einen Schlüssel pro Tool, mit den wenigsten Berechtigungen, die die Aufgabe erfüllen. Leg einen Schlüssel nie in eine Webseite, eine mobile App oder ein Repository: Gradiently speichert nur einen Hash, ein geleakter Schlüssel muss also widerrufen und ersetzt werden.

## Deine erste Anfrage

1. **Erstelle einen Schlüssel** Öffne **Einstellungen › API und Agenten**, wähle den Arbeitsbereich, benenne den Schlüssel nach dem Ort, an dem er laufen wird, und kopiere ihn, sobald er erscheint.
2. **Durchsuche den Markt** Ein `GET` an `/api/marks` mit `?q=` liefert 24 Marks pro Seite und einen `nextCursor` für die nächste.
3. **Leg ein Design an** Schick Text an `POST /api/agent/compose` mit einer Größenvorgabe und einem Layout. Du bekommst eine Design-ID, einen Studio-Link und eventuelle Prüfhinweise.
4. **Render es** Ruf `POST /api/designs/:id/render` mit Breite, Höhe und Format auf und decodiere die zurückgegebene Base64-Datei.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Die Suche im Markt braucht `marks:read`. Codes funktionieren mit oder ohne Punkte, in beliebiger Schreibweise.

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

Marken heißen in der API personalities. Zu den Layouts gehören statement, editorial, poster, split, stat, quote, list, event und minimal.

Ein Instagram-Post im Hochformat mit dem Text Frisches Brot ab 7 Uhr und einer kleinen Zeile Komm vorbei auf einem lebendigen Verlaufshintergrund

Das Ergebnis dieser Anfrage: die Wörter, von der Layout-Engine auf dem Mark der Marke platziert, im Instagram-Hochformat 1080×1350.

Weil das Design auf einem Mark steht, ist die Lesbarkeit schon geregelt: Der ruhigste Bereich des Marks wandert hinter die Wörter, und Automatische Farbe wählt Zeile für Zeile helle oder dunkle Schrift. Um denselben Post als Story und als X-Post auszuliefern, speichert das MCP-Tool `resize_copies` Kopien in bis zu acht Größen auf einmal, neu umbrochen wie im Studio. [In Größen kopieren](https://gradiently.design/de/guide/copy-to-sizes) erklärt den Umbruch.

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

Breite und Höhe reichen von 1 bis 4096. Rendern braucht dieselbe Exportlizenz für den Mark des Designs wie im Studio; ohne sie lautet die Antwort 402.

## Credits, Limits und Fehler

Legt dein eigener Assistent ein Design über die Zeichen- und Bearbeitungstools an, werden keine KI-Credits von Gradiently verbraucht. Fragst du den Designer von Gradiently selbst, über `/api/agent`, `/api/batches` oder das Tool `design`, verbraucht das die Credits des Arbeitsbereichs genau wie im Studio. [KI-Credits erklärt](https://gradiently.design/de/guide/ai-credits-explained) behandelt das Kontingent.

| Limit | Kontingent |
| --- | --- |
| Jede Anfrage mit einem Schlüssel | 120 pro Minute und Schlüssel |
| Schreibzugriffe (POST, PATCH, DELETE) | 90 pro Minute und Konto, geteilt mit der App |
| Renderings | 10 pro Minute und Konto |
| Neue Designs und Duplikate | 60 pro Minute und Konto |
| Uploads | 60 pro Minute und Konto |

Gleitende Fenster von einer Minute. Bei Überschreitung kommt 429 mit einem `Retry-After`-Header in Sekunden: Warte so lange, versuch es nicht sofort erneut.

Fehler kommen als Statuscode mit einer lesbaren `error`-Meldung zurück. Die häufigsten: 401 bei fehlendem oder widerrufenem Schlüssel, 403 bei fehlender Berechtigung, 402, wenn eine Exportlizenz oder Credits nötig sind, 409, wenn sich ein Design seit dem Lesen geändert hat, und 422, wenn ein Feld die Validierung nicht besteht. Schick `baseUpdatedAt` mit einem `PATCH`, um dieses 409 zu bekommen, statt die Änderung einer Kollegin zu überschreiben.

## Was ein Schlüssel niemals kann

Manche Aktionen brauchen immer eine bei Gradiently angemeldete Person, egal welche Berechtigungen gesetzt sind. Ein Schlüssel kann keine Schlüssel erstellen oder widerrufen, das Konto nicht ändern, nicht auf die Abrechnung zugreifen oder etwas bezahlen, einen Mark nicht übertragen, anbieten oder freigeben, die Rollen von Mitgliedern nicht ändern und keinen anderen Arbeitsbereich als seinen eigenen erreichen. Ein Sichern, das eine Zahlung braucht, hält an und verweist auf den Checkout in Gradiently. Diese Grenzen sind gewollt: Eine Automatisierung kann Arbeit erstellen und rendern, aber Besitz und Geld bleiben bei Menschen. Rollen behandelt [Rollen im Arbeitsbereich](https://gradiently.design/de/guide/workspace-roles).

## FAQ

### Hat Gradiently eine API?

Ja. Es gibt eine JSON-API unter `https://gradiently.design/api` und einen gehosteten MCP-Server, beide nutzbar mit einem API-Schlüssel des Arbeitsbereichs oder, für ChatGPT und Claude, per OAuth-Anmeldung.

### Wer kann einen API-Schlüssel für Gradiently erstellen?

Inhaber und Admins eines Arbeitsbereichs, unter Einstellungen › API und Agenten. Der Schlüssel wird einmal angezeigt und funktioniert nur in diesem Arbeitsbereich.

### Kann ich ein Design über die API als PNG rendern?

Ja. `POST /api/designs/:id/render` liefert ein PNG oder PDF als Base64, bis 4096 Pixel pro Seite, sofern du die Exportlizenz für den Mark des Designs hältst.

### Verbraucht die Nutzung der API KI-Credits?

Designs anlegen, bearbeiten und rendern nicht. Den Designer von Gradiently über die API oder das Tool `design` zu fragen, verbraucht die KI-Credits des Arbeitsbereichs.

### Welche Rate Limits hat die API?

120 Anfragen pro Minute und Schlüssel, mit niedrigeren Limits für Schreibzugriffe, Renderings und Uploads. Über einem Limit bekommst du 429 mit einem `Retry-After`-Header.