API de design pour développeurs : API et serveur MCP de Gradiently

Gradiently est une API de design autant qu’un outil de design. Avec une seule clé aux portées limitées, vous pouvez chercher des Marks, créer des créations qui portent le Mark de votre marque, changer leurs mots, enregistrer des copies dans d’autres tailles et rendre le résultat en PNG ou PDF, le tout en JSON sur HTTPS. Les mêmes capacités existent sous forme de serveur MCP hébergé : ChatGPT, Claude ou tout assistant compatible avec les serveurs MCP distants peut faire le travail à partir d’une simple demande et vous renvoyer un lien qui s’ouvre dans le Studio.

Cette page est la vue d’ensemble pour développeurs : à quoi sert l’API, comment fonctionnent les clés et les portées, une première requête, et les limites à prendre en compte dans votre conception. La référence complète se trouve sur /developers.

Ce que l’API Gradiently sait faire

L’API est celle qu’utilise l’application Gradiently elle-même : une clé voit donc les mêmes données et passe les mêmes contrôles que son créateur dans le navigateur. Les tâches utiles se répartissent en cinq groupes.

• Trouver un style. Cherchez dans le Marché public par nom, mots de couleur ou code, et lisez la recette complète de n’importe quel Mark public.
• Créer. Décrivez un contenu et une mise en page et laissez le moteur de mise en page le placer sur le Mark de la marque, remixez un modèle de Gradiently ou envoyez un document de création complet.
• Modifier. Éditez élément par élément, remplacez les mots des textes choisis, appliquez un autre Mark à une création et enregistrez des copies dans d’autres tailles.
• Rendre. Transformez une création enregistrée en PNG ou PDF avec le moteur du Studio, ou publiez un lien de consultation.
• Lire l’espace de travail. Listez les marques, leurs créations, imports et membres, et lisez les polices, logos et couleurs d’une marque.

Usages typiques : une boutique qui génère une fiche visuelle pour chaque nouveau produit, une rédaction qui transforme chaque titre en image d’aperçu de lien, ou un outil interne qui produit les publications de la semaine depuis un calendrier éditorial. Si vos données vivent déjà dans un tableur, la création en lot du Studio peut faire le travail sans une ligne de code.

API ou serveur MCP

Un appel d’outil fait les mêmes requêtes que votre code, avec la même clé : il compte dans les mêmes limites et échoue avec les mêmes messages. Si MCP est nouveau pour vous, qu’est-ce que MCP l’explique simplement, et connecter un assistant IA détaille la configuration de ChatGPT et Claude.

Clés API et portées

Les clés se créent dans Paramètres › API et agents, et seuls les propriétaires et administrateurs d’un espace de travail peuvent en créer. Une clé s’affiche une seule fois, commence par gr_live_, n’expire jamais et ne peut pas être modifiée : pour changer ce qu’elle peut faire, créez-en une nouvelle et révoquez l’ancienne. Elle agit au nom de la personne qui l’a créée, dans le seul espace de travail pour lequel elle a été créée, et cesse de fonctionner si cette personne part ou perd son rôle.

Votre première requête

1. 1

   Créez une clé

   Ouvrez Paramètres › API et agents, choisissez l’espace de travail, nommez la clé d’après l’endroit où elle tournera et copiez-la quand elle apparaît.

2. 2

   Cherchez dans le Marché

   Un GET vers /api/marks avec ?q= renvoie 24 Marks par page et un nextCursor pour la suivante.

3. 3

   Mettez en page une création

   Envoyez le texte à POST /api/agent/compose avec un préréglage de taille et une mise en page. Vous recevez un identifiant de création, un lien vers le Studio et les éventuels points à revoir.

4. 4

   Rendez-la

   Appelez POST /api/designs/:id/render avec une largeur, une hauteur et un format, puis décodez le fichier base64 renvoyé.

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

Comme la création repose sur un Mark, la lisibilité est gérée pour vous : la zone la plus calme du Mark se place derrière les mots et l’encre automatique choisit un texte clair ou sombre pour chaque ligne. Pour publier la même création en story et sur X, l’outil MCP resize_copies enregistre des copies dans jusqu’à huit tailles à la fois, recomposées comme le fait le Studio. Copier vers les tailles explique la recomposition.

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 }

Crédits, limites et erreurs

Quand votre propre assistant met en page une création avec les outils de dessin et de modification, aucun crédit IA Gradiently n’est dépensé. Solliciter le Designer de Gradiently, via /api/agent, /api/batches ou l’outil design, dépense les crédits de l’espace de travail exactement comme dans le Studio. Les crédits IA expliqués détaille la dotation.

Les erreurs reviennent sous forme de code de statut avec un message error lisible. Les plus fréquentes : 401 pour une clé absente ou révoquée, 403 pour une portée manquante, 402 quand une licence d’export ou des crédits sont nécessaires, 409 quand une création a changé depuis votre lecture, et 422 quand un champ échoue à la validation. Envoyez baseUpdatedAt avec un PATCH pour obtenir ce 409 au lieu d’écraser la modification d’un collègue.

Ce qu’une clé ne peut jamais faire

Certaines actions exigent toujours une personne connectée à Gradiently, quelles que soient les portées. Une clé ne peut pas créer ni révoquer de clés, modifier le compte, accéder à la facturation ou payer quoi que ce soit, transférer, mettre en vente ou libérer un Mark, changer les rôles des membres, ni atteindre un autre espace de travail que le sien. Une réservation qui demande un paiement s’arrête et renvoie vers le paiement dans Gradiently. Ces limites sont voulues : une automatisation peut produire et rendre du travail, mais la propriété et l’argent restent entre les mains des personnes. Les rôles sont détaillés dans les rôles d’espace de travail.