Een design-API voor developers: API en MCP-server

Gradiently is zowel een tool als een design-API. Met één afgebakende sleutel zoek je Marks, maak je ontwerpen die de Mark van je merk dragen, wijzig je de woorden, sla je kopieën in andere formaten op en render je het resultaat naar PNG of PDF, alles als JSON via HTTPS. Dezelfde mogelijkheden worden aangeboden als gehoste MCP-server, zodat ChatGPT, Claude of elke assistent die externe MCP-servers ondersteunt het werk kan doen op basis van een gewoon verzoek en je een link geeft die in de Studio opent.

Deze pagina is het overzicht voor developers: waarvoor de API dient, hoe sleutels en scopes werken, een eerste verzoek en de limieten waar je rekening mee moet houden. De volledige referentie staat op /developers.

Wat de Gradiently-API kan

De API is dezelfde die de Gradiently-app zelf gebruikt, dus een sleutel ziet dezelfde gegevens en doorloopt dezelfde controles als de maker in de browser. De bruikbare taken vallen in vijf groepen.

• Een look vinden. Zoek in de openbare Markt op naam, kleurwoorden of code en lees het volledige recept van elke openbare Mark.
• Ontwerpen maken. Beschrijf inhoud en een lay-out en laat de lay-outengine het op de Mark van het merk plaatsen, remix een van de templates van Gradiently of stuur een volledig ontwerpdocument.
• Ontwerpen wijzigen. Bewerk per element, vervang de woorden van gekozen tekstelementen, zet een andere Mark op een ontwerp en sla kopieën in andere formaten op.
• Renderen. Zet een opgeslagen ontwerp om naar PNG of PDF met de eigen engine van de Studio, of publiceer er een weergavelink voor.
• De werkruimte lezen. Toon merken, hun ontwerpen, uploads en leden en lees de lettertypen, logo’s en kleuren van een merk.

Typische toepassingen: een winkel die voor elk nieuw artikel een productkaart rendert, een redactie die van elke kop een linkvoorbeeldafbeelding maakt, of een interne tool die de posts van de week uit een contentkalender maakt. Staan je brongegevens al in een spreadsheet, dan kan bulk aanmaken in de Studio het werk misschien zonder code doen.

API of MCP-server

Een toolaanroep doet dezelfde verzoeken als je code, met dezelfde sleutel, dus telt mee voor dezelfde limieten en faalt met dezelfde meldingen. Is MCP nieuw voor je, dan legt wat is MCP het in gewone woorden uit en loopt een AI-assistent koppelen de installatie voor ChatGPT en Claude door.

API-sleutels en scopes

Sleutels maak je aan in Instellingen › API en agents, en alleen eigenaren en beheerders van een werkruimte kunnen ze maken. Een sleutel wordt één keer getoond, begint met gr_live_, verloopt nooit en kan niet worden bewerkt: om te wijzigen wat hij kan, maak je een nieuwe en trek je de oude in. Hij treedt op als de persoon die hem heeft gemaakt, binnen de ene werkruimte waarvoor hij is gemaakt, en werkt niet meer als die persoon vertrekt of lager in rang wordt gezet.

Je eerste verzoek

1. 1

   Maak een sleutel

   Open Instellingen › API en agents, kies de werkruimte, noem de sleutel naar waar hij gaat draaien en kopieer hem zodra hij verschijnt.

2. 2

   Doorzoek de Markt

   Een GET naar /api/marks met ?q= geeft 24 Marks per pagina en een nextCursor voor de volgende.

3. 3

   Maak een ontwerp op

   Stuur tekst naar POST /api/agent/compose met een formaatpreset en een lay-out. Je krijgt een ontwerp-id, een Studio-link en eventuele reviewpunten terug.

4. 4

   Render het

   Roep POST /api/designs/:id/render aan met een breedte, hoogte en formaat en decodeer het base64-bestand dat het teruggeeft.

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

Omdat het ontwerp op een Mark staat, is leesbaarheid voor je geregeld: het rustigste gebied van de Mark schuift achter de woorden en Auto-inkt kiest per regel lichte of donkere letters. Om dezelfde post als story en als X-post te leveren, slaat de MCP-tool resize_copies kopieën op in maximaal acht formaten tegelijk, opnieuw opgemaakt zoals de Studio dat doet. Kopiëren naar formaten legt de herindeling uit.

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, limieten en fouten

Als je eigen assistent een ontwerp opmaakt via de teken- en bewerktools, worden er geen AI-credits van Gradiently uitgegeven. Vraag je de eigen Designer van Gradiently, via /api/agent, /api/batches of de tool design, dan gaan de credits van de werkruimte op, precies zoals in de Studio. AI-credits uitgelegd behandelt het tegoed.

Fouten komen terug als statuscode met een leesbare error-melding. De meest voorkomende: 401 voor een ontbrekende of ingetrokken sleutel, 403 voor een ontbrekende scope, 402 als een exportlicentie of credits nodig zijn, 409 als een ontwerp is gewijzigd sinds je het las en 422 als een veld de validatie niet doorstaat. Stuur baseUpdatedAt mee met een PATCH om die 409 te krijgen in plaats van de bewerking van een collega te overschrijven.

Wat een sleutel nooit kan

Sommige acties vereisen altijd een persoon die bij Gradiently is ingelogd, wat de scopes ook zijn. Een sleutel kan geen sleutels maken of intrekken, het account niet wijzigen, niet bij facturatie komen of ergens voor betalen, geen Mark overdragen, tonen of vrijgeven, geen rollen van leden wijzigen en geen andere werkruimte bereiken dan de eigen. Een claim waarvoor betaling nodig is stopt en vraagt om afrekenen in Gradiently. Deze grenzen zijn bewust: een automatisering kan werk maken en renderen, maar eigendom en geld blijven bij mensen. Rollen staan in werkruimterollen.