Pro
FR
Se connecterCompte Télécharger pour Mac
Télécharger pour Mac

Docs / API et agents

API HTTP pour agents

Ce site documente une sélection de flux de travail et de champs pris en charge, pas l’API interne complète.

Utilisez des personnages originaux ou stylisés, ou votre propre image avec un consentement documenté. Toute représentation d’une autre personne identifiable exige son consentement documenté. Respectez la Politique d’utilisation acceptable pour toutes les images de référence, les données d’entraînement, l’audio et les résultats.

Des agents externes (Claude Code, Codex, OSS, ou tout ce qui parle HTTP) pilotent Phosphene par cette API. Le chat intégré au panneau a été retiré le 2026-05-15 : il n’y a plus d’agent embarqué dans le panneau. Tout ce que le chat savait faire peut être fait par un agent externe via ces points d’accès.

Outils prêts à l’emploi construits sur cette API : la commande phosphene et un serveur MCP pour Claude Code, Codex ou n’importe quel client MCP, dans agents/. Voir Outils pour agents.

Serveur

  • URL de base : http://127.0.0.1:8198 sur une installation normale. 8199 est le port du profil DEV, et tous les exemples de cette page l’utilisent parce que c’est le panneau sur lequel ils ont été écrits. La règle tient en une ligne de la source (mlx_ltx_panel.py:275) : DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, modifiable avec LTX_PORT. Si une requête d’ici ne renvoie rien, vous parlez presque sûrement à un port sur lequel il n’y a pas de panneau : essayez l’autre.
  • Processus : mlx_ltx_panel.py (à la racine du dépôt)
  • Format d’échange : corps de POST encodés en formulaire ; les exceptions JSON sont indiquées point d’accès par point d’accès. Les réponses sont en HTTP/1.0 (le comportement par défaut de BaseHTTPRequestHandler, jamais modifié) : la connexion se ferme donc après chaque requête et il n’y a pas de keep-alive pour enchaîner des requêtes.
  • Authentification : aucune, le serveur n’écoute que sur la boucle locale.

Conventions

  • Toute réponse JSON a le type Content-Type: application/json.
  • Les erreurs renvoient {"error": "<message>"} avec un statut HTTP hors 2xx.
  • 451 licence_required (4.19.8). Une requête qui téléchargerait ou exécuterait un modèle dont la licence demande un « J’accepte » explicite (Hailuo H3 avec la MiniMax H3 Community License, et les modèles non commerciaux Ideogram 4, YuE2, FLUX.1 Krea [dev] et Bria FIBO) reçoit HTTP 451 avec {"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"} tant que cette licence n’a pas été acceptée une fois sur ce Mac. Concerne /queue/add, /queue/retry, /queue/batch, /image/generate, /h3/turbo/install, /h3/tristep/install, /music/install, /music/cover/install et /music/lora/fetch ; un travail qui arrive par une autre voie échoue avec la même phrase. Lisez les conditions avec GET /licences et acceptez avec POST /licences/accept (plus bas), ou une seule fois dans le panneau, qui affiche l’écran de lui-même.
  • L’espace de noms /agent/* est réservé et supprimé : tout chemin sous /agent/ sauf /agent/image/config renvoie 410 Gone avec {"error": "agentic flows removed; see docs/API.md"}. Les nouveaux points d’accès ne doivent pas être ajoutés sous /agent/.

Génération : soumettre et gérer les travaux

POST /queue/add : mettre un rendu vidéo en file d’attente

Ajoute un travail à la file d’attente du panneau. Répond immédiatement ; le processus auxiliaire (helper) le rend de façon asynchrone.

Champs du formulaire (tous obligatoires sauf mention contraire) :

ChampTypeNote
modet2v | i2v | extend | keyframe | a2v | v2a | imageType de travail. v2a (Ajouter du son) ne concerne que Hailuo H3.
promptstringTexte complet du prompt. Les mots déclencheurs des LoRA vont ici.
negative_promptstringFacultatif. Pris en compte uniquement là où le pipeline exécute le classifier-free guidance : high, extend, keyframe, a2v. Les chemins distillés quick / balanced / standard n’ont pas de branche de guidance et l’ignorent (ils intégraient autrefois les termes au prompt, ce qui poussait le modèle à les dessiner, #81).
width, heightintTous deux divisibles par 32.
framesintDoit vérifier frames % 8 == 1. 121 = 5 s, 169 = 7 s, 241 = 10 s.
frame_ratefloat24 par défaut. LTX est entraîné à 24 i/s ; s’en écarter dégrade la qualité.
character_strengthfloat1.0 par défaut. Intensité du LoRA de personnage, de 0 à 2.
seedint ou -1-1 = aléatoire.
qualityquick | balanced | standard | highPour un travail avec un LoRA de personnage, utilisez high. balanced envoie en silence les clips de plus de 121 images vers le transformer distillé Q4, où les LoRA actuels perdent l’identité.
stage1_steps, stage2_stepsintPipeline HQ en deux étapes. Valeurs validées par défaut : 10 / 3.
teacache_threshfloatPlateau d’accélération validé à 1.8–2.0. Sous 1.6, aucune accélération. Plus haut = mise en cache plus agressive.
cfg_scalefloatClassifier-free guidance. 3.0 est la valeur validée par défaut.
bongmath_max_iterintPlafond de la boucle interne de l’échantillonneur. 100 est le maximum amont.
upscaleoff | fit_720p | fit_1080pPost-traitement facultatif.
upscale_methodlanczos | pipersrSi upscale != off.
acceloff | (autres modes : voir la source du panneau)Réglage d’accélération.
enhancetrue | falseSi true, Gemma réécrit le prompt avant l’encodage. Mettez false quand le prompt contient des mots déclencheurs de LoRA : la réécriture peut les supprimer.
hdrtrue | falsePasse ic-lora HDR.
imagepathI2V uniquement. Chemin absolu d’un PNG/JPG de référence. Obligatoire : depuis la v4.6.1, un image omis ou vide sur i2v / i2v_clean_audio est refusé au démarrage du travail avec une erreur lisible, au lieu de prendre par défaut examples/reference.png, un fichier de démonstration qu’aucune installation n’a jamais livré (ce défaut était l’échec de rendu le plus répandu du parc : image not found: <path>, 35 événements chez 22 personnes en 14 jours). LTX_DEFAULT_IMAGE fournit toujours une valeur par défaut lorsqu’elle pointe vers un fichier qui existe vraiment.
audiopathRéférence audio facultative.
labelstringLibellé facultatif pour la carte de la file d’attente.
temporal_modenative | fps12_interp24 | windows. windows rend au-delà d’une fenêtre de 121 images comme une SÉQUENCE : un generate, puis un extend par fenêtre suivante sur la fin conservée de la précédente (ltx_windows.py : stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), puis coupé à la durée demandée. Nécessite le module Q8 et un palier qui autorise Extend ; refusé avec une phrase sinon. Stocké sur le travail sous long_mode.
window_promptsTableau JSON (ou texte séparé par des retours à la ligne) d’une ligne par fenêtre ; ligne 1 vide = le prompt ; une ligne vide plus loin garde le moment précédent. Le prompt de chaque fenêtre suivante est sa ligne EN PREMIER, puis la clause de continuation, puis Throughout: <window_invariants>. : le contrat de chaînage H3, et la règle de commencer par le mouvement.
window_invariantsCe qui ne doit pas changer entre les fenêtres (qui, où, lumière, objectif). Réinjecté dans chaque fenêtre suivante.
lorastableau encodé en JSONVoir la charge utile LoRA ci-dessous.

Hailuo H3 (engine=h3), champs 4.19. H3 rend t2v, i2v, keyframe, extend, a2v et v2a ; chaque mode au-delà de i2v demande un indicateur sur le moteur INSTALLÉ (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), et un travail pour un mode que le moteur n’a pas est rendu sur LTX avec une phrase (Ajouter du son n’a pas de voie LTX et est refusé avec la phrase de mise à jour à la place).

ChampTypeNote
h3_quality, h3_lengthstringLa cellule. h3_quality=fast_hd = la passe Fast 640×384 + Upscale & Face Fix jusqu’à 1280×768, mis en file ensemble ; Fast et la correction sont forcés.
h3_continuityon | offon par défaut : une fenêtre chaînée reprend les 17 dernières images de la précédente et leur son (--chain-context-frames 17). off = la passation par une seule image fixe.
start_image, end_image, keyframes_jsonpath / JSONmode=keyframe. Sur H3, l’image de début est facultative (une image de fin seule est la tâche « dernière image » de MiniMax) ; les temps de keyframes_json tombent à leur frame_index sur la timeline à 24 i/s.
video_path, h3_extend_secondspath / floatmode=extend : n’importe quel clip, prolongé à partir de ses 17 dernières images et de leur son ; 0,5 à 15 s ajoutées à la suite.
audio, image, frames, audio_start_time, audio_stem_automode=a2v avec engine=h3 : la piste est conservée telle quelle et l’image est rendue dessus ; frames (24 i/s) est la durée, plafonnée à l’audio restant après audio_start_time et à 30 s ; audio_stem_auto=on conditionne sur la voix séparée et livre l’original.
video_pathpathmode=v2a (Ajouter du son, H3 uniquement) : l’image du clip est conservée exactement et seul son son est généré ; jusqu’à 60 s.
h3_prompt_guards"" | off | all | liste séparée par des virgulesQuelles protections de prompt s’appliquent au texte que le moteur encode (h3_prompt_guards.py) : ellipsis, spoken, hands, nouns. Vide = l’ensemble par défaut (ellipsis, spoken, hands ; nouns est en option) ; off envoie le prompt tel quel. Les protections appliquées sont enregistrées dans h3_prompt_guards_applied ; prompt garde ce qui a été saisi.

Charge utile LoRA : le champ loras est un tableau encodé en JSON d’objets {path, strength}. Empilez-en autant que nécessaire : sur Hailuo H3, l’empilement demande l’option répétable --lora du moteur (/status.h3.loras.max_stack > 1) ; un ancien pack n’accepte qu’un adaptateur, et le champ h3_lora_slot décide s’il va vers Turbo ou vers le LoRA.

[
  {"path": "<panel-root>/mlx_models/loras/explorertrn_v2.safetensors", "strength": 1.0}
]

Retour : {"ok": true, "id": "j-<...>"} : l’ID du travail, pour le suivi.

Exemple :

curl -s -X POST http://127.0.0.1:8199/queue/add \
  --data-urlencode "mode=t2v" \
  --data-urlencode "prompt=Cinematic close-up of bizarrotrn man in a wood-paneled study, golden hour, photorealistic." \
  --data-urlencode "width=1024" --data-urlencode "height=576" \
  --data-urlencode "frames=169" --data-urlencode "steps=8" \
  --data-urlencode "quality=high" --data-urlencode "temporal_mode=native" \
  --data-urlencode "stage1_steps=10" --data-urlencode "stage2_steps=3" \
  --data-urlencode "teacache_thresh=2.0" --data-urlencode "cfg_scale=3.0" \
  --data-urlencode "bongmath_max_iter=100" --data-urlencode "accel=off" \
  --data-urlencode "enhance=false" --data-urlencode "upscale=fit_720p" \
  --data-urlencode "upscale_method=lanczos" --data-urlencode "seed=-1" \

POST /run : alias de /queue/add (comportement identique).

POST /queue/retry

Remet en file un travail de l’historique avec les mêmes paramètres. params.open_when_done est forcé à false (les nouvelles tentatives tournent en arrière-plan).

ChampTypeNote
idstringID du travail source.

Renvoie {"ok": true, "id": "<new-id>", "source_id": "<old-id>"}.

POST /queue/remove

Retire un travail en attente. (Un travail en cours ne peut pas être retiré : utilisez /stop.)

ChampTypeNote
idstringID du travail.

Renvoie {"ok": true}.

POST /queue/clear

Vide la file d’attente. Renvoie {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}. Le jeton annule CE vidage une fois, pendant 60 s (POST /queue/restore avec {"token": "<hex>"} remet exactement les travaux retirés, avec leurs ids d’origine, devant tout ce qui a été mis en file depuis). Un vidage ultérieur le remplace ; un jeton expiré ou déjà utilisé reçoit 410.

POST /queue/pause, POST /queue/resume

Met en pause ou reprend le répartiteur de la file (sans effet sur un travail déjà en cours).

POST /stop

Demande l’arrêt du travail en cours. Renvoie {"ok": true}. ?id=<job id> facultatif (ce qu’envoie le panneau) : n’arrête que si ce travail est toujours celui qui tourne, sinon 409 {"stale": true} et rien n’est arrêté. /stop/after_part prend le même id.

POST /queue/batch

Soumet plusieurs prompts en un seul lot.

ChampTypeNote
promptsstringPrompts séparés par des retours à la ligne.
(plus tous les champs standard de /queue/add, appliqués à chaque ligne)

État : suivre l’avancement des travaux

One Shot : sa propre porte d’entrée, POST /oneshot (2026-09-08)

One Shot est un onglet de flux de travail et une API à part entière. Un script envoie le même document que l’onglet (un seul objet JSON) et récupère le travail mis en file :

curl -s -X POST http://127.0.0.1:8198/oneshot -H 'Content-Type: application/json' -d '{
  "prompt": "A red vintage tram rolls through a rain-soaked Lisbon street at night; a woman with a yellow umbrella waits at the stop. The bell rings twice; rain on the roof.",
  "seconds": 60,
  "engine": "ltx",
  "quality": "balanced",
  "camera": "a slow, steady push in along the street",
  "beats": ["the tram comes round the corner", "", "the woman steps to the kerb"],
  "handoff": "last"
}'
# → {"ok": true, "id": "j-…", "plan": {"seconds": 60, "parts": 6, "beats": 12, "engine": "ltx", "handoff": "last", "minutes": 28.2, "eta": "~28 min"}}
ChampTypeDéfautSignification
promptstrobligatoireLe plan entier, une fois : qui, où, l’heure du jour et la météo, le son. Sans temps forts, il sert toutes les cinq secondes.
secondsint60L’une de ces valeurs : 30 / 45 / 60 / 90 / 120. Toute autre valeur est refusée, jamais arrondie (un 75 se rendait autrefois en un seul clip).
engineltx / h3ltxLTX rend des parties de 10 s (visages, voix, dialogue) ; H3 rend des parties de 15 s (mouvement, paysages). H3 est refusé s’il n’est pas installé.
qualitystrdéfaut du moteurLTX : quick / balanced / standard / high ; avec un personnage : draft / pro / high / high_720p ; H3 : draft / standard / high / native.
beatsliste ou texte à retours à la ligneaucunUne ligne par cinq secondes. Une ligne vide garde ce moment ; les lignes en trop sont ignorées. Absent = le prompt est chaque temps fort.
camerastr""Un mouvement pour tout le plan, sa direction et sa vitesse ; repris dans chaque partie (take_camera).
imagepathaucunUne image de départ déjà sur ce Mac : envoyez-la d’abord avec POST /upload (champ image) et passez le path renvoyé. La première partie devient i2v.
character_idstraucunUn personnage entraîné (LTX uniquement). Fixe la qualité par défaut à pro, l’export à 720p Sharp et handoff à speech. character_strength facultatif.
handofflast / speechlast (speech avec un personnage)Comment une partie passe le relais : sa dernière image, ou une image où l’on parle, avec le dernier mot reporté sur la partie suivante (voir le contrat de la prise ci-dessous).
light_lock / retakeon/offonLa phrase de continuité sur chaque temps fort ; une reprise de dérive par partie.
seed, label, no_music, turbo (H3), upscale, upscale_methodComme sur /queue/add.

GET /oneshot/options : ce que ce Mac peut faire : seconds, engines.{ltx,h3} (available, part_seconds, qualities), character_qualities, characters (id, name, trigger), planner. GET /oneshot/estimate?engine=&quality=&seconds= : parts, part_seconds, beats, minutes, eta. POST /oneshot/plan {prompt, seconds, engine} : le planificateur du Storyboard écrit un temps fort par tranche de cinq secondes à partir du prompt (blocs de 20 à 40 s) : {ok, beats:[…]}. GET /oneshot/status : current (id, label, part, parts, lipsync par partie, drift, handoff), queued, recent, et les propres lignes de log de la prise.

En coulisses, chaque One Shot suit le contrat de prise ci-dessous : POST /oneshot transpose le document dans le formulaire de make_job, si bien que l’onglet, l’API et /queue/add rendent exactement le même travail.

Une prise : take_seconds + beats sur POST /queue/add

Un clip plus long qu’une seule passe, sur l’un ou l’autre moteur. take_seconds vaut 30 / 45 / 60 / 90 / 120 ; beats est une liste JSON (ou du texte à retours à la ligne) avec un prompt par tranche de cinq secondes : un temps fort vide garde le moment précédent, les lignes en trop sont ignorées. Aucun temps fort du tout (champ absent, vide, ou uniquement des lignes vides) signifie que le prompt est chaque temps fort : le plan est le prompt tenu pendant toute la prise. Avant 4.12.1, ce cas rendait chaque fenêtre avec la phrase de maintien : une prise sur rien. La prise l’emporte sur le champ de durée propre au moteur. Sur LES DEUX moteurs, elle se rend en PARTIES chaînées par passation de dernière image : run_take_job_inner lance un rendu ordinaire par partie, chacune partant de la dernière image de la précédente (i2v, ancré), masque les parties dans la galerie et les assemble en <name>_take<seconds>s.mp4 :

moteurpartiece que fait make_jobworker
ltx10 s = deux temps forts = 241 images (une prise de 45 s se termine sur une partie d’un seul temps fort de 121 images)frames = 241, temporal_mode = native (une prise n’est jamais la chaîne de fenêtres, quoi qu’ait envoyé le formulaire)un rendu LTX ordinaire par partie via run_job_inner : la partie 1 est t2v, ou i2v à partir du propre image du travail s’il est arrivé en i2v ; chaque partie suivante est i2v à partir de la dernière image de la précédente avec i2v_reference_mode = anchor. Toute qualité ; le pack Q8 n’est nécessaire que pour une qualité HQ, comme pour un clip seul
h315 s = trois temps fortsh3_length=15s, h3_chain_prompts = les temps forts de la première partieun rendu H3 ordinaire par partie (--first-frame à partir de la dernière image précédente)

Deux champs facultatifs, tous deux on par défaut :

champoff signifie
take_light_lockla phrase de continuité (take_light_lock() : « it is still night… ») N’est PAS ajoutée aux temps forts ; take.light_lock vaut "" et un temps fort vide se maintient avec la seule phrase de maintien
take_retakeune partie dont la lumière dérive au-delà de TAKE_DRIFT_MAX est conservée telle que rendue au lieu d’être refaite une fois avec une nouvelle seed ; take.retake vaut false
take_camerafacultatif, texte libre, un mouvement pour TOUT le plan (« a slow, steady clockwise arc around the table at eye level, wide to close »). take_camera_lock() le place en tête du prompt de la partie 1 (« Camera: …; one steady move at one speed, never stops, never changes direction ») et, dans chaque partie suivante, ajoute une phrase disant que la caméra bouge déjà ainsi et continue dans la même direction à la même vitesse : la passation ancre l’image entre les parties, pas le mouvement, et la couture se voyait comme une caméra qui changeait de direction ou s’arrêtait et repartait à chaque raccord. Laissé vide, les parties suivantes reçoivent quand même la phrase de continuité générique. Enregistré sous take.camera
take_handofflast (défaut) ou speech. Avec speech, le moteur coupe chaque partie sauf la dernière sur une image où l’on PARLE : take_handoff_points() trouve où se termine la réplique (RMS audio), arrête l’image TAKE_TALKING_BACK = 0,2 s avant (la bouche encore à mi-mot, le seul ancrage mesuré qui reporte la voix sur la bouche de la partie suivante : +0.54 / +0.47 contre −0.15…−0.01 sur une bouche fermée), garde le son jusqu’à la fin de la réplique plus sa décroissance de 0,4 s, et mixe cette queue (part{k}_tail.wav, amix normalize=0) sur le début de la partie suivante (part{k+1}_lead.mp4) : un J-cut, pour que le dernier mot s’entende en entier. Écrivez le premier temps fort de chaque partie pour S’OUVRIR SUR LE SILENCE afin que la queue ait de la place. La queue silencieuse après chaque réplique est supprimée, donc la prise dure moins que sa durée nominale ; la dernière partie n’est pas rognée. Chaque partie parlée est notée par take_lipsync_score() et refaite jusqu’à TAKE_LIPSYNC_RETAKES = 2 fois avec de nouvelles seeds (ids -pNl, -pNl2) quand le score est sous TAKE_LIPSYNC_MIN = 0.20 ; le meilleur clip est gardé et son score enregistré dans job["take_lipsync"]. Enregistré sous take.handoff

params.take sur le travail : {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake} ; frames est la prise entière (seconds·24+1 sur LTX), part_frames une partie complète. Le fichier annexe de la sortie contient take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake} avec parts les fichiers de parties masqués, et image seulement quand la prise a commencé sur l’ancre de l’utilisateur. Charger les paramètres restaure une prise comme une prise.

GET /take/estimate

?engine=h3|ltx&quality=<engine quality key>&seconds=<take_seconds> → { ok, seconds, beats, parts, beats_per_part, part_frames, engine, frames, minutes, eta, needs_q8 }. parts est le nombre de parties sur les deux moteurs. Les minutes sont les parties × le prix d’un clip seul pour une partie, selon le même modèle de coût que toutes les autres estimations (H3 : la cellule mesurée de 15 s ; LTX : la cellule 10s de la qualité dans LTX_TIERS, la queue d’un seul temps fort à sa cellule 5s) ; null là où ce Mac n’a pas de chiffre. needs_q8 vaut désormais toujours false : une prise LTX se rend sur ce que la qualité choisie utilise.

GET /status

Chaque ligne de outputs[] porte q : les mots de recherche de la sortie, en minuscules, construits à partir de son fichier annexe lors du passage de listage qui le lit déjà : prompt, label, mode, qualité, moteur, personnage, seed, WxH, Nf, noms des fichiers LoRA, nom du dossier du modèle, mode temporel et windows. La zone de recherche de la galerie teste une sous-chaîne sur name + q ; chaque mot saisi doit correspondre, et saisir quelque chose fait charger les sorties plus anciennes pour que la recherche porte sur tout.

Chaque ligne vidéo porte aussi silent : true quand le clip n’a pas de son (aucune piste audio dans l’en-tête du mp4, ou une piste qui ne dépasse jamais −80 dB), false avec du son, null tant que ce n’est pas connu. La lecture de l’en-tête est immédiate ; le contrôle du niveau tourne une fois par fichier dans un fil d’arrière-plan et est mis en cache par (mtime, size) dans state/output_silence.json, donc une interrogation ne décode jamais rien. La carte de la galerie et le lecteur proposent Ajouter du son sur un clip silent quand /status.h3.video_to_audio est vrai.

Renvoie l’état complet du panneau.

{
  "running": false,
  "paused": false,
  "current": null,
  "queue": [],
  "history": [ { "id": "j-...", "status": "done", "params": {...}, "elapsed_sec": 426.1, "output_path": "...", "raw_path": "...", "error": null }, ... ],
  "log": [ "[HH:MM:SS] helper line...", ... ]
}

Sémantique des champs :

  • deferred_downloads (4.20) : { active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. Les packs qu’une installation neuve a mis en file pour après le Start (state/install_deferred.json, écrit par install.js ; required_files.json -> install.after_start). state vaut idle, starting, downloading, waiting (un autre téléchargement tient la place), waiting_disk (le panneau garde install.background_floor_gb de libre ; message dit combien libérer), retry_wait, failed ou done. Vide et idle sur toute installation que install.js n’a jamais mise en file : une installation mise à jour ne télécharge rien. download porte background: true pendant que le téléchargeur tient la place.
  • current : le travail en cours d’exécution (null au repos).
  • gpu (4.19.10) : { busy, holder, since, outside_queue } : l’unique verrou GPU du panneau. holder vaut "queue" pour le travail dans current, ou ce qui occupe le GPU hors de la file : "image" (un rendu d’Image Studio), "character_sheet", "enhance" (Améliorer le prompt), "lyrics", "update" (le script post-mise à jour). Un client qui ne doit pas interrompre un travail (arrêter ou mettre à jour le panneau) attend que current soit null, que la file soit en pause ou vide, ET que gpu.busy soit false.
  • app_models (app Mac uniquement) : le téléchargement de modèles propre à l’app : { state, packs, active, locked, done_bytes, total_bytes }. locked (4.19.10) est vrai tant que l’app tient son verrou de téléchargement (<Phosphene home>/.locks/models.lock) ; le panneau n’offre alors aucun Télécharger pour ces packs et en refuse un avec 409 app_downloading. Un second scripts/fetch_pack_release.py sur un dossier de pack déjà en cours d’écriture s’arrête sans rien toucher avec le code de sortie 75.
  • queue : travaux en attente, dans l’ordre FIFO.
  • history : travaux terminés ou échoués. Chaque entrée a status, elapsed_sec, output_path, raw_path (natif avant upscale), error.
  • log : tampon tournant des lignes stdout du helper (environ les 50 derniers travaux).

Boucle d’interrogation : GET /status toutes les 15 à 30 s. Un travail est terminé quand son status est l’un de done, failed, cancelled, stopped, error. Jusque-là, il est queued ou running.

stopped signifie que l’utilisateur a arrêté le rendu exprès (voir POST /stop?mode=early). Ce n’est pas un échec : rien n’a été enregistré parce que le clip n’a jamais été terminé, mais rien n’a mal tourné. stopped_reason porte la propre phrase du moteur.

current.progress

Présent pendant qu’un travail tourne.

{
  "pct": 41, "phase": "denoise", "phase_label": "Denoising · step 5 / 10",
  "elapsed_sec": 62, "remaining_sec": 84, "eta_sec": 146,
  "preview": {
    "url": "/image?path=…/live/preview_latest.png&t=1786…",  // cache-busted server-side
                          // /image, NOT /file: the preview lives under STATE_DIR and
                          // /file serves OUTPUT only. Writing /file here is what shipped
                          // a correct preview to a broken-image glyph in every client.
    "estimate": 4, "total": 12,
    "meaningful": true,   // THE gate — the server decides, the client renders
    "abortable": true,    // meaningful && the runner published an abort sentinel
    "saves_sec": 182      // remaining_sec at the moment it became abortable
  },
  "preview_url": "/image?path=…"  // top-level alias of preview.url, same /image
                                  // form, present only once meaningful
}

preview est absent sauf si l’aperçu en direct est activé (Réglages → Mémoire / vitesse) et que le petit décodeur est installé. meaningful est calculé côté serveur et ne doit pas être redérivé : la règle diffère selon le pipeline, estimation 6 sur 8 sur le planning distillé, dont les premières estimations ne sont encore que du bruit ; estimation 2 sur le chemin HQ en deux étapes, qui évalue deux fois le débruiteur par étape de la phase 2. Un client qui compterait les estimations devrait savoir quel planning tourne.

POST /stop?mode=early

Demande au rendu en cours de s’arrêter à la prochaine frontière de passe avant en créant un fichier sentinelle ABORT. Le moteur sort avec 75, un code distinct qui veut dire « l’utilisateur a arrêté ceci », pas un plantage, et le travail se résout en status: "stopped" sans fichier de sortie. Renvoie 404 quand rien ne tourne et 409 quand le rendu n’a pas d’aperçu en direct par lequel s’arrêter (utilisez le POST /stop brutal, qui tue le helper).

Mise en garde sur l’encodage : le tampon du journal peut contenir des caractères de contrôle littéraux venant de prompts avec retours à la ligne intégrés. Supprimez-les avant de parser le JSON :

import re, json
raw = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', ' ', raw)
data = json.loads(raw, strict=False)

LoRA

GET /loras

Renvoie {"user": [...], "curated": [...], "loras_dir": "...", ...}. Chaque entrée a id, name, path, filename, size_bytes, recommended_strength, kind (train_character pour les LoRA entraînés via le panneau ; null sinon), adapter_verdict (voir ci-dessous), et les métadonnées CivitAI si elles sont connues.

adapter_verdict : ce que ce fichier peut réellement faire

Un LoRA peut s’entraîner jusqu’au bout, écrire un safetensors valide, se charger sans avertissement, et ne rien changer du tout : les deltas appris sont numériquement trop petits pour déplacer le modèle. Tous les contrôles structurels passent, parce que chacun demande si les CLÉS tombent au bon endroit et aucun ne demande s’il y a quelque chose dedans (#61, #62).

adapter_verdict (_adapter_verdict) est lu dans le bloc adapter_strength du fichier annexe et vaut l’une de ces valeurs :

ValeurSignification
okMesuré, et le RMS du delta est dans la plage de fonctionnement.
weakMesuré, et les deltas sont égaux ou inférieurs à WEAK_DELTA_RMS (2.0e-4). Le fichier est conservé ; le rendu aura très probablement l’air sans LoRA.
unknownEntraîné par une version qui ne mesurait pas. Ce n’est pas un synonyme de weak : le silence n’est pas la faiblesse, et tout LoRA antérieur à la mesure se lit ainsi.

Toute autre valeur est ce que l’entraîneur a écrit, transmis tel quel.

Les appelants devraient signaler weak avant qu’un rendu soit dépensé pour le découvrir, et ne pas décorer unknown.

GET /train/list porte le même verdict plus adapter_advice : une phrase qui dit quoi faire, vide quand le verdict est ok ou unknown. Elle tient compte du matériel : sur un Mac de moins de 64 Go, elle ne dit pas « entraînez de nouveau en High », parce que cette machine ne peut pas atteindre la recette validée (voir la section sur le profil plus bas). L’onglet Entraîner du panneau l’affiche comme un bandeau au-dessus des pastilles de personnages entraînés et dans la ligne d’historique du travail terminé ; un verdict sur lequel l’utilisateur ne peut pas agir est une mesure, pas une réponse (#62).

GET /hf/loras

Hugging Face comme source navigable à côté de CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1. Phosphene ne nomme aucune organisation : la requête est une recherche (vide = le terme de recherche par défaut de la voie), une liste d’auteur, ou un dépôt précis ; les résultats sont triés par voie d’après le nom du dépôt et les tags, et le plus gros .safetensors de chaque dépôt avec son clip d’exemple forme un élément dans la même forme que celle qu’affiche la grille CivitAI (name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface"). Mis en cache dix minutes par voie et par requête.

POST /hf/loras/download

Formulaire repo, filename, meta (le JSON de l’élément). Télécharge via huggingface_hub (avec le jeton HF enregistré s’il existe) dans le dossier LoRA de la voie, exécute la sonde de disposition H3, et écrit le même fichier annexe qu’une installation CivitAI, plus source, hf_repo, hf_url. Renvoie { ok, skipped, name, path, sidecar_path, lane, layout, converted }.

GET /civitai/download/state · POST /civitai/download/cancel (4.18.0)

POST /civitai/download accepte un champ de formulaire facultatif token (8 à 64 caractères, A-Z a-z 0-9 _ -) choisi par l’appelant. Pendant que ce téléchargement tourne, GET /civitai/download/state?token=… renvoie { ok, state: "running"|"cancelled", bytes, total, name } (404 une fois terminé), et POST /civitai/download/cancel avec token l’arrête au prochain bloc de 256 Ko : le fichier partiel est supprimé, rien n’est enregistré, et la réponse du téléchargement lui-même est { ok: false, cancelled: true, error }. Sans jeton, un téléchargement se déroule exactement comme avant.

GET /loras/updates

Demande à CivitAI si un LoRA installé ayant un civitai_id dans son fichier annexe a une version plus récente (modelVersions[0].id ≠ le civitai_version_id du fichier annexe). Une requête par LoRA concerné ; rien n’est téléchargé.

{ "ok": true, "checked": 3,
  "items": [ { "path": "...", "name": "...", "current_version_id": 1, "latest_version_id": 2,
               "latest_version_name": "v2", "published_at": "...", "base_model": "LTXV 2.3",
               "download_url": "...",            // what /civitai/download takes
               "meta": { ... } } ],             // the sidecar the download will write
  "errors": [ { "path": "...", "error": "..." } ] }

Installer la mise à jour, c’est un POST /civitai/download ordinaire avec ce download_url + meta ; le nouveau fichier arrive à côté de l’ancien, qui reste jusqu’à sa suppression.

POST /loras/guide

Formulaire : path (un LoRA installé de GET /loras). Le modèle planificateur écrit un guide d’un paragraphe (ce que fait le LoRA, comment le prompter, une intensité de départ, avec quoi il se dispute) à partir du nom, de la description et des mots déclencheurs du fichier annexe, et l’enregistre dans le fichier annexe sous guide ; les lignes de GET /loras portent alors guide. Refusé avec 409 pendant qu’un rendu tourne (le planificateur est un modèle de 12 Md de paramètres). Renvoie { ok, guide }.

POST /loras/refresh

Réanalyse mlx_models/loras/. Renvoie la même charge utile que /loras.

POST /loras/delete

ChampTypeNote
idstringID du LoRA donné par /loras.

Supprime le fichier. Renvoie {"ok": true}.

POST /h3/loras/import

multipart/form-data. Installe un adaptateur Hailuo H3 que vous avez déjà dans la propre bibliothèque LoRA de H3 (mlx_models/hailuo-h3/loras/, ou là où le pack installé la garde). Volontairement PAS /upload : un média de référence peut être n’importe quelle image ou audio, alors qu’un adaptateur H3 doit passer le contrat de disposition du moteur avant d’apparaître dans le sélecteur.

ChampTypeNote
filefileExactement un .safetensors. Le nom de fichier est réduit à son nom de base et assaini ; il ne peut pas entrer en collision avec un fichier déjà dans la bibliothèque.

Le corps est diffusé en flux vers un dossier de transit caché, sans mise en tampon, de sorte qu’un adaptateur de plusieurs gigaoctets coûte environ 1 Mio de mémoire résidente. Content-Length est obligatoire et plafonné à H3_LORA_UPLOAD_MAX_BYTES (4 Gio).

Ce qui arrive au fichier, dans l’ordre : placé sous .import.<pid>.<tid>/<name> → _h3_lora_prepare (un repack ComfyUI voit son espace de noms diffusion_model. retiré sur place, une réécriture de l’en-tête seul) → les contrôles de charge utile et de modules cibles propres à l’import → os.replace dans la bibliothèque → JSON annexe. Un refus à n’importe quelle étape ne laisse rien derrière.

Renvoie :

{
  "ok": true,
  "path": "/abs/path/in/the/h3/library.safetensors",
  "filename": "my_lora.safetensors",
  "name": "my lora",
  "layout": "bare" | "comfyui",
  "converted": false,
  "pairs": 208,
  "recommended_strength": 1.0,
  "scale_source": "folded" | "per_module" | "uniform" | "advisory" | "none",
  "scale_evidence": "…"
}

recommended_strength est écrit dans le fichier annexe et repris par le réglage d’intensité par LoRA du sélecteur. Le chargeur H3 applique B @ A et pas d’alpha : un adaptateur dont le alpha/rank PEFT n’est pas déjà intégré à lora_B a besoin de ce nombre ici. Il est signalé, jamais utilisé comme motif de refus.

Erreurs : 411 quand Content-Length est absent ou nul, 413 quand le corps dépasse le plafond, 400 pour un mauvais fichier (mauvaise extension, vide, nom en double, disposition inutilisable, charge utile mal formée, mauvais modèle), 500 sinon. Chaque message nomme le fichier choisi par l’utilisateur.


Entraînement

POST /train/upload

Envoi multipart/form-data. Ajoute une image à un jeu de données d’entraînement : cette route prend un fichier par requête, pas un lot. Envoyez les images dans une boucle, en renvoyant le train_job_id reçu à chaque appel après le premier pour que tout le jeu aille dans un seul dossier.

ChampTypeNote
job_idstringFacultatif au PREMIER appel (un nouvel id est créé), obligatoire ensuite, pour garder le lot ensemble. Attention au nom : job_id, pas train_job_id : la réponse le renvoie sous train_job_id.
filefileExactement UN PNG/JPG/JPEG/WEBP/BMP, ou une légende .txt.

Le corps de la requête est plafonné à TRAIN_MAX_BYTES_PER_IMAGE (32 Mo). Comme ce plafond porte sur la requête entière et que la route prend un seul fichier, un corps multi-fichiers est refusé même quand chaque image est petite.

Renvoie l’état du jeu de données (train_job_id, nombre d’images, etc.).

POST /train/start

Lance l’entraînement d’un LoRA de personnage. Le panneau appelle lora_lab.train_character et renvoie les événements de progression dans STATE['log'].

ChampTypeNote
train_job_idstringDonné par /train/upload.
triggerstringJeton déclencheur, par ex. explorertrn. Doit être composé, rare et uniquement en lettres pour ne pas entrer en collision avec la langue courante : les chiffres sont découpés en jetons isolés très courants (mrz07 → m / rz / 0 / 7), et tout déclencheur qui a porté une identité ici était uniquement en lettres ; le panneau suggère <3 consonants>trn (mrztrn) et journalise une note quand un déclencheur contient des chiffres (#62). Le LoRA de personnage arrive dans mlx_models/loras/<trigger>_v2.safetensors.
presetquick | medium | highPréréglage d’hyperparamètres. Défaut modifié en v4.6.1 : l’omettre donne désormais high pour train_type=character et quick pour train_type=style (TRAIN_DEFAULT_PRESET) ; il donnait quick dans les deux cas, le palier qui n’a jamais porté une identité (#62). Voir le tableau ci-dessous : le nombre d’étapes n’est pas une constante, et sur un Mac de moins de 64 Go rien d’autre non plus.
image_countintConfirmé par le panneau à partir des images envoyées.

Remplacements avancés (tous facultatifs, ils reprennent par défaut ceux du préréglage) :

ChampType
rank, alpha, steps, lr, resolutionint / float
caption_strategyclass_word | trigger_only | auto_caption
crop_strategycenter

Renvoie {"ok": true, "id": "j-<...>"}. Suivez la progression via /status (le travail d’entraînement apparaît dans current puis dans history).

Ce que sont vraiment les préréglages

Les étapes sont dérivées, pas fixes : steps = epochs × image_count, au minimum 1 et plafonné par le max_steps du préréglage (_preset_steps_for, mlx_ltx_panel.py:1629). Le plafond fait partie du contrat du serveur : un appel d’API écrit à la main ne doit pas pouvoir mettre en file un entraînement de plusieurs milliers d’étapes sur un Mac à mémoire limitée.

Sur un Mac de 64 Go ou plus (TRAIN_PRESETS, mlx_ltx_panel.py:1558) :

presetepochsrankrésolutionmax_stepsValidé pour l’identité ?
quick3085128000Non. La pastille affiche « identité non validée ».
medium601657612000Non. Idem.
high1003251220000Oui : la recette v2 validée (Aria_v2, Bizarro_v2). Le défaut, et celui que la pastille badge « Recommandé ».

Mesuré avec lora_compat.py : les adaptateurs de rang 32 qui portent une identité se situent entre 5.4e-04 et 1.6e-03 de delta_rms ; deux exécutions quick de rang 8 de deux utilisateurs indépendants ont mesuré 1.54e-04 et 1.98e-04, toutes deux au niveau ou sous le plancher WEAK_DELTA_RMS de 2.0e-04 (#62).

Ainsi high avec 50 images fait 5000 étapes, avec 20 images 2000, avec 300 images 20000 (plafonné). Seule la recette de rang 32 a jamais été mise sous les yeux d’un humain et jugée bonne.

⚠️ Sous 64 Go, chaque préréglage est discrètement un autre préréglage

_select_train_profile (mlx_ltx_panel.py:1650) s’exécute une fois à l’import et, quand la RAM totale est 0 < ram < 64 Go, il modifie TRAIN_PRESETS et TRAIN_STYLE_PRESETS sur place. Les noms ne changent pas. Tous les chiffres, si :

presetepochsrankrésolutionmax_stepsmodules cibles
quick24384120ensemble compact
medium58384300ensemble compact
high108448500ensemble compact

make_job reproduit les mêmes limites côté serveur, donc rank / steps / resolution passés comme remplacements avancés sont eux aussi plafonnés (max_rank 8, max_resolution 448, max_steps 500) : on ne peut pas demander la recette validée sur ce matériel et l’obtenir.

C’est un compromis délibéré, et sa raison est réelle : un entraînement LoRA LTX complet en 512 px matérialise les activations de rétropropagation du transformer dev, et un Mac de 48 Go tombe dans le swap sans jamais finir. Mais soyons clairs sur ce que cela signifie : sur un Mac de moins de 64 Go, aucun préréglage n’entraîne la recette que quelqu’un a validée. Un rang 8 avec 500 étapes ou moins est exactement le régime que adapter_verdict a été conçu pour détecter ; attendez-vous donc à weak plus souvent ici, et lisez-le comme « ce matériel, cette recette » plutôt que « ce jeu de données ».

GET /status expose le profil actif sous train_profile (key : compact_training | full_training, plus label, ram_gb, max_rank, max_resolution, max_steps, note) et les tables effectives elles-mêmes sous train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Lisez-les avant de vous fier à un nom de préréglage : ce sont les valeurs après modification, donc le seul endroit où les deux tables ci-dessus se distinguent à l’exécution.

L’événement d’entraînement adapter_strength

Ce n’est pas un événement d’analytique : rien ne quitte la machine (voir docs/ANALYTICS.md pour la liste complète de ce qui sort). C’est un événement de progression dans le flux du sous-processus lora_lab, émis une fois que l’entraîneur a mesuré le fichier qu’il vient d’écrire (mlx_ltx_panel.py:18005). Le panneau journalise le RMS médian du delta, le maximum, et le nombre de modules qui portent quelque chose, puis termine le travail dans un état AVERTISSEMENT plutôt qu’un simple done quand le verdict n’est pas ok. Le verdict est écrit dans le fichier annexe du LoRA sous adapter_strength: {"verdict": …} et relu comme adapter_verdict sur /loras et /characters.

POST /train/install

Après un entraînement réussi, le LoRA est copié automatiquement dans mlx_models/loras/. Ce point d’accès sert à une réinstallation explicite ou à une actualisation des métadonnées.

POST /train/delete, POST /train/remove-image

Supprime des jeux de données d’entraînement ou des images d’entraînement individuelles.


Personnages

Découvrir et piloter les LoRA de personnages entraînés comme des bundles.

GET /characters

Renvoie {"characters": [...]}. Chaque entrée décrit un personnage découvert dans mlx_models/loras/ :

ChampTypeNote
id, triggerstringMême valeur : le jeton déclencheur rare.
name, pronoun, subject_nounstringTirés du mlx_models/characters/<trigger>/bundle.json facultatif.
face_lora_pathstringChemin absolu vers <trigger>_v2.safetensors. Toujours présent.
sample_image_urlstring | nullURL d’une image d’aperçu du jeu de données d’entraînement.
sheet_image_path, sheet_image_urlstring | nullLa planche de personnage multi-vues générée (mlx_models/characters/<trigger>/sheet.png), quand elle existe. Créée par POST /characters/<id>/sheet/generate, servie par GET /characters/<id>/sheet.

Règle de découverte : <trigger>_v2.safetensors est obligatoire ; tout le reste est facultatif.

GET /characters/<id>/preview

Sert l’image d’entraînement d’exemple du personnage (PNG/JPEG).

GET /characters/<id>/sheet

Sert le PNG de la planche de personnage générée. ?w=<px> renvoie une miniature en cache (JPEG) par la même voie de redimensionnement que /image?w=. 404 tant qu’aucune planche n’a été générée.

POST /characters/<id>/sheet/generate

Rend une planche de rotation multi-vues à partir de l’image de référence du personnage (d’abord l’avatar du bundle, puis l’image d’entraînement en repli) et la compose dans mlx_models/characters/<id>/sheet.png + un fichier annexe sheet.json (phosphene/character_sheet@1). Synchrone, comme /image/generate : l’appelant est bloqué pendant tout le rendu ; 429 quand le GPU est déjà occupé par un rendu, un entraînement ou un travail d’image (jamais mis en file).

Content-Type: application/json. Tous les champs sont facultatifs (un corps vide rend la planche par défaut à 3 vues) :

{
  "engine_override": "qwen_edit_inline",
  "views": ["front", "profile_left", "three_quarter"],
  "wardrobe": "a red flight jacket",
  "seed": -1
}

Seuls les moteurs qui respectent la référence sont acceptés (hidream_*_inline, qwen_edit_*_inline, mock_inline) : un moteur texte seul rendrait un inconnu. seed >= 0 donne à la vue i la seed seed + i, de sorte qu’une planche entière se reproduit à partir d’un seul nombre. Chaque prompt de vue verrouille la garde-robe sur la référence (« wearing exactly the same clothes as in the reference image ») ; wardrobe redit la tenue avec des mots en plus de cela. Les vues après la première enchaînent aussi la première vue rendue comme seconde référence : mesuré sur une image de référence sombre, des rendus de profil isolés réinventaient la couleur des cheveux selon les seeds et les formulations, et une vue de face propre issue du même passage réancre les attributs que la référence brute sous-spécifie. Le cadrage de chaque vue peut encore dériver (un sujet décentré dans une vue) : régénérez ou changez la seed. En cas de succès, le preview de bundle.json est dirigé vers sheet.png seulement s’il était null : un aperçu choisi à la main n’est jamais écrasé.

POST /characters/<id>/generate

Assemble la recette de production verrouillée et met en file un rendu T2V. Le point d’accès accepte prompt_body, framing, duration, quality, et un entier seed facultatif (-1 veut dire aléatoire, comme dans /queue/add). Pour des appels de relecture exacte ou de débogage, les appelants peuvent passer full_prompt plus des champs de remplacement HQ comme stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step et audio_skip_step.


Génération d’images (séparée de la vidéo)

POST /image/generate

Génère des images fixes via le moteur d’image fourni (mflux, BFL, backend factice). Modulable à chaque appel.

Content-Type: application/json. Charge utile :

{
  "prompt": "...",
  "n": 4,
  "engine_override": "mflux",
  "aspect": "1:1",
  "refs": ["/path/to/ref.png"],
  "loras": [{"path": "...", "strength": 1.0}]
}

Voir image_engine.py pour les options propres à chaque backend.

GET /agent/image/config, POST /agent/image/config

Conservés sous l’ancien chemin /agent/ pour la compatibilité avec l’interface d’Image Studio. Lisent et écrivent la configuration du moteur d’image (backend par défaut, famille mflux, clé BFL, etc.). Malgré le chemin, c’est la configuration du moteur d’image, PAS l’agent de chat supprimé.


Storyboard : planifier un film, puis le tourner

Une planche (board) est un film : un concept, une distribution, des lieux et une liste numérotée de plans. Chaque rendu qu’elle lance passe par le même contrat make_job → file d’attente que /queue/add ; aucune de ces routes n’a de chemin d’exécution privé. Les planches vivent sous state/storyboards/<board_id>/, avec storyboard.json écrit de façon atomique : les rendus durent des heures et une planche corrompue ferait perdre toute l’exécution.

Lecture

RouteRenvoie
GET /storyboard/listToutes les planches, la plus récente d’abord.
GET /storyboard/get?id=<bid>Un document de planche.
GET /storyboard/filmsLes films assemblés sur le disque : chemin du lecteur, durée, taille d’image, taille sur disque, date de création. list_outputs parcourt OUTPUT/*.mp4 sans jamais descendre dans les sous-dossiers ; sans cette route, la seule chose que la fonction produit serait la seule que l’app ne pourrait pas vous montrer.

Interrupteurs du brief (sur plan)

ChampClé de la plancheEffet
autoautoaprès le plan : rend chaque plan, monte, assemble, sans plus aucun bouton
anchor_stillsanchor_stillsavant le rendu d’un plan texte/personnage, un travail d’image ordinaire crée sa première image (still_job_id → still ; la planche du personnage sert de référence via qwen_edit_inline quand elle existe) et le clip est rendu en i2v · ancre à partir d’elle. Une image qui échoue renseigne still_error et le plan est rendu sans ancre, une seule fois
long_windowslong_windowsun plan LTX de plus de 121 images est rendu avec temporal_mode=windows (une chaîne sur le transformer dev Q8), avec le style de la planche et le lieu du plan comme window_invariants, au lieu d’être coupé pour tenir. Extend ne peut pas réinjecter une image par fenêtre, donc un long plan ancré ne l’est que par sa première fenêtre
take_secondstake_secondsune prise : le film est un seul plan de 30 / 45 / 60 / 90 / 120 s. Le planificateur écrit un temps fort par tranche de 5 s (_sb_take_concept), la planche garde UN plan avec beats (collapse_take), la carte montre les temps forts pour les modifier, et shot_to_job envoie take_seconds + beats (la prise de l’onglet Vidéo), donc le rendu est le même par les deux portes. 0 la désactive

Chaque champ n’est modifié que s’il est envoyé ; un champ absent garde la valeur de la planche.

POST /storyboard/restill : formulaire id, n, pass facultatif : oublie l’image fixe du plan n et le clip rendu à partir d’elle, active anchor_stills s’il était désactivé, et rend ce plan seul (l’image fixe d’abord, puis le clip à partir d’elle). Mêmes refus que render (planification, rendu déjà en cours).

Écriture : POST /storyboard/<action>

Le Réalisateur. plan accepte soundtrack (un fichier audio sur ce Mac) et bars_per_shot (1/2/4, défaut 2). Avec une piste, le plan est un CLIP MUSICAL : beat_map() (le même calage que celui de la Préparation de l’Éditeur) transforme les temps forts en créneaux de bars_per_shot mesures, le nombre de plans est le nombre de créneaux (les pastilles shots s’effacent ; plafonné à STORYBOARD_MAX_SHOTS avec une note), le brief du planificateur porte le bpm, la durée du créneau, une consigne d’arc et deux lois (commencer chaque description par le mouvement ; pas de dialogue, la piste remplace le son de chaque clip), et le duration_s de chaque plan planifié est son créneau plus une seconde de marge, avec slot: {start, end} sur le plan. La carte du morceau décide de la fréquence. song_map() (storyboard_edit) place des SECTIONS sur la même grille de mesures : {start, end, label, energy, brightness} avec les labels intro / verse / chorus / bridge / outro selon la position, le volume relatif et la brillance, et director_pacing() transforme bars_per_shot en un pas par section : le refrain coupe deux fois plus souvent, l’intro et l’outro deux fois moins. Chaque créneau porte sa section ; le brief dit au planificateur quels plans tombent dans quelle section et son intensité ; une piste que la carte ne sait pas lire est coupée au pas de base et le journal le dit. La planche enregistre soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections}, le premier montage automatique de l’Éditeur utilise cette piste quand la Préparation n’en a pas mis une autre en cache (le film s’ouvre donc déjà monté sur le rythme), et GET /storyboard/edit renvoie sections pour que la règle puisse dessiner l’arc. Un mauvais chemin donne un 400 avant que le planificateur ne tourne ; l’étape de planification grid est signalée pendant la lecture du rythme.

Auto. plan accepte auto=1 : quand le plan arrive, le rendu brouillon de chaque plan démarre tout seul (_sb_auto_after_plan, une fois que le planificateur a rendu la mémoire), et quand le fil de rendu se termine avec chaque plan rendu, le film est monté (_sbe_auto_edit, sur le rythme s’il y a une piste) et assemblé par le même assembleur que Render (_sb_auto_film) ; la planche enregistre auto_film. Un plan qui n’a pas été rendu laisse le film en attente et le journal dit combien. Stop arrête toujours le rendu ; le montage et le film sont les ordinaires et peuvent être remontés ensuite.

Encodé en formulaire sauf mention contraire. id est l’id de la planche partout.

ActionChampsNote
planconcept, id, notes, shots, must, engine, character_id, style, locations, wardrobePlanifier ou replanifier. 409 tant que le moteur de rendu occupe la mémoire ou que l’unique créneau du planificateur est pris. shots est respecté ou refusé, jamais remplacé en silence par un autre nombre. Une replanification MET À JOUR les lieux et la garde-robe au lieu de les écraser.
cancelidLibérer un créneau du planificateur.
saveJSON {id, board}Écrire une planche modifiée à la main.
gradeid, n, grade, noteNoter un plan.
estimateid, pass, onlyEstimation du coût et de la durée avant de dépenser.
renderid, pass, only, out, music, music_modeTourner la planche.
stopidArrêter le rendu de planche en cours.
replan-shotsid, nsRetirer au sort les plans nommés. Une réparation qui viole une loi est rejetée ; les nouveaux tirages s’insèrent dans le plan ACTUEL, pas dans l’original.
add-shotid, path
import-shotsid, from, onlyClips de RÉFÉRENCE issus d’une autre planche. La provenance (imported_from), les LIEUX d’origine et la DISTRIBUTION d’origine les accompagnent : en laisser un derrière casse quelque chose de précis. Refusé tant que le film cible est en cours de rendu.
exportid, auto_edit, music, target_seconds, music_mode
revealid, name, whatAfficher dans le Finder (macOS).
deleteid

Schéma de la planche : les champs de géographie

Un plan est composé à partir de son lieu. Depuis le 2026-08-18, un lieu peut aussi être filmé depuis plusieurs directions, ce qui fait d’un contrechamp un vrai contrechamp plutôt qu’un second lieu.

"locations": [
  {"id": "carwash", "name": "The car wash", "description": "…",
   "views": [                                  // ABSENT, never [], when there are none
     {"id": "establishing", "name": "…",
      "light": "camera left",                  // flips with the camera
      "description": "…"},                     // self-contained: readable without the floor plan
     {"id": "reverse", "name": "…",
      "light": "camera right",
      "description": "… no car in frame …"}    // says what it does NOT hold, in those words
   ]}
],
"shots": [
  {"n": 1, "location_id": "carwash",
   "view": "reverse",        // must be a view id OF that location
   "eyeline": "right",       // "left" | "right" | "lens"
   …}
]
ChampOùRègles
locations[].viewslieuListe de {id, name, light, description}. Absent, pas [], quand un lieu n’en a pas : toute planche écrite avant l’existence des vues n’a pas cette clé, et une liste vide serait une nouvelle forme sur laquelle le validateur aurait des avis sans aucun gain. Les ids suivent le même jeu de caractères que les ids de lieux.
shots[].viewplanUn id de vue appartenant au location_id de ce plan. Une vue sur un plan sans lieu, ou une vue qui n’est pas l’une de celles de ce lieu, est une erreur de validation (unknown_view) et échoue exactement comme un lieu inconnu : une vue abandonnée en silence composerait le contrechamp à partir de la description du plan d’ensemble, et la voiture que la vue devait sortir du cadre y revient sans que rien ne soit dit.
shots[].eyelineplanL’un de left, right, lens : un fait sur le CADRE, pas sur la pièce. right = les yeux partent au-delà du bord droit. Toute autre valeur est une erreur de validation (bad_eyeline).

Ce que fait le serveur avec elles. shot_scene_text injecte la description de la VUE quand un plan en nomme une et retombe sur celle du lieu sinon : une planche sans vues, ou un plan qui ne nomme aucune vue, est rendu exactement comme avant. eyeline_clause compose "his eyes fixed past the right edge of frame" au moment du rendu ; lens ne produit volontairement rien (dire à ces modèles de regarder dans l’objectif donne un jeu plus raide que le silence), et il existe pour qu’un plan puisse dire qu’il tient l’objectif, ce qui permet à la vérification des 180 degrés de distinguer « regarde la caméra » de « personne n’a rien écrit ».

La règle des 180 degrés est appliquée, pas suggérée. Après la planification, _enforce_eyelines parcourt les plans dans l’ordre à l’écran et inverse le second de deux plans adjacents qui coupent entre deux personnages différents dans le même lieu quand les deux revendiquent le même côté, et le dit dans warnings. La réparation est mécanique parce que eyeline est un champ discret avec exactement un complément : l’inverser ne peut abîmer la prose de personne. Les lois au niveau de la prose passent par un aller-retour avec le modèle, justement parce qu’elles n’ont pas cette propriété.


Éditeur : la timeline

L’Éditeur est un flux de travail de premier niveau, pas une étape du storyboard : indépendant du moteur, il s’ouvre sans qu’une planche soit en plein rendu, et son document est edit.json dans le dossier de la planche. Une piste vidéo, une voie musique. Le son de chaque clip est lié par défaut et peut être dissocié (J/L cuts) : ce n’est pas une seconde piste audio.

Lecture

RouteRenvoie
GET /storyboard/edit?id=<bid>L’arrangement. Au premier appel pour une planche, il lance le montage automatique UNE fois, le conserve dans la voie automatique et le renvoie avec generated: true. Tous les GET suivants sont une simple lecture de fichier. Un edit.json corrompu renvoie 500 avec corrupt: true et n’est jamais remplacé en silence : ce serait jeter l’arrangement dont il est une copie cassée.
GET /storyboard/edit/status?id=<bid>L’état du travail de préparation.
GET /storyboard/edit/peaks?id=<bid>La forme d’onde. Des centaines de Ko : à récupérer une fois, jamais dans une boucle d’interrogation. 404 tant que prepare n’a pas tourné.
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4Une vidéo proxy, servie avec prise en charge des plages d’octets. Safari ne se déplace pas dans une <video> dont le serveur répond un simple 200, ce qui annulerait toute la raison d’être des proxys. name doit correspondre à [A-Za-z0-9._-]{1,120}\.mp4 : c’est un nom de base créé par le serveur, donc toute autre chose est une sonde.
GET /storyboard/edit/uploadsLes vidéos que l’utilisateur a apportées (panel_uploads/timeline/, les plus récentes d’abord, plafonné à 200). Gardées hors d’OUTPUT volontairement, ce qui explique qu’elles aient besoin d’une route ; les images n’en ont pas besoin, elles arrivent dans la bibliothèque que la galerie parcourt déjà.
GET /storyboard/edit/sounds?id=<bid>La source Son du pool de médias : {sounds: [{path, name, where, mtime}], dir} : d’abord le propre dossier audio/ du film (where: "film"), puis les fichiers son (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) à la racine d’OUTPUT, les plus récents d’abord, plafonné à 300. Aucune analyse ; la durée est lue quand un son est ajouté.
GET /storyboard/edit/drafts?id=<bid>{active, drafts: [...], backup} : voir Brouillons plus bas.
GET /storyboard/edit/versions?id=<bid>Métadonnées seulement : nom, révision, date de sauvegarde, nombre de clips, durée, plus keep (= EDIT_HISTORY_KEEP, 50). Les documents eux-mêmes ne sont lus qu’une fois, par restore, sur ordre de l’utilisateur. Ouvrir le panneau ne doit pas être un téléchargement.

Écriture : POST /storyboard/edit/<sub>

Sous-routeChampsNote
prepareid, music, target_secondsConstruit les proxys et les crêtes. 400 si music n’est pas un fichier.
add-clipid, from, only, path, title, kindkind vaut video | still | slug : le passer évite qu’une image n’arrive comme une vidéo sans image.
add-soundid, pathUn fichier pour une piste audio : analysé ({path, title, duration_s, has_video, imported}), 400 s’il ne porte aucun son. Un fichier hors d’OUTPUT est lié en dur (copié entre volumes) dans le propre dossier audio/ du film d’abord, parce que /file ne sert qu’OUTPUT et qu’un son que l’aperçu ne peut pas lire n’est qu’un demi-son. La bande est placée et enregistrée par le client.
relinkid, onlyRepointe les clips vers leurs fichiers terminés (de livraison). Une REPRISE terminée ne fait jamais partie de ce lot : elle est proposée face à son clip avec retake: true dans les lignes relink de la charge utile et adoptée clip par clip avec only=<clip id>.
cancelidAnnuler le travail de préparation.
autoid, music, target_seconds, min_shot, max_shotRelancer le montage de la machine. Arrive dans la voie automatique.
saveJSON {id, edit, expect_revision?}Voir ci-dessous.
draftid, op, slug, name, fromVoir Brouillons.
backupJSON {id, edit}La voie discrète. Voir Brouillons.
recoveridAdopter la sauvegarde en attente.
discard-backupidLa jeter.
versionid, labelNommer une version. Nommer n’est pas enregistrer : pas d’incrément de révision, pas d’écriture dans edit.json, rien ne change dans la timeline, ce qui explique précisément qu’on puisse l’actionner à tout moment.
restoreid, fileRestaurer une entrée de l’historique. Refusé pendant le rendu du film.
renderid, out, music, music_mode, format, sizeAssembler le film. music_mode vaut replace | under. Livrer en : format vaut h264 (défaut, le préréglage du panneau) | hevc (VideoToolbox, hvc1, environ moitié moins d’octets) | prores (422 HQ, 10 bits 4:2:2, son PCM, un .mov qu’aucun navigateur ne prévisualise) ; size vaut native (tel que monté) | 1080p | 2160p : une mise à l’échelle Lanczos après les incrustations, uniquement vers le haut, jamais un recadrage, ignorée quand le montage a déjà cette hauteur. finish vaut none | grain | heavy_grain : un grain de film animé (noise t+u, intensité 9 / 18) ajouté APRÈS la taille, de sorte qu’une livraison 4K reçoive un grain 4K ; un traitement de livraison, jamais dans le document, jamais dans l’aperçu ni l’export. Une autre livraison est un autre fichier : <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. Les faits portent deliver: {format, size, finish, label}.
export-nleidXML FCP7 + JSX After Effects + médias liés.
revealid, whatAfficher dans le Finder.
generateid, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_ofTourner un nouveau clip directement dans un créneau. Avec retake_of=<clip id>, c’est une reprise : le propre plan du clip est CLONÉ (personnage, références, lieu, moteur) et seuls le prompt, la durée et la seed changent ; le nouveau plan porte edit_slot.retake_of, et quand il est rendu l’Éditeur le propose face à ce clip (« Use it » / « Keep the old one »). 400 si le clip n’est plus sur la timeline.

Sémantique de save. revision est le compteur du serveur, pris sur le disque, jamais ce dont le client se souvenait : un onglet périmé ne doit pas pouvoir le faire reculer. Passez expect_revision pour apprendre que vous avez été dépassé au lieu d’écraser en silence l’autre onglet : une différence renvoie 409 avec conflict: true et la révision actuelle. Les erreurs de validation reviennent toutes à la fois (errors: [...], 400) avec le fichier sur disque intact, pour qu’un client puisse surligner chaque mauvais clip en une passe au lieu de jouer à la taupe.

Schéma de edit.json

version vaut 2 (EDIT_VERSION). La version 1 est mise à niveau uniquement à la LECTURE (migrate_edit) : augmenter la version sans mise à niveau au chemin de lecture ne refuserait pas les anciennes versions, cela refuserait chaque timeline que quelqu’un possède déjà. Une version venue du futur est laissée telle quelle pour que le validateur puisse dire la vérité.

{
  "version": 2,
  "board_id": "sb_…",
  "revision": 17,
  "origin": "manual",          // "manual" | "auto" | "backup" — who asked for this save
  "updated_at": 1786…,
  "duration": 43.5,
  "clips": [ /* below */ ],
  "audio": { /* below */ },
  "beats": null,
  "settings": {}
}

clips[]

ChampNote
id, path, proxypath/proxy valent null sur un slug.
start, endLa fenêtre À L’INTÉRIEUR de la source.
film_start, film_endLe créneau sur le film. Jamais indépendants : un clip se lit à 1x, donc film_end - film_start == end - start à LENGTH_TOLERANCE près (2 ms).
kindvideo (absent signifie video : l’inscrire sur 400 clips réécrirait chaque edit.json de la machine pour dire ce que son absence dit déjà), still (tenu pendant la durée de son créneau ; start/end sont synthétisés à partir du créneau, duration: null), slug (noir, sans fichier).
sourceauto | human.
lockedbool.
adjust{brightness}, un décalage additif eq=brightness de ffmpeg limité à ±BRIGHTNESS_LIMIT (0.5). Neutre = absent : remettre le curseur à zéro laisse un document identique à celui qui n’a jamais eu de curseur.
frame{zoom, x, y} : un recadrage. L’image est agrandie zoom fois (1 à 3) et la fenêtre est centrée à la fraction (x, y) de la source. Rendu : un crop des propres pixels de la source avant l’ajustement, donc une seule chaîne convient à toutes les tailles ; aperçu : une échelle CSS autour du même ancrage (approximatif) ; export : Basic Motion de FCP7 (échelle + centre) et échelle + position d’AE. Neutre = absent ; un slug n’a rien à recadrer.
speedVitesse de lecture, SPEED_MIN à SPEED_MAX (0.25 à 4.0), vidéo uniquement. Le créneau vaut (end - start) / speed, donc la règle du 1x ci-dessus se lit « à sa vitesse ». L’image passe par setpts, le son par atempo enchaîné au-delà de la plage 0.5 à 2.0 de ffmpeg, et l’enveloppe du son (afx) reste sur l’horloge JOUÉE de la bande : un point clé à 2 s reste à 2 s de la bande après un changement de vitesse. Absent = 1x. Jamais défini automatiquement.
audioLe montage décalé. Voir ci-dessous.

clip.audio : le J-cut et le L-cut

"audio": {"start": 3.5, "end": 7.0, "film_start": 12.25}

Clips vidéo uniquement. Les trois mêmes nombres que pour l’image, pour le SON : le son peut ainsi commencer avant son image (J) ou la dépasser (L), ce qui fait qu’une coupe cesse d’être un raccord sec.

Absent signifie lié, et c’est toute la migration : chaque clip jamais écrit n’a pas de clé audio et chacun joue son propre son sous sa propre image. EDIT_VERSION n’a pas bougé pour cela et aucun document n’a été réécrit.

C’est la PRÉSENCE du champ qui fait office d’interrupteur, pas les valeurs qu’il contient. Ne déduisez pas « lié » de l’égalité de audio avec la fenêtre de l’image : dissocier écrit la fenêtre que le clip a déjà, donc un clip que l’utilisateur vient de dissocier se lirait comme lié et refuserait d’être déplacé. La bascule ajoute l’objet ou le supprime ; rien d’autre ne décide. normalise_edit arrondit le champ mais ne le supprime jamais, pour la même raison, et le retire entièrement d’un still ou d’un slug.

Les fenêtres audio ne peuvent pas se chevaucher, pas plus que les images. Un montage décalé est un raccord sec qui atterrit ailleurs, pas un mixage : le mixage, c’est le rôle de audio_tracks.

audio_tracks[] : A3, A4, … sous la musique

"audio_tracks": [
  {"id": "t…", "name": "Laughs", "muted": true, "gain": 0.8,
   "strips": [{"id": "k…", "path": "/…/laugh.wav", "start": 0.0, "end": 2.0,
               "film_start": 12.5, "duration": 4.1, "gain": 0.5,
               "muted": true, "locked": true, "title": "laugh (copy)",
               "afx": {"fade_in": 0.5, "fade_out": 0.25, "points": [[1.0, 0.6]]}}]}]

N’importe quel nombre de pistes, chacune avec n’importe quel nombre de bandes. start/end sont les points d’entrée et de sortie dans le fichier (une bande se lit à 1x, donc sa longueur sur le film est end - start) ; film_start est une seconde de la timeline, placée avec adelay exactement comme le lit de musique. afx est le même objet d’enveloppe que portent le son d’un clip et le lit de musique, lu par audio_gain_points ; le gain de la bande et le gain de la piste (linéaire 0 à 1) le multiplient : track_strip_gain_points est l’unique courbe que lisent l’aperçu, le rendu et l’export. Absent = aucun et neutre = absent : un montage sans pistes n’a pas cette clé, il se charge, s’enregistre et se rend donc octet pour octet à l’identique ; une piste vide est conservée.

Les bandes d’une même piste ne peuvent pas se chevaucher (audio_track_strips_overlap, une erreur, avec TOUCH_TOLERANCE pour un raccord sec) ; les bandes de pistes différentes se chevauchent et se mixent. Erreurs de forme : audio_tracks_shape, audio_track_shape, audio_track_name, audio_track_muted, audio_track_gain(_range), audio_track_strips, track_strip_shape, track_strip_path, track_strip_start, track_strip_end, track_strip_film_start, track_strip_window, track_strip_past_the_end, track_strip_gain(_range), track_strip_muted, track_strip_locked, track_strip_title, track_strip_afx*.

Rendu : chaque bande audible (non muette, piste non muette, courbe non silencieuse) est un -vn -i après les incrustations, atrim → volume (sa courbe, sur l’horloge de la bande) → aresample → adelay (en échantillons) → apad → atrim au film, et toutes sont mixées par amix (normalize=0, duration=first) avec le son des clips et le lit de musique sous l’unique limiteur asoftclip ; les faits du film portent sound_strips et mix_peak. Une bande dont le fichier a disparu fait refuser le rendu, avec son chemin et sa piste. Export : chaque piste devient sa propre piste audio FCP7 (clipitems avec entrée/sortie, points clés de niveau, <enabled>FALSE</enabled> pour une sourdine) et chaque bande un calque After Effects nommé <track> · <title>.

transitions[] : un objet typé qui possède une FRONTIÈRE

"transitions": [{"id": "t1", "after_clip": "<clip id>",
                 "kind": "dissolve" | "fade_black", "duration": 0.5}]

Un fondu enchaîné, ce sont deux clips dans la même seconde, et la règle de la voie image, un seul clip à la fois (clips_overlap), est porteuse : une transition n’est donc pas un chevauchement. Elle nomme le clip SORTANT et se place sur la coupe entre lui et son successeur dans l’ordre du film ; une par frontière. Les propres film_start/film_end des clips ne bougent pas et le film garde exactement la durée que dit la timeline. Le rendu prend la moitié de la durée en queue supplémentaire au-delà du point de sortie du clip sortant et la moitié en tête supplémentaire avant le point d’entrée du clip entrant (de la matière source que les coupes ont laissée), scinde la concaténation de l’image à la frontière et joint les deux tronçons avec xfade (fade / fadeblack) centré sur la coupe. Le son n’a besoin de rien de nouveau : il suit le chemin de la voie (_sb_split_audio_plan) exactement comme un J-cut.

duration est bornée à chaque lecture (transition_duration) à min(asked, half the shorter neighbour, 2.0 s) et alignée sur un nombre pair d’images ; le document garde le nombre saisi. Un côté sans matière disponible est refusé : transition_no_handles nomme le côté et le manque (« clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there »). Chaque code de transition (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) est une erreur ; aucun n’est dans WARNING_CODES. render refuse avec la même phrase. Un still et un slug ont toute la matière qu’on pourrait leur demander.

overlays[] : cartons, caches et titres

kind vaut still | video | text. Un kind explicite l’emporte ; sans lui, le suffixe du chemin décide (.png/.webp/.tif sont des stills), donc chaque incrustation écrite avant l’existence des titres se lit comme avant. Un titre est une incrustation dont le rendu dessine les pixels :

{"id": "o1", "kind": "text", "text": "FIN", "film_start": 40.0, "film_end": 44.0,
 "style": {"font_size": 96, "color": "#ffffff", "align": "center", "x": 0.5, "y": 0.8,
           "box": true, "box_color": "#000000", "box_opacity": 0.5},
 "fx": {"fade_in": 0.5, "fade_out": 0.5}}

font_size est en px sur une image de 1080 de haut et suit l’échelle du film ; x/y sont l’ancrage en fractions de l’image ; align dit quel bord du texte se pose sur x. overlay_text() est l’unique accesseur et le style n’est écrit que là où il diffère des valeurs par défaut. La police est un FICHIER : LTX_TITLE_FONT, sinon la première de TITLE_FONT_CANDIDATES présente sur la machine, vérifiée avant la construction de ffmpeg ; sans aucune, render répond 400 avec une phrase plutôt que de produire un film troué. La trame est un PNG RGBA de la taille de l’image, à côté du film (.titles/), passé dans la même chaîne d’incrustation qu’un carton importé, donc un titre hérite de l’alpha, des fondus et de l’ordre de superposition de la voie. Les titres sont dessinés sur la scène dans le DOM au même ancrage et à la même taille ; ils ne voyagent pas dans l’export NLE (pas de chemin).

audio : la bande-son, comme objet sur la timeline

"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
          "offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
ChampSignification
offsetLa seconde de la PISTE qui joue à l’instant 0 du film. C’est ce qu’il signifie depuis avant l’existence de l’éditeur, donc tous les documents sur disque continuent de fonctionner. Il peut désormais être négatif : la piste commence -offset secondes dans le film, avec du silence devant.
trim_start / trim_endPoints d’entrée et de sortie À L’INTÉRIEUR de la piste, en secondes de piste. Absent signifie non coupé, ce qui explique qu’un edit.json écrit avant reste valide : pas de champ, pas de coupe, même graphe de filtres. Une coupe à la fin de la piste ou au-delà n’est pas une coupe, et normalise_edit la supprime : une poignée ramenée tout au bout laisse un graphe identique octet pour octet.

music_window(audio, duration=…) est l’unique endroit où ces valeurs deviennent les nombres dont ffmpeg et chaque exporteur ont besoin : start = max(trim_start, offset) (une coupe de tête et un décalage positif sont le même geste vu de deux directions ; celui qui coupe le plus l’emporte), end ou None pour « jouer jusqu’à la fin », et delay/film_start = start - offset. Couper le bord gauche ne fait pas glisser le reste de la piste plus tôt (ce serait un ripple, et la musique ne fait pas de ripple) : les secondes qu’une coupe de tête retire reviennent donc sous forme de silence devant. Une fenêtre que les coupes ferment entièrement renvoie « pas de musique » plutôt qu’un atrim de durée nulle que ffmpeg refuse.

Brouillons, sauvegardes et historique : trois choses différentes

Les brouillons sont des variantes nommées du même film, dans drafts/ avec un index.json qui nomme le brouillon actif. Une planche qui n’a que edit.json a exactement un brouillon et en a toujours eu un ; il n’avait simplement pas de nom. load_draft_index le nomme à la volée plutôt que dans une passe de réécriture, pour que la mise à niveau ne puisse pas se faire à moitié.

POST /storyboard/edit/draft est une seule route avec cinq verbes : ce sont cinq modifications du même pointeur actif, et les séparer donnerait cinq endroits où ce pointeur peut être faux :

opChamps supplémentairesEffet
newname, from=currentNouveau brouillon, vide ou copié de ce qui est à l’écran. Il devient actif.
duplicateslug, name
renameslug, name
deleteslug
activateslugMet d’abord de côté le brouillon actif actuel : il n’est jamais perdu.

new, duplicate, delete et activate renvoient 409 avec busy: true pendant que ce film est en rendu : le rendu lit ce document clip par clip, et échanger la timeline sous ses pieds présente le même danger que ce que refusent import-shots et restore.

La sauvegarde est la nôtre, l’enregistrement est celui de l’utilisateur. POST /storyboard/edit/backup écrit history/backup-<draft>.json et rien d’autre : pas d’edit.json, pas de révision, pas de contrôle de conflit. Le brouillon enregistré de l’utilisateur reste exactement ce qu’il a enregistré en dernier. Il est exposé par GET …/drafts sous backup et proposé, jamais appliqué : recover l’adopte, discard-backup le jette.

L’historique, ce sont deux voies plus une voie de conservation, distinguées par le préfixe du nom de fichier plutôt qu’en ouvrant les fichiers : un nettoyage qui doit lire cinquante documents pour décider quoi supprimer échoue à mi-chemin au premier document corrompu :

PréfixeQuoiNettoyé ?
edit-r*Un instantané automatique.Oui, plafonné à EDIT_HISTORY_KEEP (50).
save-r*Un enregistrement que l’utilisateur a déclenché.Jamais.
keep-r*Une version que l’utilisateur a nommée (version).Jamais.

Chaque enregistrement archive son prédécesseur avant que le nouveau document n’arrive (~5 Ko chacun). L’échec de l’historique ne doit jamais bloquer un enregistrement : perdre une miette de pain n’est rien à côté du refus de conserver l’arrangement à l’écran. origin est aussi estampillé dans le JSON, pour tout ce qui lit un fichier isolément.


Gestion des sorties

POST /output/delete

ChampTypeNote
pathstringDoit être sous mlx_outputs/.

POST /output/hide, POST /output/show, POST /output/show_all

Masque ou réaffiche des sorties dans la galerie sans supprimer le fichier.

POST /output/open_folder

Ouvre dans le Finder le dossier qui contient la sortie (Mac).


Licences des modèles (4.19.8)

GET /licences

Chaque licence sur laquelle le panneau pose la question, avec l’état d’acceptation de ce Mac : {"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Clés : h3, ideogram4, yue2, flux1_dev, fibo. L’entrée de H3 porte aussi territory_notice, excluded_territories, report_line, report_url et credit_line.

POST /licences/accept

Champs de formulaire key=<licence key> et accept=1 (la case que l’utilisateur a cochée). Enregistre l’acceptation pour la version actuelle de la licence dans state/model_licences.json (plus un fichier marqueur que l’installateur H3 lit) et renvoie {"ok": true, "key": ..., "record": {...}, "licence": {...}}. Une version de licence modifiée redemande. Accepter au nom de quelqu’un, c’est accepter pour lui : un agent doit d’abord montrer à l’utilisateur les conditions issues de GET /licences.

Helper / système

POST /helper/restart

Redémarre le sous-processus helper préchauffé (utilisé après des changements de réglages qui demandent un processus neuf).

POST /stop_comfy

Arrête un processus ComfyUI si Phosphene en a démarré un.

GET /version/check, POST /version/pull

Mise à jour automatique depuis le dépôt GitHub. /version/pull n’est qu’un git pull : il n’exécute pas scripts/post_update.sh, donc tout ce qu’une mise à jour installe (nouveaux paquets, modèles) n’est pas installé par lui. Depuis 4.17.4, le panneau installe lui-même un séparateur de voix de synchronisation labiale manquant au démarrage suivant (voir /a2v/separator).

POST /engine/repair

Relance uniquement l’étape d’environnement du moteur (scripts/pinokio/ltx_engine_env.sh, la même que celle d’Install) : réinstalle les paquets Python du moteur de rendu dans son venv, en arrière-plan. Aucun téléchargement, aucune reconstruction du venv, aucun Stop. Répond 202 (démarré), 200 {nothing_to_do} (le moteur va bien) ou 409 (une réparation est en cours, ou installing: true : l’Install de Pinokio écrit encore le venv). La progression et le résultat passent par GET /status -> engine_env (ok, fault, installing, repair.{state, active, log, error}).

POST /h3/repair

4.19.5. Relance uniquement scripts/pinokio/h3_deps.sh sur l’extraction Hailuo H3 : réinstalle les paquets Python de H3 dans son propre venv à l’ensemble avec lequel cette version a été testée (scripts/pinokio/h3_constraints.txt, passé avec -c ; uv ramène tout ce qui est hors de cet ensemble). Pas de modèles, pas de Stop : le panneau n’importe jamais le venv H3. Répond 202 (démarré) ou 409 (H3 n’est pas installé, un rendu H3 est en cours, ou une réparation est déjà en cours). La progression et le résultat passent par GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Un rendu H3 sur un venv hors de l’ensemble est refusé dès son démarrage avec H3 cannot start: the Hailuo H3 venv ... et cette réparation sur la carte.

Alertes push : l’alerte de fin pour un onglet fermé

Le carillon dans l’onglet et l’alerte du navigateur (Réglages → Alertes de fin) demandent que la page soit ouverte. Web Push, non : le navigateur garde un abonnement pour cette origine, le panneau signe chaque message avec une paire de clés VAPID qu’il génère une fois (state/vapid.json), et le service push du navigateur réveille /sw.js pour afficher la notification. Pas de relais : le panneau poste directement chez l’éditeur du navigateur. Proposé uniquement quand pywebpush s’importe (GET /settings → push_available).

RouteQuoi
GET /sw.jsle service worker, servi depuis la portée racine avec Service-Worker-Allowed: /
GET /push/key{ ok, available, public_key, subscriptions } : la clé publique VAPID avec laquelle le navigateur s’abonne (503 si indisponible)
POST /push/subscribeformulaire subscription = le JSON PushSubscription ; une entrée par point d’accès
POST /push/unsubscribeformulaire endpoint
POST /push/testenvoie « This is what a finished render will say. » à chaque abonné ; { ok, sent }

Chaque travail qui se termine en done ou failed envoie Phosphene — render done / — a render failed avec le libellé du travail (ou les 60 premiers caractères de son prompt), hors du verrou GPU, uniquement quand notify_done est activé. Un abonnement que l’éditeur signale disparu (404 / 410) est supprimé.

POST /settings

ChampTypeNote
(n’importe quelle clé de réglage)stringVoir state/panel_settings.json pour l’ensemble de référence.
notify_done1/0Alertes de fin : un carillon dans l’onglet quand un rendu se termine ou échoue, et une notification du navigateur quand l’onglet est en arrière-plan et que la personne les a autorisées. Activé par défaut ; GET /settings le renvoie.

POST /prompt/enhance

Encodé en formulaire. Réécrit un prompt en amont avec Gemma. Utilisé par les boutons Améliorer du panneau (Vidéo et synchronisation labiale).

ChampNote
promptobligatoire
modet2v (défaut), i2v ou a2v (synchronisation labiale : le prompt d’aide i2v plus la loi de prompt de synchronisation labiale)
preserve_tokensliste JSON (ou liste séparée par des virgules) de mots que le résultat doit conserver, à la casse exacte : les mots déclencheurs
translate0 garde un prompt en écriture non latine dans sa propre langue ; par défaut il est traduit en anglais
loras4.18.0 : liste JSON des chemins des LoRA installés sur le rendu. Le panneau lit le nom, les mots déclencheurs et le guide de chacun (sinon la description du créateur) dans la bibliothèque LoRA ; les chemins qu’elle ne liste pas sont ignorés ; il en transmet au plus 4, bornés, au helper sous forme de texte de référence délimité. Un LoRA dont tous les mots déclencheurs manquent dans le résultat voit son premier déclencheur remis en tête.

Renvoie { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] } ; { error } avec 409 pendant qu’un rendu occupe le GPU.

409 needs_pack (4.20). Enhance tourne sur Gemma 3, qu’une installation neuve télécharge en arrière-plan après le premier démarrage (voir deferred_downloads sous GET /status). Tant qu’il n’est pas sur le disque, la route répond 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state } avec pack_state valant downloading, queued, waiting_disk ou missing, et ne demande jamais au helper de le charger. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan et /train/auto-caption répondent la même forme pour la même raison. POST /models/download repo_key=<needs_pack> le télécharge maintenant : tant que le téléchargeur d’arrière-plan tient la place de téléchargement, cela répond 202 { queued: true } et place le pack en tête de la file ({ already: true } quand c’est celui qui se télécharge).

POST /upload

multipart/form-data. Envoie une image de référence pour les modes I2V ou images clés. Renvoie {"path": "<absolute path under panel_uploads/>"}.


Format JSON du fichier annexe

Chaque clip terminé écrit un fichier annexe <output>.mp4.json à côté du MP4. Schéma (simplifié) :

{
  "output": "/abs/path/to/clip_720p.mp4",
  "raw_output": "/abs/path/to/clip.mp4",
  "params": { /* the full params from /queue/add, plus seed_used, model, etc. */ },
  "command": "helper",
  "started": "YYYY-MM-DD HH:MM:SS",
  "elapsed_sec": 426.13,
  "video_duration_sec": 7.0,
  "fps": 24,
  "model": "mlx_models/ltx-2.5-mlx-q4",
  "queue_id": "j-<...>",
  "helper_elapsed_sec": 425.5,
  "output_codec": { "preset": "standard", "pix_fmt": "yuv420p", "crf": "18" },
  "memory_policy": { "requested": "auto", "effective": "auto", "frames": 169, "tier": "standard", "pressure_pct": 30, "swap_gb": 3.9 }
}

Lisez les fichiers annexes pour comparer des exécutions sans réinterroger le panneau.


Recette de production (validée le 2026-05-15)

Pour le travail vidéo avec LoRA de personnage, la recette verrouillée validée :

mode:               t2v
width × height:     1024 × 576   (also validated: 736 × 416 for ~2× faster wall)
frames:             169 (7s) / 241 (10s) / 361 (15s)
quality:            high          ← CRITICAL — forces Q8 dev transformer
temporal_mode:      native
stage1_steps:       10
stage2_steps:       3
teacache_thresh:    1.8–2.0       (plateau speedup; below 1.6 = no speedup)
cfg_scale:          3.0
bongmath_max_iter:  100
upscale:            off | fit_720p (lanczos)
accel:              off
enhance:            false         ← critical when trigger words are in the prompt
seed:               42 for A/B, -1 for production variety
LoRAs:              <trigger>_v2.safetensors @ 1.0

Durée réelle sur un M4 Max 64 Go : ~7:06 par clip de 7 s en 1024×576, ~3:24 en 736×416.


Exemple complet : un pilote d’agent

Soumet un clip avec deux LoRA, interroge jusqu’à la fin, affiche le chemin de sortie. Bibliothèque standard uniquement.

import json, time, re, urllib.parse, urllib.request

PANEL = "http://127.0.0.1:8199"

def submit(prompt, loras, **overrides):
    form = {
        "mode": "t2v",
        "prompt": prompt,
        "width": "1024", "height": "576", "frames": "169", "steps": "8",
        "seed": "-1",
        "quality": "high", "temporal_mode": "native",
        "stage1_steps": "10", "stage2_steps": "3",
        "teacache_thresh": "1.8", "cfg_scale": "3.0",
        "bongmath_max_iter": "100", "accel": "off",
        "enhance": "false",
        "upscale": "fit_720p", "upscale_method": "lanczos",
        "loras": json.dumps(loras),
    }
    form.update({k: str(v) for k, v in overrides.items()})
    data = urllib.parse.urlencode(form).encode()
    req = urllib.request.Request(f"{PANEL}/queue/add", data=data, method="POST")
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.loads(resp.read())["id"]

def wait_terminal(job_id, timeout=1800):
    deadline = time.time() + timeout
    while time.time() < deadline:
        with urllib.request.urlopen(f"{PANEL}/status", timeout=15) as resp:
            raw = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", " ", resp.read().decode())
        d = json.loads(raw, strict=False)
        for src in ([d.get("current")] if d.get("current") else [], d.get("queue") or [], d.get("history") or []):
            for j in src:
                if not j or j.get("id") != job_id:
                    continue
                st = j.get("status")
                if st in ("done", "failed", "cancelled", "error"):
                    return j
        time.sleep(20)
    raise TimeoutError(f"job {job_id} did not finish")

if __name__ == "__main__":
    # Adjust to wherever your Phosphene install lives:
    LORAS_DIR = "<panel-root>/mlx_models/loras"
    job_id = submit(
        prompt="An original illustrated explorer in a wood-paneled study, storybook illustration.",
        loras=[
            {"path": f"{LORAS_DIR}/explorertrn_v2.safetensors", "strength": 1.0},
        ],
    )
    print(f"queued: {job_id}")
    result = wait_terminal(job_id)
    print(f"status={result['status']} wall={result['elapsed_sec']}s output={result.get('output_path')}")

Voilà le schéma complet : soumettre → interroger → lire le chemin de sortie.


Ce qui a été retiré (et ce qui l’a remplacé)

La fonction de flux agentiques intégrés au panneau (planificateur de plans piloté par chat) a été retirée le 2026-05-15. Un instantané d’avant le retrait est conservé durablement sur GitHub sous le tag pre-agent-removal-2026-05-15.

Tout ce que faisait le chat (planifier plusieurs plans, générer des images d’ancrage candidates, rendre de l’I2V conditionné par ces ancres, gérer des sessions) est réalisable par un agent externe via l’API documentée ci-dessus. Plus précisément :

  • Planification des plans : raisonnement textuel côté agent, sans intervention du panneau.
  • Génération d’ancres : POST /image/generate.
  • Ancre vers vidéo : POST /queue/add avec mode=i2v et image=<anchor_path>.
  • État de session : l’agent le tient à l’extérieur.

Les agents externes peuvent utiliser les flux de travail documentés via cette API.

Source : docs/API.md dans le dépôt public. Relu pour ce site avant publication. Traduit de l'original anglais. Suggérer une modification.