docs(hermes-nabil): edition d'image Fal.ai + regle de journalisation des replis

2026-07-18 11:38:38 +00:00
parent 1e30454933
commit 3acecca784
1 changed files with 31 additions and 0 deletions
@@ -99,3 +99,34 @@ Image encodee en base64 inline dans le HTML : un seul fichier, pas de probleme d
 - `data/.env` est le seul fichier lu par Hermes (pas le `.env` racine).
 - Le wrapper mcp interdit `docker rm -f` : utiliser `docker compose up -d` (recreate propre) et
  `docker run --rm` pour les tests jetables.
+
+## 6. Edition d'image (Fal.ai + repli OpenRouter)
+
+`/data/nyora/nyora_image_edit.py`. Cascade **Fal.ai -> OpenRouter nano-banana**.
+
+### Fal.ai
+- Endpoint synchrone : `POST https://fal.run/<modele>`, en-tete **`Authorization: Key <FAL_KEY>`**
+  (pas `Bearer`). Reponse : `images[0].url` (URL hebergee, a telecharger).
+- L'image source passe en **data-URI base64**, pas besoin d'heberger le fichier.
+- **Piege de schema** : le nom du champ source change selon le modele —
+  `nano-banana/edit` attend `image_urls` (**tableau**), `flux-pro/kontext` et `qwen-image-edit`
+  attendent `image_url` (**chaine**). Un mauvais champ = 422.
+- Modeles : `fal-ai/nano-banana/edit` (respect fidele du sujet, fond/retouche),
+  `fal-ai/flux-pro/kontext` (edition dirigee), `fal-ai/qwen-image-edit` (texte et details).
+
+### Etat du compte (18/07/2026)
+Cle valide et authentifiee, mais les trois modeles renvoient
+**`User is locked. Reason: Exhausted balance`** -> solde Fal.ai epuise, recharge necessaire
+sur `fal.ai/dashboard/billing`. Ce n'est ni un probleme de cle ni de code.
+
+### Lecon : un repli silencieux masque un probleme de facturation
+La cascade avait fait son travail (les editions ont abouti via OpenRouter) mais **sans rien signaler** :
+les trois tests semblaient reussis alors que Fal etait mort. Correction appliquee — quand un repli
+se declenche, la raison de l'echec du backend principal est ecrite sur **stderr**
+(`AVERTISSEMENT repli sur OpenRouter — Fal indisponible : ...`).
+**Regle generale : toute cascade de backends doit journaliser pourquoi elle est descendue d'un cran.**
+
+### Consignes d'edition
+Toujours formuler en **conservant explicitement le sujet** ("garde X exactement identique"),
+sinon le modele reinvente l'image. Pour un PNG reellement transparent : sujet sur fond blanc plat
+puis detourage flood-fill PIL depuis les bords (cf [openrouter-image-gen.md](openrouter-image-gen.md)).