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

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.

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 macht, oder ein internes Tool, das die Posts der Woche aus einem Redaktionsplan erstellt. Liegen deine Daten schon in einer Tabelle, erledigt die Massenerstellung im Studio die Aufgabe vielleicht ganz ohne Code.

API oder MCP-Server

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 es in einfachen Worten, und einen KI-Assistenten verbinden 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.

Deine erste Anfrage

1. 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. 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. 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. 4

   Render es

   Ruf POST /api/designs/:id/render mit Breite, Höhe und Format auf und decodiere die zurückgegebene Base64-Datei.

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

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 erklärt den Umbruch.

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 }

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 behandelt das Kontingent.

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.