---
name: motiframe
description: >-
  Génère des visuels (images PNG) à partir des templates Motiframe de
  l'utilisateur via l'API REST. À utiliser dès qu'il faut produire une image de
  marque, un visuel réseaux sociaux, une bannière, une vignette ou une
  déclinaison à partir d'un gabarit existant : lister les templates, repérer
  leurs calques modifiables, lancer un rendu en surchargeant texte/couleurs/
  images, puis inspecter visuellement le résultat et itérer.
license: MIT
---

# Motiframe — génération d'images par template

Motiframe transforme un template conçu une fois (éditeur visuel) en une API
d'images : on passe l'identifiant d'un template et des **surcharges par calque**
(texte, image, couleur…), on récupère une image finie.

Cette skill pilote l'API via un petit script `curl` : `scripts/motiframe.sh`.

## Prérequis (une seule fois)

1. L'utilisateur crée une **clé d'API** dans Motiframe : app → menu compte →
   « Clés d'API » → créer. La clé ressemble à `mf_live_…` et n'est affichée
   qu'une fois.
2. Exporter la clé dans l'environnement **avant** d'utiliser la skill :

   ```bash
   export MOTIFRAME_API_KEY="mf_live_..."
   ```

   Ne jamais écrire la clé en clair dans un fichier versionné, un message ou un
   argument de commande. La skill la lit uniquement depuis cette variable.

## Boucle de travail recommandée

Toujours procéder ainsi — c'est ce qui donne un rendu correct du premier coup,
puis ajusté visuellement comme le ferait un humain :

1. **Découvrir** les templates disponibles :

   ```bash
   scripts/motiframe.sh templates
   ```

2. **Inspecter les calques** du template choisi pour connaître les clés de
   surcharge (chaque calque a un `name` unique) :

   ```bash
   scripts/motiframe.sh layers <templateId>
   ```

3. **Générer** l'image en surchargeant les calques utiles. Les surcharges sont
   un objet JSON `{"<nom_de_calque>": { <propriétés> }}` :

   ```bash
   scripts/motiframe.sh render <templateId> \
     --overrides '{"title":{"text":"Soldes -40%"},"bg":{"fill":"#4f46e5"}}'
   ```

   Par défaut, le PNG est téléchargé en local (`motiframe-render.png`) et la
   commande affiche son chemin et ses dimensions.

4. **Inspecter visuellement** : ouvrir le fichier PNG produit et vérifier
   l'alignement, la lisibilité, les débordements de texte, le contraste. Si
   quelque chose ne va pas, ajuster les surcharges et relancer l'étape 3.

5. Quand le rendu convient, on peut soit garder le fichier, soit demander une
   **URL hébergée** (pratique pour publier ou partager) :

   ```bash
   scripts/motiframe.sh render <templateId> --overrides '{...}' --url
   ```

## Surcharges par type de calque

Les propriétés acceptées dépendent du type de calque (vu via `layers`) :

- **text** : `{ "text": "…", "color": "#fff", "fontSize": 64 }`
- **image** : `{ "src": "https://…/image.jpg" }` (URL publique en HTTPS)
- **shape** : `{ "fill": "#4f46e5" }`
- **qrcode** : `{ "value": "https://…" }`

Pour utiliser une image locale comme source, la téléverser d'abord :

```bash
scripts/motiframe.sh upload ./photo.jpg   # renvoie { "url": "https://…" }
```

puis passer cette URL comme `src` dans `--overrides`.

## Bonnes pratiques

- Ne surcharger que les calques nécessaires ; les autres gardent leur valeur du
  template.
- N'inventer ni identifiant de template ni nom de calque : toujours les obtenir
  via `templates` puis `layers`.
- Les rendus comptent dans le **quota mensuel** du plan de l'utilisateur
  (réponse `402` si la limite est atteinte) — éviter les rendus inutiles.
- `--scale` (1 à 4) augmente la résolution de sortie sans changer la mise en
  page.

## Référence rapide des commandes

| Commande | Rôle |
| --- | --- |
| `motiframe.sh check` | Vérifie la clé et la connectivité |
| `motiframe.sh templates` | Liste les templates du compte |
| `motiframe.sh template <id>` | Template complet (JSON) |
| `motiframe.sh layers <id>` | Calques = clés de surcharge |
| `motiframe.sh render <id> [opts]` | Génère une image (fichier ou `--url`) |
| `motiframe.sh upload <fichier>` | Téléverse une image, renvoie son URL |

Documentation détaillée et installation par agent : voir `README.md`.