# API de design pour développeurs : API et serveur MCP de Gradiently [Canonical HTML page](https://gradiently.design/fr/guide/gradiently-for-developers) Une clé, un espace de travail, huit portées. Comment chercher des Marks, mettre en page des créations, produire d’autres tailles et rendre des fichiers finis depuis votre code ou un assistant IA, avec les limites et erreurs que vous croiserez en route. ## The short version - Gradiently propose une API de design JSON sous https://gradiently.design/api et un serveur MCP hébergé, tous deux construits sur les mêmes endpoints. - Chaque requête porte une clé API d’espace de travail, créée dans Paramètres › API et agents par un propriétaire ou un administrateur de l’espace. - Une clé fonctionne dans exactement un espace de travail, agit au nom de la personne qui l’a créée et ne peut atteindre que les endpoints autorisés par ses portées. - L’API peut chercher dans le Marché, mettre en page et modifier des créations sur le Mark d’une marque, enregistrer des copies dans d’autres tailles et rendre des créations enregistrées en PNG ou PDF. - Une clé ne peut jamais gérer des clés, accéder à la facturation, modifier le compte ou donner un Mark ; ces actions exigent toujours une personne connectée. 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](https://gradiently.design/fr/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](https://gradiently.design/fr/guide/link-preview-image), 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](https://gradiently.design/fr/guide/bulk-create-from-spreadsheet) du Studio peut faire le travail sans une ligne de code. ## API ou serveur MCP ### Serveur MCP - Pour les assistants IA compatibles avec les serveurs MCP distants. - Claude : `https://gradiently.design/api/mcp`. ChatGPT : `https://gradiently.design/api/mcp/chatgpt`. - Les outils retrouvent votre marque, enregistrent des créations et renvoient des liens vers le Studio. - Idéal pour demander du travail en langage courant. ### API HTTP - Pour les scripts, back ends et automatisations. - JSON sur HTTPS sous `https://gradiently.design/api`. - Vous choisissez la marque, envoyez le contenu et traitez chaque réponse. - Idéal quand il vous faut un résultat exact et reproductible. 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](https://gradiently.design/fr/guide/what-is-mcp) l’explique simplement, et [connecter un assistant IA](https://gradiently.design/fr/guide/connect-ai-assistant) 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. | Portée | Dans les Paramètres | Ce qu’elle autorise | | --- | --- | --- | | `designs:read` | Lire les créations | Marques, créations, vignettes, imports et rendus | | `designs:write` | Créer et modifier des créations | Créer, modifier, dupliquer et supprimer des créations, importer des images, lancer le Designer | | `marks:read` | Rechercher des Marks | Chercher dans le Marché et lire les Marks | | `marks:claim` | Réserver des Marks | Réserver un Mark disponible pour le créateur de la clé | | `brand:generate` | Générer des marques | Endpoints de génération de marque | | `workspaces:read` | Lire l’espace de travail | L’espace de travail, ses membres et son journal d’audit | | `personalities:write` | Modifier les marques | Créer, renommer et supprimer des marques, changer le Mark d’une marque | | `members:write` | Inviter des membres | Envoyer des invitations à l’espace de travail | Les huit portées. Une nouvelle clé démarre avec les cinq dont la plupart des usages ont besoin ; Réserver des Marks reste désactivé tant que vous ne le choisissez pas, car une réservation fait de vous le détenteur d’un Mark. > **Une clé est un mot de passe** Gardez-la dans une variable d’environnement ou un coffre à secrets, une clé par outil, avec le minimum de portées nécessaires. Ne mettez jamais une clé dans une page web, une application mobile ou un dépôt : Gradiently ne stocke qu’une empreinte, donc une clé divulguée doit être révoquée et remplacée. ## Votre première requête 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. **Cherchez dans le Marché** Un `GET` vers `/api/marks` avec `?q=` renvoie 24 Marks par page et un `nextCursor` pour la suivante. 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. **Rendez-la** Appelez `POST /api/designs/:id/render` avec une largeur, une hauteur et un format, puis décodez le fichier base64 renvoyé. ```bash export GRADIENTLY_API_KEY="gr_live_…" curl "https://gradiently.design/api/marks?q=deep%20teal" \ -H "Authorization: Bearer $GRADIENTLY_API_KEY" ``` Chercher dans le Marché demande `marks:read`. Les codes fonctionnent avec ou sans points, en majuscules comme en minuscules. ```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": [ … ] } ``` Dans l’API, les marques s’appellent personalities. Les mises en page incluent statement, editorial, poster, split, stat, quote, list, event et minimal. Une publication Instagram portrait avec le texte Fresh bread from 7 h et une petite ligne Visit us, sur un arrière-plan vivant en dégradé Ce que produit cette requête : les mots placés par le moteur de mise en page sur le Mark de la marque, au format portrait Instagram 1080×1350. 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](https://gradiently.design/fr/guide/copy-to-sizes) explique la recomposition. ```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 } ``` La largeur et la hauteur vont de 1 à 4096. Le rendu exige la même licence d’export pour le Mark de la création que dans le Studio ; sans elle, la réponse est 402. ## 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](https://gradiently.design/fr/guide/ai-credits-explained) détaille la dotation. | Limite | Quota | | --- | --- | | Chaque requête avec une clé | 120 par minute et par clé | | Écritures (POST, PATCH, DELETE) | 90 par minute et par compte, partagées avec l’application | | Rendus | 10 par minute et par compte | | Nouvelles créations et duplications | 60 par minute et par compte | | Imports | 60 par minute et par compte | Fenêtres glissantes d’une minute. Un dépassement renvoie 429 avec un en-tête `Retry-After` en secondes : attendez ce délai, ne réessayez pas tout de suite. 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](https://gradiently.design/fr/guide/workspace-roles). ## FAQ ### Gradiently a-t-il une API ? Oui. Il propose une API JSON sous `https://gradiently.design/api` et un serveur MCP hébergé, utilisables avec une clé API d’espace de travail ou, pour ChatGPT et Claude, une connexion OAuth. ### Qui peut créer une clé API Gradiently ? Les propriétaires et administrateurs d’un espace de travail, dans Paramètres › API et agents. La clé s’affiche une seule fois et ne fonctionne que dans cet espace. ### Puis-je rendre une création en PNG avec l’API ? Oui. `POST /api/designs/:id/render` renvoie un PNG ou un PDF en base64, jusqu’à 4096 pixels de côté, à condition de détenir la licence d’export pour le Mark de la création. ### Utiliser l’API dépense-t-il des crédits IA ? Mettre en page, modifier et rendre des créations, non. Solliciter le Designer de Gradiently via l’API ou l’outil `design` dépense les crédits IA de l’espace de travail. ### Quelles sont les limites de débit de l’API ? 120 requêtes par minute et par clé, avec des limites plus basses pour les écritures, rendus et imports. Au-delà, vous recevez un 429 avec un en-tête `Retry-After`.