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:8198sur une installation normale.8199est 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 avecLTX_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
POSTencodé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 deBaseHTTPRequestHandler, 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/installet/music/lora/fetch; un travail qui arrive par une autre voie échoue avec la même phrase. Lisez les conditions avecGET /licenceset acceptez avecPOST /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/configrenvoie 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) :
| Champ | Type | Note |
|---|---|---|
mode | t2v | i2v | extend | keyframe | a2v | v2a | image | Type de travail. v2a (Ajouter du son) ne concerne que Hailuo H3. |
prompt | string | Texte complet du prompt. Les mots déclencheurs des LoRA vont ici. |
negative_prompt | string | Facultatif. 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, height | int | Tous deux divisibles par 32. |
frames | int | Doit vérifier frames % 8 == 1. 121 = 5 s, 169 = 7 s, 241 = 10 s. |
frame_rate | float | 24 par défaut. LTX est entraîné à 24 i/s ; s’en écarter dégrade la qualité. |
character_strength | float | 1.0 par défaut. Intensité du LoRA de personnage, de 0 à 2. |
seed | int ou -1 | -1 = aléatoire. |
quality | quick | balanced | standard | high | Pour 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_steps | int | Pipeline HQ en deux étapes. Valeurs validées par défaut : 10 / 3. |
teacache_thresh | float | Plateau d’accélération validé à 1.8–2.0. Sous 1.6, aucune accélération. Plus haut = mise en cache plus agressive. |
cfg_scale | float | Classifier-free guidance. 3.0 est la valeur validée par défaut. |
bongmath_max_iter | int | Plafond de la boucle interne de l’échantillonneur. 100 est le maximum amont. |
upscale | off | fit_720p | fit_1080p | Post-traitement facultatif. |
upscale_method | lanczos | pipersr | Si upscale != off. |
accel | off | (autres modes : voir la source du panneau) | Réglage d’accélération. |
enhance | true | false | Si 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. |
hdr | true | false | Passe ic-lora HDR. |
image | path | I2V 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. |
audio | path | Référence audio facultative. |
label | string | Libellé facultatif pour la carte de la file d’attente. |
temporal_mode | native | 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_prompts | Tableau 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_invariants | Ce qui ne doit pas changer entre les fenêtres (qui, où, lumière, objectif). Réinjecté dans chaque fenêtre suivante. | |
loras | tableau encodé en JSON | Voir 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).
| Champ | Type | Note |
|---|---|---|
h3_quality, h3_length | string | La 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_continuity | on | off | on 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_json | path / JSON | mode=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_seconds | path / float | mode=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_auto | mode=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_path | path | mode=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 virgules | Quelles 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).
| Champ | Type | Note |
|---|---|---|
id | string | ID 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.)
| Champ | Type | Note |
|---|---|---|
id | string | ID 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.
| Champ | Type | Note |
|---|---|---|
prompts | string | Prompts 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"}}
| Champ | Type | Défaut | Signification |
|---|---|---|---|
prompt | str | obligatoire | Le 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. |
seconds | int | 60 | L’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). |
engine | ltx / h3 | ltx | LTX 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é. |
quality | str | défaut du moteur | LTX : quick / balanced / standard / high ; avec un personnage : draft / pro / high / high_720p ; H3 : draft / standard / high / native. |
beats | liste ou texte à retours à la ligne | aucun | Une ligne par cinq secondes. Une ligne vide garde ce moment ; les lignes en trop sont ignorées. Absent = le prompt est chaque temps fort. |
camera | str | "" | Un mouvement pour tout le plan, sa direction et sa vitesse ; repris dans chaque partie (take_camera). |
image | path | aucun | Une 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_id | str | aucun | Un personnage entraîné (LTX uniquement). Fixe la qualité par défaut à pro, l’export à 720p Sharp et handoff à speech. character_strength facultatif. |
handoff | last / speech | last (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 / retake | on/off | on | La phrase de continuité sur chaque temps fort ; une reprise de dérive par partie. |
seed, label, no_music, turbo (H3), upscale, upscale_method | Comme 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 :
| moteur | partie | ce que fait make_job | worker |
|---|---|---|---|
ltx | 10 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 |
h3 | 15 s = trois temps forts | h3_length=15s, h3_chain_prompts = les temps forts de la première partie | un 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 :
| champ | off signifie |
|---|---|
take_light_lock | la 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_retake | une 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_camera | facultatif, 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_handoff | last (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).statevautidle,starting,downloading,waiting(un autre téléchargement tient la place),waiting_disk(le panneau gardeinstall.background_floor_gbde libre ;messagedit combien libérer),retry_wait,failedoudone. Vide etidlesur toute installation que install.js n’a jamais mise en file : une installation mise à jour ne télécharge rien.downloadportebackground: truependant que le téléchargeur tient la place.current: le travail en cours d’exécution (nullau repos).gpu(4.19.10) :{ busy, holder, since, outside_queue }: l’unique verrou GPU du panneau.holdervaut"queue"pour le travail danscurrent, 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 quecurrentsoitnull, que la file soit en pause ou vide, ET quegpu.busysoitfalse.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 409app_downloading. Un secondscripts/fetch_pack_release.pysur 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 astatus,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 :
| Valeur | Signification |
|---|---|
ok | Mesuré, et le RMS du delta est dans la plage de fonctionnement. |
weak | Mesuré, 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. |
unknown | Entraî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
| Champ | Type | Note |
|---|---|---|
id | string | ID 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.
| Champ | Type | Note |
|---|---|---|
file | file | Exactement 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.
| Champ | Type | Note |
|---|---|---|
job_id | string | Facultatif 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. |
file | file | Exactement 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'].
| Champ | Type | Note |
|---|---|---|
train_job_id | string | Donné par /train/upload. |
trigger | string | Jeton 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. |
preset | quick | medium | high | Pré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_count | int | Confirmé par le panneau à partir des images envoyées. |
Remplacements avancés (tous facultatifs, ils reprennent par défaut ceux du préréglage) :
| Champ | Type |
|---|---|
rank, alpha, steps, lr, resolution | int / float |
caption_strategy | class_word | trigger_only | auto_caption |
crop_strategy | center |
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) :
preset | epochs | rank | résolution | max_steps | Validé pour l’identité ? |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | Non. La pastille affiche « identité non validée ». |
medium | 60 | 16 | 576 | 12000 | Non. Idem. |
high | 100 | 32 | 512 | 20000 | Oui : 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 :
preset | epochs | rank | résolution | max_steps | modules cibles |
|---|---|---|---|---|---|
quick | 2 | 4 | 384 | 120 | ensemble compact |
medium | 5 | 8 | 384 | 300 | ensemble compact |
high | 10 | 8 | 448 | 500 | ensemble 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/ :
| Champ | Type | Note |
|---|---|---|
id, trigger | string | Même valeur : le jeton déclencheur rare. |
name, pronoun, subject_noun | string | Tirés du mlx_models/characters/<trigger>/bundle.json facultatif. |
face_lora_path | string | Chemin absolu vers <trigger>_v2.safetensors. Toujours présent. |
sample_image_url | string | null | URL d’une image d’aperçu du jeu de données d’entraînement. |
sheet_image_path, sheet_image_url | string | null | La 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
| Route | Renvoie |
|---|---|
GET /storyboard/list | Toutes les planches, la plus récente d’abord. |
GET /storyboard/get?id=<bid> | Un document de planche. |
GET /storyboard/films | Les 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)
| Champ | Clé de la planche | Effet |
|---|---|---|
auto | auto | après le plan : rend chaque plan, monte, assemble, sans plus aucun bouton |
anchor_stills | anchor_stills | avant 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_windows | long_windows | un 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_seconds | take_seconds | une 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.
| Action | Champs | Note |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | Planifier 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. |
cancel | id | Libérer un créneau du planificateur. |
save | JSON {id, board} | Écrire une planche modifiée à la main. |
grade | id, n, grade, note | Noter un plan. |
estimate | id, pass, only | Estimation du coût et de la durée avant de dépenser. |
render | id, pass, only, out, music, music_mode | Tourner la planche. |
stop | id | Arrêter le rendu de planche en cours. |
replan-shots | id, ns | Retirer 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-shot | id, path | |
import-shots | id, from, only | Clips 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. |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Afficher dans le Finder (macOS). |
delete | id |
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"
…}
]
| Champ | Où | Règles |
|---|---|---|
locations[].views | lieu | Liste 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[].view | plan | Un 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[].eyeline | plan | L’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
| Route | Renvoie |
|---|---|
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>.mp4 | Une 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/uploads | Les 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-route | Champs | Note |
|---|---|---|
prepare | id, music, target_seconds | Construit les proxys et les crêtes. 400 si music n’est pas un fichier. |
add-clip | id, from, only, path, title, kind | kind vaut video | still | slug : le passer évite qu’une image n’arrive comme une vidéo sans image. |
add-sound | id, path | Un 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. |
relink | id, only | Repointe 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>. |
cancel | id | Annuler le travail de préparation. |
auto | id, music, target_seconds, min_shot, max_shot | Relancer le montage de la machine. Arrive dans la voie automatique. |
save | JSON {id, edit, expect_revision?} | Voir ci-dessous. |
draft | id, op, slug, name, from | Voir Brouillons. |
backup | JSON {id, edit} | La voie discrète. Voir Brouillons. |
recover | id | Adopter la sauvegarde en attente. |
discard-backup | id | La jeter. |
version | id, label | Nommer 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. |
restore | id, file | Restaurer une entrée de l’historique. Refusé pendant le rendu du film. |
render | id, out, music, music_mode, format, size | Assembler 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-nle | id | XML FCP7 + JSX After Effects + médias liés. |
reveal | id, what | Afficher dans le Finder. |
generate | id, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_of | Tourner 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[]
| Champ | Note |
|---|---|
id, path, proxy | path/proxy valent null sur un slug. |
start, end | La fenêtre À L’INTÉRIEUR de la source. |
film_start, film_end | Le 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). |
kind | video (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). |
source | auto | human. |
locked | bool. |
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. |
speed | Vitesse 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. |
audio | Le 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}
| Champ | Signification |
|---|---|
offset | La 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_end | Points 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 :
op | Champs supplémentaires | Effet |
|---|---|---|
new | name, from=current | Nouveau brouillon, vide ou copié de ce qui est à l’écran. Il devient actif. |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | Met 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éfixe | Quoi | Nettoyé ? |
|---|---|---|
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
| Champ | Type | Note |
|---|---|---|
path | string | Doit ê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).
| Route | Quoi |
|---|---|
GET /sw.js | le 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/subscribe | formulaire subscription = le JSON PushSubscription ; une entrée par point d’accès |
POST /push/unsubscribe | formulaire endpoint |
POST /push/test | envoie « 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
| Champ | Type | Note |
|---|---|---|
| (n’importe quelle clé de réglage) | string | Voir state/panel_settings.json pour l’ensemble de référence. |
notify_done | 1/0 | Alertes 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).
| Champ | Note |
|---|---|
prompt | obligatoire |
mode | t2v (défaut), i2v ou a2v (synchronisation labiale : le prompt d’aide i2v plus la loi de prompt de synchronisation labiale) |
preserve_tokens | liste JSON (ou liste séparée par des virgules) de mots que le résultat doit conserver, à la casse exacte : les mots déclencheurs |
translate | 0 garde un prompt en écriture non latine dans sa propre langue ; par défaut il est traduit en anglais |
loras | 4.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/addavecmode=i2vetimage=<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.