Docs / API e agenti
API HTTP per agenti
Questo sito documenta flussi di lavoro e campi supportati selezionati, non l’intera API interna.
Usa personaggi originali o stilizzati, oppure la tua stessa immagine con consenso documentato. Qualsiasi rappresentazione di un’altra persona identificabile richiede il suo consenso documentato. Segui la politica di utilizzo accettabile per tutte le immagini di riferimento, i dati di addestramento, l’audio e i risultati.
Gli agenti esterni (Claude Code, Codex, OSS o qualunque cosa parli HTTP) controllano Phosphene tramite questa API. La chat dentro il pannello è stata rimossa il 2026-05-15: nel pannello non c’è più nessun agente integrato. Tutto ciò che faceva la chat può essere fatto da un agente esterno tramite questi endpoint.
Strumenti già pronti sopra questa API: il comando phosphene e un server MCP per Claude Code,
Codex o qualsiasi client MCP, in agents/. Vedi Strumenti per agenti.
Server
- URL base:
http://127.0.0.1:8198su un’installazione normale.8199è la porta del profilo DEV, e ogni esempio di questa pagina la usa perché è il pannello su cui sono stati scritti. La regola è una riga nel sorgente (mlx_ltx_panel.py:275):DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, modificabile conLTX_PORT. Se una richiesta qui non restituisce nulla, quasi certamente stai parlando con una porta su cui non c’è nessun pannello: prova l’altra. - Processo:
mlx_ltx_panel.py(nella radice del repository) - Formato di scambio: corpi
POSTcodificati come form; le eccezioni JSON sono indicate per ogni endpoint. Le risposte sono HTTP/1.0 (il valore predefinito diBaseHTTPRequestHandler, mai sovrascritto), quindi la connessione si chiude dopo ogni richiesta e non c’è nessun keep-alive con cui mettere richieste in pipeline. - Autenticazione: nessuna, in ascolto solo sul loopback.
Convenzioni
- Ogni risposta JSON ha
Content-Type: application/json. - Gli errori restituiscono
{"error": "<message>"}più uno stato HTTP non 2xx. - 451
licence_required(4.19.8). Una richiesta che scaricherebbe o eseguirebbe un modello la cui licenza chiede un “I accept” esplicito (Hailuo H3 con la MiniMax H3 Community License e i modelli non commerciali Ideogram 4, YuE2, FLUX.1 Krea [dev] e Bria FIBO) risponde con HTTP 451 e{"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"}finché quella licenza non viene accettata una volta su questo Mac. Vale per/queue/add,/queue/retry,/queue/batch,/image/generate,/h3/turbo/install,/h3/tristep/install,/music/install,/music/cover/installe/music/lora/fetch; un lavoro che arriva in qualsiasi altro modo fallisce con la stessa frase. Leggi i termini conGET /licencese accetta conPOST /licences/accept(sotto), oppure una volta nel pannello, che mostra da solo la schermata. - Il namespace
/agent/*è riservato e rimosso: qualsiasi percorso sotto/agent/tranne/agent/image/configrestituisce 410 Gone con{"error": "agentic flows removed; see docs/API.md"}. I nuovi endpoint non vanno aggiunti sotto/agent/.
Generazione: invia e gestisci i lavori
POST /queue/add: accoda un render video
Aggiunge un lavoro alla coda del pannello. Restituisce subito; l’helper lo elabora in modo asincrono.
Campi del form (tutti obbligatori salvo indicazione contraria):
| Campo | Tipo | Nota |
|---|---|---|
mode | t2v | i2v | extend | keyframe | a2v | v2a | image | Tipo di lavoro. v2a (Aggiungi audio) è solo per Hailuo H3. |
prompt | stringa | Testo completo del prompt. Le parole trigger dei LoRA vanno qui. |
negative_prompt | stringa | Facoltativo. Rispettato solo dove la pipeline usa il classifier-free guidance: high, extend, keyframe, a2v. I percorsi distillati quick / balanced / standard non hanno un ramo di guidance e lo ignorano (prima ne incorporavano i termini nel prompt, e il modello finiva per disegnarli, #81). |
width, height | int | Entrambi divisibili per 32. |
frames | int | Deve soddisfare frames % 8 == 1. 121 = 5 s, 169 = 7 s, 241 = 10 s. |
frame_rate | float | Predefinito 24. LTX è addestrato a 24 fps; scostarsi peggiora la qualità. |
character_strength | float | Predefinito 1.0. L’intensità del LoRA del personaggio, 0-2. |
seed | int o -1 | -1 = casuale. |
quality | quick | balanced | standard | high | Per il lavoro con LoRA di personaggio, usa high. balanced instrada in silenzio le clip oltre 121f verso il transformer distillato Q4, dove i LoRA attuali perdono l’identità. |
stage1_steps, stage2_steps | int | Pipeline HQ a due stadi. Valori predefiniti validati: 10 / 3. |
teacache_thresh | float | Il plateau di accelerazione validato è 1.8–2.0. Sotto 1.6 nessuna accelerazione. Più alto = cache più aggressiva. |
cfg_scale | float | Classifier-free guidance. 3.0 è il valore predefinito validato. |
bongmath_max_iter | int | Limite del ciclo interno del sampler. 100 è il massimo di upstream. |
upscale | off | fit_720p | fit_1080p | Post-elaborazione facoltativa. |
upscale_method | lanczos | pipersr | Se upscale != off. |
accel | off | (altre modalità: vedi il sorgente del pannello) | Manopola di accelerazione. |
enhance | true | false | Se true, Gemma riscrive il prompt prima della codifica. Imposta false quando il prompt contiene parole trigger di LoRA: il riscrittore può eliminarle. |
hdr | true | false | Passaggio HDR ic-lora. |
image | percorso | Solo I2V. Percorso assoluto di un PNG/JPG di riferimento. Obbligatorio: dalla v4.6.1 un image omesso o vuoto su i2v / i2v_clean_audio viene rifiutato all’avvio del lavoro con un errore leggibile, invece di usare per default examples/reference.png, un file demo che nessuna installazione ha mai incluso (quel default era l’errore di render più diffuso nella flotta: image not found: <path>, 35 eventi su 22 persone in 14 giorni). LTX_DEFAULT_IMAGE fornisce ancora un default quando punta a un file che esiste davvero. |
audio | percorso | Riferimento audio facoltativo. |
label | stringa | Etichetta UI facoltativa per la scheda in coda. |
temporal_mode | native | fps12_interp24 | windows. windows fa il render oltre una finestra da 121 fotogrammi come SEQUENZA: un generate, poi un extend per ogni finestra successiva sulla coda mantenuta dell’ultima (ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), tagliata alla durata richiesta. Richiede il componente Q8 e un livello che consenta Extend; altrimenti viene rifiutato con una frase. Memorizzato sul lavoro come long_mode. | |
window_prompts | array JSON (o righe separate da a capo) con una riga per finestra; riga 1 vuota = il prompt; una riga vuota successiva mantiene il momento precedente. Il prompt di ogni finestra successiva è la sua riga PRIMA, poi la clausola di continuazione, poi Throughout: <window_invariants>.: il contratto della catena H3, e la regola di aprire con il movimento. | |
window_invariants | Ciò che non deve cambiare tra le finestre (chi, dove, luce, obiettivo). Reiniettato in ogni finestra successiva. | |
loras | array codificato in JSON | Vedi il payload dei LoRA sotto. |
Campi di Hailuo H3 (engine=h3), 4.19. H3 fa il render di t2v, i2v, keyframe, extend, a2v e v2a; ogni modalità oltre i2v richiede un flag sul runner INSTALLATO (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), e un lavoro per una modalità che il runner non ha viene renderizzato su LTX con una frase (Aggiungi audio non ha un percorso LTX e viene invece rifiutato con la frase di aggiornamento).
| Campo | Tipo | Nota |
|---|---|---|
h3_quality, h3_length | stringa | La cella. h3_quality=fast_hd = il passaggio Fast 640×384 + Aumenta risoluzione e Correzione volto a 1280×768, messi in coda insieme; Fast e la correzione sono forzati. |
h3_continuity | on | off | Predefinito on: una finestra concatenata porta gli ultimi 17 fotogrammi della precedente e il loro suono (--chain-context-frames 17). off = il passaggio con una sola immagine. |
start_image, end_image, keyframes_json | percorso / JSON | mode=keyframe. Su H3 il fotogramma iniziale è facoltativo (un fotogramma finale da solo è il compito last-frame di MiniMax); i beat di keyframes_json cadono al loro frame_index sulla linea temporale a 24 fps. |
video_path, h3_extend_seconds | percorso / float | mode=extend: qualsiasi clip, continuata dai suoi ultimi 17 fotogrammi e dal loro suono; da 0,5 a 15 s aggiunti dopo. |
audio, image, frames, audio_start_time, audio_stem_auto | mode=a2v con engine=h3: la traccia viene mantenuta esattamente e l’immagine viene renderizzata su di essa; frames (24 fps) è la durata, limitata all’audio rimasto dopo audio_start_time e a 30 s; audio_stem_auto=on condiziona sulla voce separata e consegna l’originale. | |
video_path | percorso | mode=v2a (Aggiungi audio, solo H3): l’immagine della clip viene mantenuta esattamente e viene generato solo il suo suono; fino a 60 s. |
h3_prompt_guards | "" | off | all | elenco separato da virgole | Quali protezioni del prompt agiscono sul testo che il runner codifica (h3_prompt_guards.py): ellipsis, spoken, hands, nouns. Vuoto = l’insieme predefinito (ellipsis, spoken, hands; nouns è su richiesta); off invia il prompt così com’è. Le protezioni applicate vengono registrate come h3_prompt_guards_applied; prompt conserva ciò che è stato scritto. |
Payload dei LoRA: il campo loras è un array codificato in JSON di oggetti {path, strength}. Impila quanti ne servono: su Hailuo H3, impilare richiede --lora ripetibile del motore (/status.h3.loras.max_stack > 1); un pacchetto più vecchio accetta un solo adattatore e il campo h3_lora_slot decide se va a Turbo o al LoRA.
[
{"path": "<panel-root>/mlx_models/loras/explorertrn_v2.safetensors", "strength": 1.0}
]
Ritorno: {"ok": true, "id": "j-<...>"}: l’ID del lavoro per il polling.
Esempio:
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 di /queue/add (comportamento identico).
POST /queue/retry
Rimette in coda un lavoro dalla cronologia con gli stessi parametri. params.open_when_done viene forzato a false (i nuovi tentativi sono in background).
| Campo | Tipo | Nota |
|---|---|---|
id | stringa | ID del lavoro di origine. |
Restituisce {"ok": true, "id": "<new-id>", "source_id": "<old-id>"}.
POST /queue/remove
Rimuove un lavoro in coda. (Un lavoro in esecuzione non si può rimuovere: usa /stop.)
| Campo | Tipo | Nota |
|---|---|---|
id | stringa | ID del lavoro. |
Restituisce {"ok": true}.
POST /queue/clear
Svuota la coda. Restituisce {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}.
Il token annulla QUESTO svuotamento una volta, per 60 s (POST /queue/restore con
{"token": "<hex>"} rimette esattamente i lavori rimossi, con gli ID originali,
davanti a tutto ciò che è stato messo in coda da allora). Uno svuotamento successivo lo sostituisce; un token scaduto o
già usato risponde 410.
POST /queue/pause, POST /queue/resume
Mette in pausa o riprende il dispatcher della coda (non influisce su un lavoro già in esecuzione).
POST /stop
Chiede di fermare il lavoro in esecuzione. Restituisce {"ok": true}. ?id=<job id> facoltativo
(quello che invia il pannello): ferma solo se quel lavoro è ancora quello in esecuzione,
altrimenti 409 {"stale": true} e non viene fermato nulla. /stop/after_part
accetta lo stesso id.
POST /queue/batch
Invia più prompt come un unico batch.
| Campo | Tipo | Nota |
|---|---|---|
prompts | stringa | Prompt separati da a capo. |
(più tutti i campi standard di /queue/add, applicati a ogni riga) |
Stato: controlla lo stato dei lavori
One Shot: una porta tutta sua, POST /oneshot (2026-09-08)
One Shot è una scheda di lavoro e un’API di prima classe. Uno script invia lo stesso documento che invia la scheda, un unico oggetto JSON, e riceve indietro il lavoro messo in coda:
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"}}
| Campo | Tipo | Predefinito | Significato |
|---|---|---|---|
prompt | str | obbligatorio | L’intera inquadratura, una volta sola: chi, dove, l’ora del giorno e il tempo, il suono. Senza beat copre ogni cinque secondi. |
seconds | int | 60 | Uno tra 30 / 45 / 60 / 90 / 120. Qualsiasi altro valore viene rifiutato, mai arrotondato (un 75 prima veniva renderizzato come una sola clip). |
engine | ltx / h3 | ltx | LTX fa il render di parti da 10 s (volti, voci, dialoghi); H3 di parti da 15 s (movimento, paesaggi). H3 viene rifiutato se non è installato. |
quality | str | predefinito del motore | LTX: quick / balanced / standard / high; con un personaggio: draft / pro / high / high_720p; H3: draft / standard / high / native. |
beats | elenco o testo a capo | nessuno | Una riga ogni cinque secondi. Una riga vuota mantiene quel momento; le righe in più vengono scartate. Assenti = il prompt è ogni beat. |
camera | str | "" | Un solo movimento per tutta l’inquadratura, la sua direzione e velocità; riportato in ogni parte (take_camera). |
image | percorso | nessuno | Un fotogramma iniziale già presente su questo Mac: caricalo prima con POST /upload (campo image) e passa il path restituito. Rende la prima parte i2v. |
character_id | str | nessuno | Un personaggio addestrato (solo LTX). Imposta la qualità su pro, l’esportazione su 720p Sharp e handoff su speech. character_strength facoltativo. |
handoff | last / speech | last (speech con un personaggio) | Dove una parte passa il testimone: il suo ultimo fotogramma, oppure un fotogramma parlato con l’ultima parola portata sulla parte successiva (vedi il contratto del take più sotto). |
light_lock / retake | on/off | on | La frase di continuità su ogni beat; una ripresa per deriva per ogni parte. |
seed, label, no_music, turbo (H3), upscale, upscale_method | Come su /queue/add. |
GET /oneshot/options: cosa può fare questo Mac: 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}: il pianificatore dello Storyboard scrive un beat ogni cinque secondi a partire dal prompt (blocca per 20-40 s): {ok, beats:[…]}.
GET /oneshot/status: current (id, label, part, parts, lipsync per parte, drift, handoff), queued, recent e le righe log del take stesso.
Sotto il cofano ogni One Shot è il contratto del take qui sotto: POST /oneshot mappa il documento sul form di make_job, quindi la scheda, l’API e /queue/add fanno il render esattamente dello stesso lavoro.
Un take: take_seconds + beats su POST /queue/add
Una clip più lunga di un singolo passaggio, su entrambi i motori. take_seconds è uno tra
30 / 45 / 60 / 90 / 120; beats è un elenco JSON (o testo a capo) con un
prompt ogni cinque secondi: un beat vuoto mantiene il momento precedente, quelli in più
vengono scartati. Nessun beat (campo assente, vuoto o con sole righe vuote) significa che
prompt è ogni beat: l’inquadratura è il prompt sostenuto per tutto il take. Prima della
4.12.1 quel caso faceva il render di ogni finestra come la frase di mantenimento: un take su niente. Il take prevale sul campo di durata del motore. Su ENTRAMBI i motori
viene renderizzato come PARTI concatenate da un passaggio dell’ultimo fotogramma: run_take_job_inner esegue un render
ordinario per parte, ognuna parte dall’ultimo fotogramma della precedente
(i2v, ancorata), nasconde le parti dalla galleria e le unisce in
<name>_take<seconds>s.mp4:
| motore | parte | cosa fa make_job | worker |
|---|---|---|---|
ltx | 10 s = due beat = 241 fotogrammi (un take da 45 s termina con una parte da un beat e 121 fotogrammi) | frames = 241, temporal_mode = native (un take non è mai la catena di finestre, qualunque cosa mandi il form) | un render LTX ordinario per parte tramite run_job_inner: la parte 1 è t2v, oppure i2v dall’image del lavoro quando è arrivato come i2v; ogni parte successiva è i2v dall’ultimo fotogramma della precedente con i2v_reference_mode = anchor. Qualsiasi qualità; il pacchetto Q8 serve solo a una qualità HQ, come per una clip singola |
h3 | 15 s = tre beat | h3_length=15s, h3_chain_prompts = i beat della prima parte | un render H3 ordinario per parte (--first-frame dall’ultimo fotogramma precedente) |
Due campi facoltativi, entrambi on per impostazione predefinita:
| campo | off significa |
|---|---|
take_light_lock | la frase di continuità (take_light_lock(), “it is still night…”) NON viene aggiunta ai beat; take.light_lock è "" e un beat vuoto mantiene con la sola frase di mantenimento |
take_retake | una parte la cui luce supera TAKE_DRIFT_MAX viene tenuta com’è stata renderizzata invece di essere ripresa una volta con un nuovo seed; take.retake è false |
take_camera | facoltativo, testo libero, un solo movimento per TUTTA l’inquadratura (“a slow, steady clockwise arc around the table at eye level, wide to close”). take_camera_lock() lo mette per primo nel prompt della parte 1 (“Camera: …; one steady move at one speed, never stops, never changes direction”) e, in ogni parte successiva, una frase che dice che la camera si sta già muovendo in quel modo e continua nella stessa direzione alla stessa velocità: il passaggio di testimone ancora l’immagine tra le parti, non il movimento, e lo stacco si vedeva come una camera che cambiava direzione o si fermava e ripartiva a ogni giunzione. Se lasciato vuoto, le parti successive ricevono comunque la frase generica di continuità. Registrato come take.camera |
take_handoff | last (predefinito) oppure speech. Con speech il runner taglia ogni parte tranne l’ultima su un fotogramma PARLATO: take_handoff_points() trova dove finisce la battuta (RMS audio), ferma l’immagine TAKE_TALKING_BACK = 0.2 s prima (la bocca ancora a metà parola: l’unico ancoraggio misurato che porta la voce sulla bocca della parte successiva: +0.54 / +0.47 contro −0.15…−0.01 su una bocca chiusa), mantiene il suono fino alla fine della battuta più i suoi 0.4 s di decadimento, e mixa quella coda (part{k}_tail.wav, amix normalize=0) sull’inizio della parte successiva (part{k+1}_lead.mp4): un J-cut, così l’ultima parola si sente intera. Scrivi il primo beat di ogni parte in modo che APRA IN SILENZIO, così la coda ha spazio. La coda silenziosa dopo ogni battuta viene scartata, quindi il take dura meno della sua durata nominale; l’ultima parte non viene tagliata. Ogni parte parlata viene valutata da take_lipsync_score() e ripresa fino a TAKE_LIPSYNC_RETAKES = 2 volte con nuovi seed (id -pNl, -pNl2) quando è sotto TAKE_LIPSYNC_MIN = 0.20; viene tenuta la clip migliore e il suo punteggio è registrato in job["take_lipsync"]. Registrato come take.handoff |
params.take sul lavoro: {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}: frames è
l’intero take (seconds·24+1 su LTX), part_frames una parte intera. Il sidecar
del risultato contiene take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake} con parts i file delle parti nascoste, e
image solo quando il take si è aperto sull’ancora dell’utente. Carica parametri
ripristina un take come take.
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 è il numero di parti su entrambi i motori. I minuti
sono parti × il prezzo di una singola clip di una parte dallo stesso modello di costo di
ogni altra stima (H3: la cella da 15 s misurata; LTX: la cella 10s della qualità
in LTX_TIERS, la coda da un beat alla sua cella 5s); null dove questo
Mac non ha un valore. needs_q8 ora è sempre false: un take LTX fa il render su
qualunque cosa usi la qualità scelta.
GET /status
Ogni riga di outputs[] ha q: le parole ricercabili del risultato, in minuscolo, costruite dal suo sidecar nel passaggio di elenco che già lo legge: prompt, label, mode, quality, engine, character, seed, WxH, Nf, nomi dei file dei LoRA, il nome della cartella del modello, la modalità temporale e windows. La casella di ricerca della galleria è un test di sottostringa su name + q; ogni parola digitata deve corrispondere, e digitare carica anche i risultati più vecchi, così la ricerca copre tutto.
Ogni riga video ha anche silent: true quando la clip non ha suono (nessuna traccia audio nell’intestazione del suo mp4, o una traccia che non supera mai −80 dB), false con suono, null finché non è noto. La lettura dell’intestazione è immediata; il controllo del livello viene eseguito una volta per file su un thread in background e messo in cache per (mtime, size) in state/output_silence.json, quindi un polling non decodifica mai nulla. La scheda della galleria e il player offrono Aggiungi audio su una clip silent quando /status.h3.video_to_audio è true.
Restituisce lo stato completo del pannello.
{
"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...", ... ]
}
Semantica dei campi:
deferred_downloads(4.20):{ active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. I pacchetti che una nuova installazione ha messo in coda per dopo Start (state/install_deferred.json, scritto da install.js;required_files.json -> install.after_start).stateèidle,starting,downloading,waiting(un altro download occupa lo slot),waiting_disk(il pannello mantiene liberoinstall.background_floor_gb;messagedice quanto liberare),retry_wait,failedodone. Vuoto eidlesu qualsiasi installazione che install.js non ha mai messo in coda: un’installazione aggiornata non scarica nulla.downloadportabackground: truementre il fetcher occupa lo slot.current: il lavoro attualmente in esecuzione (nullquando inattivo).gpu(4.19.10):{ busy, holder, since, outside_queue }: l’unico gate GPU del pannello.holderè"queue"per il lavoro incurrent, oppure ciò che occupa la GPU fuori dalla coda:"image"(un render di Image Studio),"character_sheet","enhance"(Prompt Enhance),"lyrics","update"(lo script post-aggiornamento). Un client che non deve interrompere il lavoro (fermare o aggiornare il pannello) aspetta checurrentsianull, che la coda sia in pausa o vuota E chegpu.busysiafalse.app_models(solo app per Mac): il download dei modelli dell’app stessa:{ state, packs, active, locked, done_bytes, total_bytes }.locked(4.19.10) è true mentre l’app tiene il suo blocco di download (<Phosphene home>/.locks/models.lock); il pannello allora non offre Download per quei pacchetti e ne rifiuta uno con 409app_downloading. Un secondoscripts/fetch_pack_release.pysu una cartella di pacchetto già in scrittura si ferma senza toccare nulla con codice di uscita 75.queue: lavori in attesa, in ordine FIFO.history: lavori completati/falliti. Ogni voce hastatus,elapsed_sec,output_path,raw_path(nativo prima dell’upscale),error.log: buffer a scorrimento delle righe stdout dell’helper (ultimi ~50 lavori).
Ciclo di polling: GET /status ogni 15-30 s. Un lavoro è terminale quando il suo status è uno tra done, failed, cancelled, stopped, error. Fino ad allora è queued o running.
stopped significa che l’utente ha fermato il render di proposito (vedi POST /stop?mode=early). Non è un fallimento: non è stato salvato nulla perché la clip non è mai stata finita, ma nulla è andato storto. stopped_reason porta la frase del runner stesso.
current.progress
Presente mentre un lavoro è in esecuzione.
{
"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 è assente a meno che l’anteprima in diretta sia attiva (Impostazioni → Memoria / velocità) e il piccolo decoder sia installato. meaningful è calcolato lato server e non va ricalcolato: la regola cambia per pipeline, stima 6 di 8 sul programma distillato, le cui prime stime sono ancora sostanzialmente rumore; stima 2 sul percorso HQ a due stadi, che valuta il denoiser due volte per passo dello stadio 2. Un client che contasse le stime dovrebbe sapere quale programma è in esecuzione.
POST /stop?mode=early
Chiede al render in corso di fermarsi al prossimo confine di forward creando un sentinella ABORT. Il runner esce con 75, un codice distinto che significa “l’utente l’ha fermato”, non un crash, e il lavoro si risolve con status: "stopped" senza file di risultato. Restituisce 404 quando nulla è in rendering e 409 quando il render non ha un’anteprima in diretta attraverso cui fermarsi (usa il POST /stop brusco, che termina l’helper).
Avvertenza sulla codifica: il buffer del log può contenere caratteri di controllo letterali da prompt con a capo incorporati. Eliminali prima di fare il parsing JSON:
import re, json
raw = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', ' ', raw)
data = json.loads(raw, strict=False)
LoRA
GET /loras
Restituisce {"user": [...], "curated": [...], "loras_dir": "...", ...}. Ogni voce ha id, name, path, filename, size_bytes, recommended_strength, kind (train_character per i LoRA addestrati tramite il pannello; null altrimenti), adapter_verdict (vedi sotto) e i metadati di CivitAI se noti.
adapter_verdict: se questo file può fare qualcosa
Un LoRA può essere addestrato fino in fondo, scrivere un safetensors valido, caricarsi senza avvisi e non cambiare nulla: i delta che ha imparato sono numericamente troppo piccoli per spostare il modello. Ogni controllo strutturale passa, perché ogni controllo strutturale chiede se le CHIAVI arrivano a destinazione e nessuno chiede se dentro ci sia qualcosa (#61, #62).
adapter_verdict (_adapter_verdict) viene letto dal blocco adapter_strength del sidecar ed è uno tra:
| Valore | Significato |
|---|---|
ok | Misurato, e l’RMS del delta è nella banda di lavoro. |
weak | Misurato, e i delta sono pari o inferiori a WEAK_DELTA_RMS (2.0e-4). Il file viene tenuto; il render quasi certamente sembrerà senza LoRA. |
unknown | Addestrato da una build che non misurava. Non è sinonimo di weak: il silenzio non è debolezza, e ogni LoRA precedente alla misurazione risulta così. |
Qualsiasi altro valore è ciò che l’ha chiamato il trainer, passato così com’è.
Chi chiama dovrebbe segnalare weak prima di spendere un render per scoprirlo, e non dovrebbe decorare unknown.
GET /train/list porta lo stesso verdetto più adapter_advice: una frase che dice cosa fare, vuota quando il verdetto è ok o unknown. Tiene conto dell’hardware: su un Mac sotto i 64 GB non dice “train again on High”, perché quella macchina non può raggiungere la ricetta valutata (vedi la sezione sul profilo più sotto). La scheda Addestra del pannello la mostra come banner sopra i chip dei personaggi addestrati e nella riga di cronologia del lavoro finito; un verdetto su cui l’utente non può agire è una misura, non una risposta (#62).
GET /hf/loras
Hugging Face come fonte sfogliabile accanto a CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1.
Phosphene non nomina nessuna organizzazione: la query è una ricerca (vuota = il termine di ricerca predefinito della corsia), un elenco per autore o un singolo repository;
i risultati sono tenuti per corsia in base al nome del repository e ai tag, e il .safetensors più grande di ogni repository più la sua clip di esempio diventano un elemento nella stessa forma che la griglia di CivitAI mostra
(name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface").
In cache per dieci minuti per corsia e query.
POST /hf/loras/download
Form repo, filename, meta (il JSON dell’elemento). Scarica tramite huggingface_hub (il token HF salvato, se presente)
nella cartella dei LoRA della corsia, esegue la sonda di layout H3 e scrive lo stesso sidecar che scrive un’installazione da CivitAI più
source, hf_repo, hf_url. Restituisce { ok, skipped, name, path, sidecar_path, lane, layout, converted }.
GET /civitai/download/state · POST /civitai/download/cancel (4.18.0)
POST /civitai/download accetta un campo di form facoltativo token (8-64 caratteri, A-Z a-z 0-9 _ -) scelto da
chi chiama. Mentre quel download è in corso, GET /civitai/download/state?token=… restituisce
{ ok, state: "running"|"cancelled", bytes, total, name } (404 quando è finito), e
POST /civitai/download/cancel con token lo ferma al prossimo blocco da 256 KB: il file parziale viene rimosso,
non viene registrato nulla, e la risposta del download stesso è { ok: false, cancelled: true, error }.
Senza token un download funziona esattamente come prima.
GET /loras/updates
Chiede a CivitAI se un LoRA installato con un civitai_id nel suo sidecar ha una
versione più recente (modelVersions[0].id ≠ il civitai_version_id del sidecar). Una
richiesta per ciascun LoRA di questo tipo; non viene scaricato nulla.
{ "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": "..." } ] }
Installare l’aggiornamento è il normale POST /civitai/download con quel
download_url + meta; il nuovo file arriva accanto al vecchio, che resta
finché non viene eliminato.
POST /loras/guide
Form: path (un LoRA installato da GET /loras). Il modello pianificatore scrive una
guida di un paragrafo (cosa fa il LoRA, come scrivere il prompt, un’intensità da cui partire,
con cosa va in conflitto) a partire dal nome / descrizione / parole trigger del sidecar stesso, e la salva nel sidecar sotto guide; le righe di GET /loras poi portano
guide. Rifiutato con 409 mentre un render è in corso (il pianificatore è un modello da 12B).
Restituisce { ok, guide }.
POST /loras/refresh
Riesamina mlx_models/loras/. Restituisce lo stesso payload di /loras.
POST /loras/delete
| Campo | Tipo | Nota |
|---|---|---|
id | stringa | ID del LoRA da /loras. |
Elimina il file. Restituisce {"ok": true}.
POST /h3/loras/import
multipart/form-data. Installa un adattatore Hailuo H3 che hai già nella libreria
LoRA di H3 (mlx_models/hailuo-h3/loras/, o dove il pacchetto installato la tiene).
Volutamente NON /upload: i media di riferimento possono essere qualsiasi immagine o audio, mentre un adattatore
H3 deve superare il contratto di layout del runner prima di poter comparire nel selettore.
| Campo | Tipo | Nota |
|---|---|---|
file | file | Esattamente un .safetensors. Il nome del file viene ridotto al suo basename e ripulito; non può collidere con un file già presente nella libreria. |
Il corpo viene trasmesso in streaming a una cartella di staging nascosta, non messo in buffer, quindi un adattatore da molti gigabyte
costa circa 1 MiB di memoria residente. Content-Length è obbligatorio e limitato a
H3_LORA_UPLOAD_MAX_BYTES (4 GiB).
Cosa succede al file, in ordine: messo in staging sotto .import.<pid>.<tid>/<name> →
_h3_lora_prepare (un repack di ComfyUI ha il suo namespace diffusion_model. rimosso
sul posto, una riscrittura della sola intestazione) → i controlli di payload e moduli di destinazione solo per l’importazione →
os.replace nella libreria → JSON sidecar. Un rifiuto in qualsiasi passaggio non lascia nulla.
Restituisce:
{
"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 viene scritto nel sidecar e raccolto dal controllo di intensità per LoRA del
selettore. Il loader H3 applica B @ A e nessun alpha, quindi un adattatore il cui PEFT
alpha/rank non è già incorporato in lora_B ha bisogno di quel numero qui: viene segnalato,
mai usato come motivo di rifiuto.
Errori: 411 quando Content-Length è assente o zero, 413 quando il corpo supera il limite,
400 per un file errato (estensione sbagliata, vuoto, nome duplicato, layout inutilizzabile, payload
malformato, modello sbagliato), 500 altrimenti. Ogni messaggio nomina il file scelto dall’utente.
Addestramento
POST /train/upload
Caricamento multipart/form-data. Aggiunge un’immagine a un dataset di addestramento: questa route
è un file per richiesta, non un batch. Invia le immagini in un ciclo, rimandando indietro il
train_job_id restituito a ogni chiamata dopo la prima, così l’intero insieme finisce in una sola cartella.
| Campo | Tipo | Nota |
|---|---|---|
job_id | stringa | Facoltativo alla PRIMA chiamata (viene generato un nuovo id), obbligatorio dopo, per tenere insieme il batch. Attenzione al nome: job_id, non train_job_id: la risposta lo restituisce come train_job_id. |
file | file | Esattamente UN PNG/JPG/JPEG/WEBP/BMP, oppure una didascalia .txt. |
Il corpo della richiesta è limitato a TRAIN_MAX_BYTES_PER_IMAGE (32 MB). Poiché quel limite vale per l’
intera richiesta e la route accetta un solo file, un corpo con più file viene rifiutato anche quando ogni
singola immagine è piccola.
Restituisce lo stato del dataset (train_job_id, numero di immagini, ecc.).
POST /train/start
Avvia l’addestramento di un LoRA di personaggio. Il pannello lancia lora_lab.train_character e rimanda gli eventi di avanzamento in STATE['log'].
| Campo | Tipo | Nota |
|---|---|---|
train_job_id | stringa | Da /train/upload. |
trigger | stringa | Token trigger, ad es. explorertrn. Deve essere composto, raro e solo di lettere per non collidere con il linguaggio normale: le cifre vengono tokenizzate come token singoli e molto comuni (mrz07 → m / rz / 0 / 7), e ogni trigger che qui ha portato un’identità era solo di lettere; il pannello suggerisce <3 consonants>trn (mrztrn) e registra una nota quando un trigger contiene cifre (#62). Il LoRA del personaggio finisce in mlx_models/loras/<trigger>_v2.safetensors. |
preset | quick | medium | high | Preset di iperparametri. Predefinito cambiato nella v4.6.1: ometterlo ora dà high per train_type=character e quick per train_type=style (TRAIN_DEFAULT_PRESET); prima dava quick per entrambi, il livello che non ha mai portato un’identità (#62). Vedi la tabella sotto: il numero di passi non è una costante, e su un Mac sotto i 64 GB nemmeno nient’altro. |
image_count | int | Confermato dal pannello in base alle immagini caricate. |
Override avanzati (tutti facoltativi, ripiegano sui valori predefiniti del preset):
| Campo | Tipo |
|---|---|
rank, alpha, steps, lr, resolution | int / float |
caption_strategy | class_word | trigger_only | auto_caption |
crop_strategy | center |
Restituisce {"ok": true, "id": "j-<...>"}. Segui l’avanzamento tramite /status (il lavoro di addestramento compare in current poi in history).
Cosa sono davvero i preset
I passi sono derivati, non fissi: steps = epochs × image_count, con minimo 1 e limitati dal max_steps del preset (_preset_steps_for, mlx_ltx_panel.py:1629). Il limite fa parte del contratto del server: una chiamata API scritta a mano non deve poter mettere in coda un’esecuzione da migliaia di passi su un Mac con poca memoria.
Su un Mac con 64 GB o più (TRAIN_PRESETS, mlx_ltx_panel.py:1558):
preset | epoche | rango | risoluzione | max_steps | Valutato per l’identità? |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | No. La pillola dice “identity ungraded”. |
medium | 60 | 16 | 576 | 12000 | No. Uguale. |
high | 100 | 32 | 512 | 20000 | Sì: la ricetta v2 validata (Aria_v2, Bizarro_v2). Il predefinito, e quello che la pillola contrassegna come “Recommended”. |
Misurato con lora_compat.py: gli adattatori rango 32 che portano un’identità stanno tra 5.4e-04 e 1.6e-03 di delta_rms; le esecuzioni quick rango 8 di due utenti indipendenti hanno misurato 1.54e-04 e 1.98e-04, entrambe pari o sotto la soglia WEAK_DELTA_RMS di 2.0e-04 (#62).
Quindi high con 50 immagini fa 5000 passi, con 20 immagini 2000, con 300 immagini 20000 (limitato). Solo la ricetta rango 32 è mai stata messa davanti a un occhio umano e giudicata buona.
⚠️ Sotto i 64 GB, ogni preset è in silenzio un altro preset
_select_train_profile (mlx_ltx_panel.py:1650) viene eseguito una volta all’importazione e, quando la RAM totale è 0 < ram < 64 GB, modifica TRAIN_PRESETS e TRAIN_STYLE_PRESETS sul posto. I nomi non cambiano. I numeri cambiano tutti:
preset | epoche | rango | risoluzione | max_steps | moduli di destinazione |
|---|---|---|---|---|---|
quick | 2 | 4 | 384 | 120 | insieme compatto |
medium | 5 | 8 | 384 | 300 | insieme compatto |
high | 10 | 8 | 448 | 500 | insieme compatto |
make_job riproduce gli stessi limiti lato server, quindi anche rank / steps / resolution passati come override avanzati vengono limitati (max_rank 8, max_resolution 448, max_steps 500): non puoi chiedere la ricetta valutata su questo hardware e ottenerla.
È un compromesso voluto e il motivo è reale: un addestramento LoRA LTX completo a 512 px materializza le attivazioni all’indietro del transformer dev e un Mac da 48 GB finisce in swap thrash e non termina mai. Ma sii chiaro su cosa significa: su un Mac sotto i 64 GB non esiste nessun preset che addestri la ricetta valutata da qualcuno. Rango 8 con ≤500 passi è esattamente il regime che adapter_verdict è stato costruito per intercettare, quindi aspettati weak più spesso qui, e leggilo come “questo hardware, questa ricetta” e non come “questo dataset”.
GET /status espone il profilo attivo come train_profile (key: compact_training | full_training, più label, ram_gb, max_rank, max_resolution, max_steps, note) e le tabelle effettive stesse come train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Leggile prima di fidarti del nome di un preset: sono i valori dopo la modifica, quindi sono l’unico posto in cui le due tabelle sopra si distinguono a runtime.
L’evento del trainer adapter_strength
Non è un evento di analisi: nulla di ciò che contiene lascia la macchina (vedi docs/ANALYTICS.md per l’elenco completo di ciò che lo fa). È un evento di avanzamento sullo stream del sottoprocesso lora_lab, emesso una volta dopo che il trainer misura il file che ha appena scritto (mlx_ltx_panel.py:18005). Il pannello registra l’RMS mediano del delta, il massimo e quanti moduli portano qualcosa, poi termina il lavoro in stato di AVVISO invece di un semplice done quando il verdetto non è ok. Il verdetto viene scritto nel sidecar del LoRA come adapter_strength: {"verdict": …} e riletto come adapter_verdict su /loras e /characters.
POST /train/install
Dopo un addestramento riuscito, il LoRA viene copiato automaticamente in mlx_models/loras/. Questo endpoint serve per una reinstallazione esplicita / un aggiornamento dei metadati.
POST /train/delete, POST /train/remove-image
Eliminano i dataset di addestramento / le singole immagini di addestramento.
Personaggi
Scopri e controlla i LoRA di personaggio addestrati come pacchetti.
GET /characters
Restituisce {"characters": [...]}. Ogni voce descrive un personaggio trovato in mlx_models/loras/:
| Campo | Tipo | Nota |
|---|---|---|
id, trigger | stringa | Lo stesso valore: il token trigger raro. |
name, pronoun, subject_noun | stringa | Dal mlx_models/characters/<trigger>/bundle.json facoltativo. |
face_lora_path | stringa | Percorso assoluto di <trigger>_v2.safetensors. Sempre presente. |
sample_image_url | stringa | null | URL di un’immagine di anteprima dal dataset di addestramento. |
sheet_image_path, sheet_image_url | stringa | null | La scheda del personaggio multi-vista generata (mlx_models/characters/<trigger>/sheet.png), quando esiste. Creata da POST /characters/<id>/sheet/generate, servita da GET /characters/<id>/sheet. |
Regola di rilevamento: <trigger>_v2.safetensors è obbligatorio; tutto il resto è facoltativo.
GET /characters/<id>/preview
Serve l’immagine di esempio dell’addestramento per il personaggio (PNG/JPEG).
GET /characters/<id>/sheet
Serve il PNG della scheda del personaggio generata. ?w=<px> restituisce una miniatura in cache (JPEG) attraverso la stessa corsia di ridimensionamento di /image?w=. 404 finché non è stata generata una scheda.
POST /characters/<id>/sheet/generate
Fa il render di una scheda turnaround multi-vista dall’immagine di riferimento del personaggio (prima l’avatar del pacchetto, poi in alternativa un esempio dell’addestramento) e la compone in mlx_models/characters/<id>/sheet.png + un sidecar sheet.json (phosphene/character_sheet@1). Sincrono, come /image/generate: chi chiama resta bloccato per tutto il render; 429 quando la GPU è già occupata da un lavoro di render/addestramento/immagine (mai messo in coda).
Content-Type: application/json. Ogni campo è facoltativo (un corpo vuoto fa il render della scheda predefinita a 3 viste):
{
"engine_override": "qwen_edit_inline",
"views": ["front", "profile_left", "three_quarter"],
"wardrobe": "a red flight jacket",
"seed": -1
}
Sono accettati solo i motori che rispettano i riferimenti (hidream_*_inline, qwen_edit_*_inline, mock_inline): un motore solo testo farebbe il render di uno sconosciuto. seed >= 0 dà alla vista i il valore seed + i, così un’intera scheda si riproduce da un solo numero. Il prompt di ogni vista fissa l’abbigliamento al riferimento (“wearing exactly the same clothes as in the reference image”); wardrobe riafferma l’abito a parole in aggiunta. Le viste dopo la prima concatenano anche la prima vista renderizzata come secondo riferimento: misurato su un’immagine di riferimento poco luminosa, i render laterali isolati reimmaginavano il colore dei capelli tra seed e formulazioni, e un frontale pulito dalla stessa esecuzione riancora gli attributi che il riferimento grezzo specifica poco. L’inquadratura di ogni vista può comunque variare (un soggetto fuori centro in una vista): rigenera o cambia il seed. In caso di successo, il preview di bundle.json viene puntato su sheet.png solo se era null: un’anteprima curata non viene mai sovrascritta.
POST /characters/<id>/generate
Assembla la ricetta di produzione bloccata e mette in coda un render T2V. L’endpoint accetta prompt_body, framing, duration, quality e un seed intero facoltativo (-1 significa casuale, come in /queue/add). Per chiamate di riproduzione/debug esatte, chi chiama può passare full_prompt più i campi di override HQ come stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step e audio_skip_step.
Generazione di immagini (separata dal video)
POST /image/generate
Genera immagini fisse tramite il motore immagini incluso (mflux, BFL, backend mock). Intercambiabile a ogni chiamata.
Content-Type: application/json. Payload:
{
"prompt": "...",
"n": 4,
"engine_override": "mflux",
"aspect": "1:1",
"refs": ["/path/to/ref.png"],
"loras": [{"path": "...", "strength": 1.0}]
}
Vedi image_engine.py per le opzioni specifiche di ciascun backend.
GET /agent/image/config, POST /agent/image/config
Mantenuti sotto il vecchio percorso /agent/ per compatibilità con il frontend di Image Studio. Leggono/scrivono la configurazione del motore immagini (backend predefinito, famiglia mflux, chiave BFL, ecc.). Nonostante il percorso, questa è la configurazione del motore immagini, NON l’agente di chat rimosso.
Storyboard: pianifica un film, poi giralo
Una board è un film: un concept, un cast, location e un elenco numerato di inquadrature. Ogni render che avvia passa per lo stesso contratto make_job → coda di /queue/add; nessuna di queste route ha un percorso di esecuzione privato. Le board vivono sotto state/storyboards/<board_id>/, con storyboard.json scritto in modo atomico: i render durano ore e una board corrotta farebbe perdere l’intera esecuzione.
Lettura
| Route | Restituisce |
|---|---|
GET /storyboard/list | Ogni board, dalla più recente. |
GET /storyboard/get?id=<bid> | Un documento board. |
GET /storyboard/films | I film assemblati su disco: percorso del player, durata, dimensione dell’immagine, dimensione su disco, quando è stato creato. list_outputs fa il glob di OUTPUT/*.mp4 e non scende mai nelle sottocartelle, quindi senza questo l’unica cosa che la funzione produce sarebbe l’unica che l’app non può mostrarti. |
Interruttori del brief (su plan)
| Campo | Chiave della board | Effetto |
|---|---|---|
auto | auto | dopo il piano: fa il render di ogni inquadratura, monta, assembla: niente più pulsanti |
anchor_stills | anchor_stills | prima che venga renderizzata un’inquadratura da testo/personaggio, un normale lavoro immagine ne crea il primo fotogramma (still_job_id → still; la scheda del personaggio è il riferimento tramite qwen_edit_inline quando esiste) e la clip viene renderizzata come i2v · anchor da lì. Un’immagine che fallisce imposta still_error e l’inquadratura viene renderizzata senza ancora, una volta |
long_windows | long_windows | un’inquadratura LTX più lunga di 121 fotogrammi viene renderizzata come temporal_mode=windows (una catena sul transformer dev Q8) con lo stile della board e la location dell’inquadratura come window_invariants, invece di essere tagliata per starci. Extend non può reiniettare un’immagine per finestra, quindi un’inquadratura lunga ancorata lo è solo dalla sua prima finestra |
take_seconds | take_seconds | un take: il film è un’unica inquadratura da 30 / 45 / 60 / 90 / 120 s. Il pianificatore scrive un beat ogni 5 s (_sb_take_concept), la board tiene UNA sola inquadratura con beats (collapse_take), la scheda mostra i beat da modificare e shot_to_job invia take_seconds + beats: il take della scheda Video, così il render è lo stesso da entrambe le porte. 0 lo disattiva |
Ogni campo viene modificato solo se inviato; un campo assente mantiene il valore della board.
POST /storyboard/restill: form id, n, pass facoltativo: dimentica l’immagine
dell’inquadratura n e la clip renderizzata da essa, attiva anchor_stills se era disattivato,
e fa il render di quella sola inquadratura (prima l’immagine, poi la clip da essa). Stessi
rifiuti di render (pianificazione, render già in corso).
Scrittura: POST /storyboard/<action>
Il Director. plan accetta soundtrack (un file audio su questo Mac) e bars_per_shot (1/2/4, predefinito 2). Con una traccia il piano è un VIDEO MUSICALE: beat_map() (lo stesso adattamento che esegue Prepara dell’Editor) trasforma i tempi forti in slot di bars_per_shot battute, il numero di inquadrature è il numero di slot (i chip shots si fanno da parte; limitato a STORYBOARD_MAX_SHOTS con una nota), il brief del pianificatore porta i bpm, la durata dello slot, un’istruzione sull’arco e due leggi (inizia ogni descrizione con il movimento; nessun dialogo, la traccia sostituisce il suono di ogni clip), e la duration_s di ogni inquadratura pianificata è il suo slot più un secondo di margine, con slot: {start, end} sull’inquadratura. La mappa del brano decide quanto spesso. song_map() (storyboard_edit) mette le SEZIONI sulla stessa griglia di battute: {start, end, label, energy, brightness} con etichette intro / verse / chorus / bridge / outro ricavate da posizione, volume relativo e luminosità, e director_pacing() trasforma bars_per_shot in un passo per sezione: il ritornello taglia il doppio delle volte, l’intro e l’outro la metà. Ogni slot porta la sua section; il brief dice al pianificatore quali inquadrature cadono in quale sezione e quanto è calda; una traccia che la mappa non riesce a leggere viene tagliata al passo base e il log lo dice. La board registra soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections}, il primo montaggio automatico dell’Editor usa quella traccia quando Prepara non ne ha messa in cache un’altra, così il film si apre già tagliato a tempo, e GET /storyboard/edit restituisce sections perché il righello possa dipingere l’arco. Un percorso errato è un 400 prima che il pianificatore parta; la fase del pianificatore grid viene segnalata mentre si legge il ritmo.
Auto. plan accetta auto=1: quando il piano arriva, la bozza di ogni inquadratura parte da sola (_sb_auto_after_plan, una volta che il pianificatore ha restituito la memoria), e quando il thread di render finisce con ogni inquadratura renderizzata il film viene tagliato (_sbe_auto_edit, a tempo quando c’è una traccia) e assemblato dallo stesso assemblatore usato da Render (_sb_auto_film); la board registra auto_film. Un’inquadratura che non è stata renderizzata lascia il film in attesa e il log dice quante. Stop ferma comunque il render; il montaggio e il film sono quelli ordinari e si possono rifare dopo.
Codificato come form salvo diversa indicazione. id è l’id della board ovunque.
| Azione | Campi | Nota |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | Pianifica o ripianifica. 409 mentre il renderer occupa la memoria o l’unico slot del pianificatore è preso. shots viene rispettato o rifiutato, mai sostituito in silenzio con un numero diverso. Una ripianificazione MODIFICA location e abbigliamento invece di sovrascriverli. |
cancel | id | Rilascia uno slot del pianificatore. |
save | JSON {id, board} | Scrive una board modificata a mano. |
grade | id, n, grade, note | Valuta un’inquadratura. |
estimate | id, pass, only | Stima di costo/tempo prima di spendere. |
render | id, pass, only, out, music, music_mode | Gira la board. |
stop | id | Ferma il render in corso della board. |
replan-shots | id, ns | Rifà le inquadrature indicate. Una riparazione che viola una legge viene rifiutata; le rifacimenti si innestano nel piano CORRENTE, non in quello originale. |
add-shot | id, path | |
import-shots | id, from, only | Clip di RIFERIMENTO da un’altra board. La provenienza (imported_from), le LOCATION di origine e il CAST di origine viaggiano con loro: lasciarne indietro uno rompe qualcosa di preciso. Rifiuta mentre il film di destinazione è in rendering. |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Mostra nel Finder (macOS). |
delete | id |
Schema della board: i campi di geografia
Un’inquadratura è composta a partire dalla sua location. Dal 2026-08-18 una location può anche essere ripresa da più direzioni, ed è ciò che rende un controcampo un controcampo invece di una seconda location.
"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"
…}
]
| Campo | Dove | Regole |
|---|---|---|
locations[].views | location | Elenco di {id, name, light, description}. Assente, non [], quando una location non ne ha: ogni board scritta prima dell’esistenza delle viste non ha la chiave, e un elenco vuoto sarebbe una forma nuova su cui il validatore avrebbe opinioni senza nessun vantaggio. Gli id seguono lo stesso set di caratteri degli id delle location. |
shots[].view | inquadratura | Un id di vista appartenente alla location_id di quell’inquadratura. Una vista su un’inquadratura senza location, o una vista che non è una di quelle di quella location, è un errore di validazione (unknown_view) e fallisce esattamente come una location sconosciuta: una vista scartata in silenzio compone il controcampo dalla descrizione dell’establishing, e l’auto che la vista esisteva per far uscire dall’inquadratura ci rientra senza che nessuno lo dica. |
shots[].eyeline | inquadratura | Uno tra left, right, lens: un fatto sull’INQUADRATURA, non sulla stanza. right = gli occhi guardano oltre il bordo destro. Qualsiasi altro valore è un errore di validazione (bad_eyeline). |
Cosa ne fa il server. shot_scene_text inietta la descrizione della VISTA quando un’inquadratura ne nomina una e ripiega su quella della location altrimenti: quindi una board senza viste, o un’inquadratura che non nomina nessuna vista, viene renderizzata esattamente come sempre. eyeline_clause compone "his eyes fixed past the right edge of frame" al momento del render; lens non produce volutamente nulla (dire a questi modelli di guardare in macchina dà una recitazione più rigida del silenzio), ed esiste perché un’inquadratura possa dire che tiene l’obiettivo, ed è ciò che permette al controllo dei 180 gradi di distinguere “guarda in camera” da “nessuno ne ha scritta una”.
La regola dei 180 gradi è applicata, non suggerita. Dopo la pianificazione, _enforce_eyelines percorre le inquadrature in ordine di schermo e inverte la seconda di due inquadrature adiacenti che passano tra due personaggi diversi nella stessa location e dichiarano entrambe lo stesso lato, e lo segnala in warnings. Ripara in modo meccanico perché eyeline è un campo discreto con un solo complementare: invertirlo non può danneggiare la prosa di nessuno. Le leggi a livello di prosa ricevono invece un giro di andata e ritorno con un modello, proprio perché non hanno quella proprietà.
Editor: la timeline
L’Editor è un flusso di lavoro di primo livello, non una fase dello storyboard: indipendente dal motore, si apre senza che una board sia a metà render, e il suo documento è edit.json nella cartella della board. Una traccia video, una corsia musicale. Il suono di ogni clip è collegato per impostazione predefinita e si può separare (J/L cut): non è una seconda traccia audio.
Lettura
| Route | Restituisce |
|---|---|
GET /storyboard/edit?id=<bid> | L’arrangiamento. Alla prima chiamata per una board esegue il montaggio automatico UNA volta, lo salva nella corsia automatica e lo restituisce con generated: true. Ogni GET successivo è una lettura di file. Un edit.json corrotto restituisce 500 con corrupt: true e non viene mai sostituito in silenzio: significherebbe buttare via l’arrangiamento di cui è una copia rotta. |
GET /storyboard/edit/status?id=<bid> | Lo stato del lavoro di preparazione. |
GET /storyboard/edit/peaks?id=<bid> | La forma d’onda. Centinaia di KB: scaricala una volta, mai a ogni polling. 404 finché non è stato eseguito prepare. |
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4 | Un video proxy, servito con supporto range. Safari non permette di spostarsi in un <video> il cui server risponde con un semplice 200, il che vanificherebbe l’intero motivo dell’esistenza dei proxy. name deve corrispondere a [A-Za-z0-9._-]{1,120}\.mp4: è un basename coniato dal server, quindi qualsiasi altra cosa è una sonda. |
GET /storyboard/edit/uploads | I video che l’utente ha portato con sé (panel_uploads/timeline/, dal più recente, limitati a 200). Tenuti fuori da OUTPUT di proposito, ed è per questo che servono una route; le immagini no, finiscono nella libreria che la galleria già scorre. |
GET /storyboard/edit/sounds?id=<bid> | La sorgente Suoni della raccolta media: {sounds: [{path, name, where, mtime}], dir}: prima la cartella audio/ del film (where: "film"), poi i file audio (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) in cima a OUTPUT, dal più recente, limitati a 300. Nessuna sonda; la durata viene letta quando si aggiunge un suono. |
GET /storyboard/edit/drafts?id=<bid> | {active, drafts: [...], backup}: vedi Bozze più sotto. |
GET /storyboard/edit/versions?id=<bid> | Solo metadati: nome, revisione, quando è stata salvata, numero di clip, durata, più keep (= EDIT_HISTORY_KEEP, 50). I documenti veri e propri vengono letti una volta, da restore, su richiesta dell’utente. Aprire il pannello non deve essere un download. |
Scrittura: POST /storyboard/edit/<sub>
| Sub | Campi | Nota |
|---|---|---|
prepare | id, music, target_seconds | Crea proxy + picchi. 400 se music non è un file. |
add-clip | id, from, only, path, title, kind | kind è video | still | slug: passarlo è ciò che impedisce a un’immagine di finire come un video senza fotogrammi. |
add-sound | id, path | Un file per una traccia audio: analizzato ({path, title, duration_s, has_video, imported}), 400 quando non contiene suono. Un file fuori da OUTPUT viene collegato con hardlink (copiato tra volumi) nella cartella audio/ del film prima, perché /file serve solo OUTPUT e un suono che l’anteprima non può riprodurre è mezzo suono. La striscia viene posizionata e salvata dal client. |
relink | id, only | Ricollega le clip ai loro file finiti (di consegna). Una RIPRESA finita non fa mai parte di quel batch: viene offerta sulla sua clip con retake: true nelle righe relink del payload e adottata una clip alla volta con only=<clip id>. |
cancel | id | Annulla il lavoro di preparazione. |
auto | id, music, target_seconds, min_shot, max_shot | Rifà il montaggio della macchina. Arriva nella corsia automatica. |
save | JSON {id, edit, expect_revision?} | Vedi sotto. |
draft | id, op, slug, name, from | Vedi Bozze. |
backup | JSON {id, edit} | La corsia silenziosa. Vedi Bozze. |
recover | id | Adotta il backup in sospeso. |
discard-backup | id | Lo butta via. |
version | id, label | Dà un nome a una versione. Dare un nome non è salvare: nessun aumento di revisione, nessuna scrittura su edit.json, nulla della timeline cambia, ed è proprio per questo che si può premere in qualsiasi momento. |
restore | id, file | Ripristina una voce della cronologia. Rifiuta mentre il film è in rendering. |
render | id, out, music, music_mode, format, size | Assembla il film. music_mode è replace | under. Consegna come: format è h264 (predefinito, il preset del pannello) | hevc (VideoToolbox, hvc1, circa metà dei byte) | prores (422 HQ, 4:2:2 a 10 bit, suono PCM, un .mov che nessun browser mostra in anteprima); size è native (come tagliato) | 1080p | 2160p: un solo ridimensionamento Lanczos dopo le sovrapposizioni, solo verso l’alto, mai un ritaglio, saltato quando il montaggio ha già quell’altezza. finish è none | grain | heavy_grain: grana di pellicola in movimento (noise t+u, intensità 9 / 18) aggiunta DOPO la dimensione, così una consegna in 4K ottiene una grana 4K; un trattamento al momento della consegna, mai nel documento, mai nell’anteprima né nell’esportazione. Una consegna diversa è un file diverso: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. I dati portano deliver: {format, size, finish, label}. |
export-nle | id | XML FCP7 + JSX per After Effects + media collegati. |
reveal | id, what | Mostra nel Finder. |
generate | id, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_of | Gira una nuova clip direttamente in uno slot. Con retake_of=<clip id> è una ripresa: l’inquadratura della clip stessa viene CLONATA (personaggio, riferimenti, location, motore) e cambiano solo il prompt, la durata e il seed; la nuova inquadratura porta edit_slot.retake_of, e quando viene renderizzata l’Editor la offre sulla sua clip (“Usalo” / “Keep the old one”). 400 se la clip non è più nella timeline. |
Semantica di save. revision è il contatore del server, preso dal disco, mai da ciò che il client ricordava: una scheda obsoleta non deve poterlo far tornare indietro. Passa expect_revision per scoprire di essere stato superato invece di sovrascrivere in silenzio l’altra scheda: una discrepanza restituisce 409 con conflict: true e la revisione corrente. Gli errori di validazione tornano tutti insieme (errors: [...], 400) con il file su disco intatto, così un client può evidenziare ogni clip errata in un solo passaggio invece di giocare a whack-a-mole.
Schema di edit.json
version è 2 (EDIT_VERSION). La versione 1 viene aggiornata solo in LETTURA (migrate_edit): alzare la versione senza un aggiornamento nel percorso di lettura non rifiuterebbe le build vecchie, rifiuterebbe ogni timeline che qualcuno già aveva. Una versione dal futuro viene lasciata stare così il validatore può dire la cosa onesta.
{
"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[]
| Campo | Nota |
|---|---|
id, path, proxy | path/proxy sono null su uno slug. |
start, end | La finestra DENTRO la sorgente. |
film_start, film_end | Lo slot nel film. Mai indipendenti: una clip viene riprodotta a 1x, quindi film_end - film_start == end - start entro LENGTH_TOLERANCE (2 ms). |
kind | video (assente significa video: stamparlo su 400 clip riscriverebbe ogni edit.json della macchina per dire ciò che la sua assenza dice già), still (tenuta per la durata del suo slot; start/end sono sintetizzati dallo slot, duration: null), slug (nero, nessun file). |
source | auto | human. |
locked | bool. |
adjust | {brightness}, uno scostamento additivo eq=brightness di ffmpeg limitato a ±BRIGHTNESS_LIMIT (0.5). Neutro è assente: riportare il cursore a zero lascia un documento identico a uno che non ha mai avuto un cursore. |
frame | {zoom, x, y}: un’inquadratura diversa. L’immagine viene ingrandita zoom volte (1-3) e la finestra è centrata sulla frazione (x, y) della sorgente. Render: un crop dei pixel della sorgente stessa prima dell’adattamento, così una sola stringa è giusta a ogni dimensione; anteprima: una scala CSS attorno allo stesso ancoraggio (approssimativa); esportazione: FCP7 Basic Motion (scala + centro) e scala + posizione di AE. Neutro è assente; uno slug non ha nulla da reinquadrare. |
speed | Velocità di riproduzione, SPEED_MIN-SPEED_MAX (0.25-4.0), solo video. Lo slot è (end - start) / speed, quindi la regola 1x sopra si legge “alla sua velocità”. L’immagine è setpts, il suono è atempo concatenato oltre la finestra 0.5-2.0 di ffmpeg, e l’inviluppo del suono (afx) resta sull’orologio RIPRODOTTO della striscia: un keyframe a 2 s è ancora a 2 s della striscia dopo una modifica di tempo. Assente è 1x. Mai impostato automaticamente. |
audio | Il montaggio diviso. Vedi sotto. |
clip.audio: il J-cut e l’L-cut
"audio": {"start": 3.5, "end": 7.0, "film_start": 12.25}
Solo clip video. Gli stessi tre numeri dell’immagine, per il SUONO: così il suono può iniziare prima della sua immagine (J) o continuare oltre (L), ed è così che un taglio smette di essere una giunzione netta.
Assente significa collegato, e questa è l’intera migrazione: ogni clip mai scritta non ha la chiave audio e ognuna riproduce il proprio suono sotto la propria immagine. EDIT_VERSION non si è mosso per questo e nessun documento è stato riscritto.
La PRESENZA del campo è l’interruttore, non i valori che contiene. Non derivare “collegato” dal fatto che audio sia uguale alla finestra dell’immagine: scollegare scrive la finestra che la clip ha già, quindi una clip appena scollegata dall’utente risulterebbe collegata e rifiuterebbe di essere trascinata. L’interruttore aggiunge l’oggetto o lo elimina; nient’altro decide. normalise_edit arrotonda il campo ma non lo rimuove mai per lo stesso motivo, e lo elimina del tutto da una still o da uno slug.
Le finestre audio non possono sovrapporsi tra loro più di quanto possano farlo le immagini. Un montaggio diviso è una giunzione netta che cade altrove, non un mix: il mix è ciò per cui esiste audio_tracks.
audio_tracks[]: A3, A4, … sotto la musica
"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]]}}]}]
Un numero qualsiasi di tracce, ciascuna con un numero qualsiasi di strisce. start/end sono i punti di ingresso/uscita dentro il file (una striscia viene riprodotta a 1x, quindi dura end - start nel film); film_start è un secondo della timeline, disposto con adelay esattamente come il letto musicale. afx è lo stesso oggetto inviluppo che portano il suono di una clip e il letto, letto da audio_gain_points; il gain della striscia e il gain della traccia (lineare 0-1) lo moltiplicano: track_strip_gain_points è l’unica curva che anteprima, render ed esportazione leggono. Assente è nessuna e neutro è assente: una modifica senza tracce non ha la chiave, quindi si carica, si salva e si renderizza in modo identico byte per byte; una traccia vuota viene mantenuta.
Le strisce sulla stessa traccia non possono sovrapporsi (audio_track_strips_overlap, un errore, TOUCH_TOLERANCE per una giunzione netta); le strisce su tracce diverse si sovrappongono e si mixano. Errori di forma: 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*.
Render: ogni striscia udibile (non silenziata, traccia non silenziata, curva non muta) è un -vn -i dopo le sovrapposizioni, atrim → volume (la sua curva, sull’orologio della striscia) → aresample → adelay (in campioni) → apad → atrim al film, e tutte vengono mixate con amix (normalize=0, duration=first) sul suono delle clip e sul letto sotto l’unico limitatore asoftclip; i dati del film portano sound_strips e mix_peak. Una striscia il cui file non c’è più rifiuta il render indicando il suo percorso e la sua traccia. Esportazione: ogni traccia è una traccia audio FCP7 a sé (clipitem con ingresso/uscita, keyframe di livello, <enabled>FALSE</enabled> per un mute) e ogni striscia un livello After Effects chiamato <track> · <title>.
transitions[]: un oggetto tipizzato che possiede un CONFINE
"transitions": [{"id": "t1", "after_clip": "<clip id>",
"kind": "dissolve" | "fade_black", "duration": 0.5}]
Una dissolvenza incrociata sono due clip nello stesso secondo, e la regola della corsia immagine di una sola clip alla volta (clips_overlap) è portante: quindi una transizione non è una sovrapposizione. Nomina la clip in USCITA e sta sul taglio tra essa e la successiva nell’ordine del film; una per confine. I film_start/film_end delle clip non si muovono e il film resta lungo esattamente quanto dice la timeline. Il render prende metà della durata di coda extra da oltre il punto di uscita della clip in uscita e metà di testa extra da prima del punto di ingresso della clip in ingresso (materiale sorgente che le rifilature hanno lasciato indietro), divide il concat dell’immagine sul confine e unisce le due parti con xfade (fade / fadeblack) centrato sul taglio. Il suono non ha bisogno di nulla di nuovo: segue il percorso della corsia (_sb_split_audio_plan) esattamente come un J-cut.
duration viene limitata a ogni lettura (transition_duration) a min(asked, half the shorter neighbour, 2.0 s) e agganciata a un numero pari di fotogrammi; il documento conserva il numero digitato. Un lato senza materiale di riserva viene rifiutato: transition_no_handles nomina il lato e la mancanza (“clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there”). Ogni codice di transizione (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) è un errore; nessuno è in WARNING_CODES. render rifiuta con la stessa frase. Una still e uno slug hanno tutti i margini che si possano chiedere.
overlays[]: schede, matte e titoli
kind è still | video | text. Un kind esplicito prevale; senza, decide il suffisso del percorso (.png/.webp/.tif sono still), quindi ogni sovrapposizione scritta prima dell’esistenza dei titoli si legge com’era. Un titolo è una sovrapposizione i cui pixel li disegna il render:
{"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 è in px su un fotogramma alto 1080 e scala con il film; x/y sono l’ancoraggio come frazioni del fotogramma; align dice quale bordo del testo sta su x. overlay_text() è l’unico accessor e lo stile viene scritto solo dove differisce dai valori predefiniti. Il font è un FILE: LTX_TITLE_FONT, altrimenti il primo di TITLE_FONT_CANDIDATES presente sulla macchina, verificato prima che ffmpeg venga costruito; se non ce n’è nessuno, render risponde 400 con una frase invece di dare un film con un buco. Il raster è un PNG RGBA a dimensione di fotogramma accanto al film (.titles/) fatto passare per la stessa catena di sovrapposizioni di una scheda caricata, quindi un titolo eredita alfa, dissolvenze e z-order della corsia. I titoli vengono disegnati sul palco nel DOM con lo stesso ancoraggio e la stessa dimensione; non viaggiano nell’esportazione NLE (nessun percorso).
audio: la colonna sonora, come oggetto sulla timeline
"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
"offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
| Campo | Significato |
|---|---|
offset | Il secondo della TRACCIA che suona al tempo 0 del film. Significa questo da prima che esistesse l’editor, quindi ogni documento su disco continua a funzionare. Ora può essere negativo: la traccia inizia -offset secondi dentro il film, con silenzio davanti. |
trim_start / trim_end | Punti di ingresso/uscita DENTRO la traccia, in secondi di traccia. Assente significa non rifilata, ed è per questo che un edit.json scritto prima è ancora valido: nessun campo, nessuna rifilatura, stesso filtergraph. Una rifilatura alla fine della traccia o oltre non è una rifilatura, e normalise_edit la elimina: una maniglia trascinata fino in fondo lascia un grafo identico byte per byte. |
music_window(audio, duration=…) è l’unico posto in cui questi valori diventano i numeri di cui ffmpeg e ogni esportatore hanno bisogno: start = max(trim_start, offset) (una rifilatura di testa e un offset positivo sono lo stesso gesto da due direzioni; vince quella che taglia di più), end o None per “riproduci fino alla fine”, e delay/film_start = start - offset. Rifilare il bordo sinistro non fa scorrere il resto della traccia prima: sarebbe un ripple, e la musica non fa ripple, quindi i secondi che una rifilatura di testa toglie tornano come silenzio davanti. Una finestra che le rifilature chiudono del tutto restituisce “nessuna musica” invece di un atrim a lunghezza zero che ffmpeg rifiuta.
Bozze, backup e cronologia: tre cose diverse
Le bozze sono variazioni con nome dello stesso film, in drafts/ con un index.json che nomina quella attiva. Una board che ha solo edit.json ha esattamente una bozza e l’ha sempre avuta; semplicemente non aveva un nome per essa. load_draft_index la nomina in uscita invece che in un passaggio di riscrittura, così l’aggiornamento non può avvenire a metà.
POST /storyboard/edit/draft è una route con cinque verbi: sono cinque modifiche allo stesso puntatore attivo, e dividerle significherebbe cinque posti in cui quel puntatore può sbagliare:
op | Campi extra | Effetto |
|---|---|---|
new | name, from=current | Nuova bozza, vuota o copiata da ciò che è sullo schermo. Diventa attiva. |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | Mette prima da parte la bozza attiva corrente: non la perde mai. |
new, duplicate, delete e activate restituiscono 409 con busy: true mentre quel film è in rendering: il render sta leggendo questo documento clip per clip, e scambiare la timeline sotto di esso è lo stesso rischio che import-shots e restore rifiutano.
Il backup è nostro, il salvataggio è dell’utente. POST /storyboard/edit/backup scrive history/backup-<draft>.json e nient’altro: niente edit.json, niente revisione, nessun controllo di conflitto. La bozza salvata dall’utente resta esattamente ciò che ha salvato per ultimo. Viene esposta da GET …/drafts come backup e offerta, mai applicata: recover la adotta, discard-backup la butta via.
La cronologia è due corsie più una corsia di conservazione, distinte dal prefisso del nome del file invece che aprendo i file: una potatura che deve leggere cinquanta documenti per decidere cosa eliminare fallisce a metà al primo corrotto:
| Prefisso | Cosa | Potato? |
|---|---|---|
edit-r* | Un’istantanea automatica. | Sì, limitato a EDIT_HISTORY_KEEP (50). |
save-r* | Un salvataggio premuto dall’utente. | Mai. |
keep-r* | Una versione che l’utente ha nominato (version). | Mai. |
Ogni salvataggio archivia il suo predecessore prima che il nuovo documento arrivi (~5 KB ciascuno). Un errore nella cronologia non deve mai bloccare un salvataggio: perdere una briciola non è niente rispetto al rifiutarsi di conservare l’arrangiamento sullo schermo. origin è anche impresso dentro il JSON, per qualsiasi cosa legga un file da sola.
Gestione dei risultati
POST /output/delete
| Campo | Tipo | Nota |
|---|---|---|
path | stringa | Deve stare sotto mlx_outputs/. |
POST /output/hide, POST /output/show, POST /output/show_all
Nascondono/mostrano i risultati nella galleria senza eliminare il file.
POST /output/open_folder
Apre nel Finder la cartella che contiene il risultato (Mac).
Licenze dei modelli (4.19.8)
GET /licences
Ogni licenza su cui il pannello chiede conferma, con lo stato di accettazione di questo Mac:
{"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Chiavi: h3, ideogram4, yue2,
flux1_dev, fibo. La voce di H3 porta anche territory_notice, excluded_territories, report_line,
report_url e credit_line.
POST /licences/accept
Campi del form key=<licence key> e accept=1 (la casella che l’utente ha spuntato). Registra l’accettazione per
la version corrente della licenza in state/model_licences.json (più un file marcatore che l’installer di H3
legge) e restituisce {"ok": true, "key": ..., "record": {...}, "licence": {...}}. Una versione
di licenza cambiata chiede di nuovo. Accettare per conto di qualcuno è accettare al suo posto: un agente dovrebbe mostrare prima
all’utente i termini di GET /licences.
Helper / sistema
POST /helper/restart
Riavvia il sottoprocesso helper caldo (usato dopo modifiche alle impostazioni che richiedono un processo nuovo).
POST /stop_comfy
Chiude un processo ComfyUI se Phosphene ne ha avviato uno.
GET /version/check, POST /version/pull
Aggiornamento automatico dal repository GitHub. /version/pull è solo un git pull:
non esegue scripts/post_update.sh, quindi ciò che un Update installa (nuovi
pacchetti, pesi) non viene installato da lui. Dalla 4.17.4 il pannello installa da solo, al prossimo avvio,
un separatore vocale di sincronizzazione labiale mancante (vedi
/a2v/separator).
POST /engine/repair
Riesegue solo il passaggio dell’ambiente del motore (scripts/pinokio/ltx_engine_env.sh,
lo stesso passaggio che esegue Install): reinstalla in background i pacchetti Python del motore di render
nel suo venv. Nessun download, nessuna ricostruzione del venv, nessun Stop.
Risponde 202 (avviato), 200 {nothing_to_do} (il motore va bene) oppure 409
(una riparazione è in corso, oppure installing: true - l’Install di Pinokio sta ancora
scrivendo il venv). Avanzamento ed esito viaggiano su GET /status -> engine_env
(ok, fault, installing, repair.{state, active, log, error}).
POST /h3/repair
4.19.5. Riesegue solo scripts/pinokio/h3_deps.sh sul checkout di Hailuo H3:
reinstalla i pacchetti Python di H3 nel suo venv, all’insieme con cui questa versione
è stata testata (scripts/pinokio/h3_constraints.txt, passato con -c; uv
riporta dentro tutto ciò che ne è fuori). Nessun peso, nessun Stop: il pannello non
importa mai il venv di H3. Risponde 202 (avviato) oppure 409 (H3 non è installato, un
render H3 è in corso, o una riparazione è già in corso). Avanzamento ed esito
viaggiano su GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Un render H3 su un venv fuori dall’insieme viene rifiutato all’avvio con
H3 cannot start: the Hailuo H3 venv ... e questa riparazione sulla scheda.
Notifiche push: l’avviso di completamento per una scheda chiusa
Il suono nella scheda e l’avviso del browser (Impostazioni → Avvisi di completamento) richiedono che la pagina
sia aperta. Web Push no: il browser tiene una sottoscrizione per questa origine, il
pannello firma ogni messaggio con una coppia di chiavi VAPID che genera una volta
(state/vapid.json), e il servizio push del browser sveglia /sw.js per mostrare la
notifica. Nessun relay: il pannello scrive direttamente al fornitore del browser. Offerto
solo quando pywebpush si importa (GET /settings → push_available).
| Route | Cosa |
|---|---|
GET /sw.js | il service worker, servito dall’ambito radice con Service-Worker-Allowed: / |
GET /push/key | { ok, available, public_key, subscriptions }: la chiave pubblica VAPID con cui il browser si sottoscrive (503 quando non disponibile) |
POST /push/subscribe | form subscription = il JSON di PushSubscription; una voce per endpoint |
POST /push/unsubscribe | form endpoint |
POST /push/test | invia “This is what a finished render will say.” a ogni sottoscrittore; { ok, sent } |
Ogni lavoro che termina done o failed invia Phosphene — render done /
— a render failed con l’etichetta del lavoro (o i primi 60 caratteri del suo
prompt), fuori dal blocco della GPU, solo mentre notify_done è attivo. Una sottoscrizione
che il fornitore segnala come scomparsa (404 / 410) viene eliminata.
POST /settings
| Campo | Tipo | Nota |
|---|---|---|
| (qualsiasi chiave di impostazione) | stringa | Vedi state/panel_settings.json per l’insieme canonico. |
notify_done | 1/0 | Avvisi di completamento: un suono nella scheda quando un render finisce o fallisce, e una notifica del browser quando la scheda è in background e la persona le ha consentite. Attivo per impostazione predefinita; GET /settings lo restituisce. |
POST /prompt/enhance
Codificato come form. Riscrive in anticipo un prompt con Gemma. Usato dai pulsanti Migliora del pannello (Video e Sincronizzazione labiale).
| Campo | Nota |
|---|---|
prompt | obbligatorio |
mode | t2v (predefinito), i2v o a2v (Sincronizzazione labiale: il prompt helper i2v più la legge del prompt per la sincronizzazione labiale) |
preserve_tokens | elenco JSON (o elenco separato da virgole) di parole che il risultato deve mantenere, esatte nelle maiuscole: parole trigger |
translate | 0 mantiene un prompt non latino nella sua lingua; per impostazione predefinita traduce in inglese |
loras | 4.18.0: elenco JSON dei percorsi dei LoRA installati sul render. Il pannello legge di ciascuno nome, parole trigger e guida (altrimenti la descrizione del creatore) dalla libreria dei LoRA (i percorsi che non elenca vengono ignorati) e ne passa al massimo 4, limitati, all’helper come testo di riferimento delimitato. Un LoRA le cui parole trigger mancano tutte nel risultato si vede rimettere in testa la prima. |
Restituisce { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] }; { error } con 409 mentre un render occupa la GPU.
409 needs_pack (4.20). Migliora funziona con Gemma 3, che una nuova installazione scarica in background dopo il primo avvio (vedi deferred_downloads sotto GET /status). Finché non è su disco la route risponde 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state } con pack_state uno tra downloading, queued, waiting_disk, missing, e non chiede mai all’helper di caricarlo. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan e /train/auto-caption rispondono con la stessa forma per lo stesso motivo. POST /models/download repo_key=<needs_pack> lo scarica subito: mentre il fetcher in background occupa lo slot di download risponde 202 { queued: true } e porta il pacchetto in testa alla coda ({ already: true } quando è quello che sta scaricando).
POST /upload
multipart/form-data. Carica un’immagine di riferimento per le modalità I2V o keyframe. Restituisce {"path": "<absolute path under panel_uploads/>"}.
Formato JSON del sidecar
Ogni clip completata scrive un sidecar in <output>.mp4.json accanto all’MP4. Schema (semplificato):
{
"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 }
}
Leggi i sidecar per confrontare le esecuzioni senza interrogare di nuovo il pannello.
Ricetta di produzione (validata il 2026-05-15)
Per il lavoro video con LoRA di personaggio, la ricetta bloccata validata:
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
Tempo su M4 Max 64 GB: ~7:06 per clip da 7 s a 1024×576, ~3:24 a 736×416.
Esempio completo: un agente che pilota il pannello
Invia una clip con due LoRA, fai polling finché non è finita, stampa il percorso del risultato. Solo libreria standard.
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')}")
Questo è lo schema completo: invia → fai polling → leggi il percorso del risultato.
Cosa è stato rimosso (e cosa lo ha sostituito)
La funzione dei flussi agentici nel pannello (il pianificatore di inquadrature guidato dalla chat) è stata rimossa il 2026-05-15. Un’istantanea precedente alla rimozione è conservata su GitHub con il tag pre-agent-removal-2026-05-15.
Tutto ciò che faceva la chat (pianificare più inquadrature, generare immagini di ancoraggio candidate, fare il render I2V condizionato su quelle ancore, gestire le sessioni) lo può fare un agente esterno tramite l’API documentata sopra. In particolare:
- Pianificazione delle inquadrature: ragionamento testuale lato agente, senza coinvolgere il pannello.
- Generazione delle ancore:
POST /image/generate. - Dall’ancora al video:
POST /queue/addconmode=i2veimage=<anchor_path>. - Stato della sessione: lo mantiene l’agente all’esterno.
Gli agenti esterni possono usare i flussi di lavoro documentati tramite questa API.
Fonte: docs/API.md nel repository pubblico. Rivisto per questo sito prima della pubblicazione. Tradotto dall'originale inglese. Suggerisci una modifica.