Doku / API und Agenten
HTTP-API für Agenten
Diese Website dokumentiert ausgewählte unterstützte Abläufe und Felder, nicht die vollständige interne API.
Verwende eigene oder stilisierte Charaktere oder deine eigene Darstellung mit dokumentierter Einwilligung. Jede Darstellung einer anderen erkennbaren Person erfordert deren dokumentierte Einwilligung. Beachte die Richtlinie zur zulässigen Nutzung für alle Referenzbilder, Trainingsdaten, Audiodateien und Ergebnisse.
Externe Agenten (Claude Code, Codex, OSS oder alles, was HTTP spricht) steuern Phosphene über diese API. Der Chat im Panel wurde am 2026-05-15 entfernt: Im Panel steckt kein Agent mehr. Alles, was der Chat früher konnte, kann ein externer Agent über diese Endpunkte erledigen.
Fertige Tools auf dieser API: der Befehl phosphene und ein MCP-Server für Claude Code, Codex oder jeden MCP-Client, in agents/. Siehe Agent-Tools.
Server
- Basis-URL:
http://127.0.0.1:8198bei einer normalen Installation.8199ist der Port des DEV-Profils, und jedes Beispiel auf dieser Seite nutzt ihn, weil die Beispiele gegen dieses Panel geschrieben wurden. Die Regel steht in einer Zeile im Quellcode (mlx_ltx_panel.py:275):DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, überschreibbar mitLTX_PORT. Wenn eine Anfrage hier nichts zurückgibt, sprichst du fast sicher einen Port an, auf dem kein Panel läuft: Probiere den anderen. - Prozess:
mlx_ltx_panel.py(im Stammordner des Repos) - Übertragungsformat: formularkodierte
POST-Bodys; JSON-Ausnahmen stehen beim jeweiligen Endpunkt. Antworten sind HTTP/1.0 (der Standard vonBaseHTTPRequestHandler, nie überschrieben), daher schließt die Verbindung nach jeder Anfrage, und es gibt kein Keep-Alive zum Pipelining. - Authentifizierung: keine, nur an Loopback gebunden.
Konventionen
- Jede JSON-Antwort hat
Content-Type: application/json. - Fehler liefern
{"error": "<message>"}plus einen HTTP-Status außerhalb von 2xx. - 451
licence_required(4.19.8). Eine Anfrage, die ein Modell herunterladen oder ausführen würde, dessen Lizenz ein ausdrückliches „Ich akzeptiere“ verlangt (Hailuo H3 mit der MiniMax H3 Community License und die nichtkommerziellen Modelle Ideogram 4, YuE2, FLUX.1 Krea [dev] und Bria FIBO), antwortet mit HTTP 451 und{"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"}, bis diese Lizenz auf diesem Mac einmal akzeptiert wurde. Gilt für/queue/add,/queue/retry,/queue/batch,/image/generate,/h3/turbo/install,/h3/tristep/install,/music/install,/music/cover/installund/music/lora/fetch; ein Auftrag, der auf anderem Weg ankommt, scheitert mit demselben Satz. Lies die Bedingungen mitGET /licencesund akzeptiere sie mitPOST /licences/accept(unten) oder einmal im Panel, das den Bildschirm von selbst zeigt. - Der Namensraum
/agent/*ist reserviert und entfernt: Jeder Pfad unter/agent/außer/agent/image/configliefert 410 Gone mit{"error": "agentic flows removed; see docs/API.md"}. Neue Endpunkte sollten nicht unter/agent/hinzugefügt werden.
Generierung: Aufträge einreichen und verwalten
POST /queue/add: ein Video-Rendering einreihen
Fügt der Warteschlange des Panels einen Auftrag hinzu. Kehrt sofort zurück; der Helper rendert ihn asynchron.
Formularfelder (alle erforderlich, sofern nicht als optional markiert):
| Feld | Typ | Hinweis |
|---|---|---|
mode | t2v | i2v | extend | keyframe | a2v | v2a | image | Auftragsart. v2a (Sound hinzufügen) gibt es nur für Hailuo H3. |
prompt | string | Vollständiger Prompt-Text. Triggerwörter für LoRAs kommen hierhin. |
negative_prompt | string | Optional. Wird nur berücksichtigt, wo die Pipeline Classifier-Free Guidance ausführt: high, extend, keyframe, a2v. Die destillierten Pfade quick / balanced / standard haben keinen Guidance-Zweig und ignorieren es (früher wurden die Begriffe in den Prompt eingefaltet, wodurch das Modell sie zeichnete, #81). |
width, height | int | Beide durch 32 teilbar. |
frames | int | Muss frames % 8 == 1 erfüllen. 121 = 5 s, 169 = 7 s, 241 = 10 s. |
frame_rate | float | Standard 24. LTX ist auf 24 fps trainiert; Abweichungen verschlechtern die Qualität. |
character_strength | float | Standard 1.0. Die Stärke des Charakter-LoRA, 0 bis 2. |
seed | int oder -1 | -1 = zufällig. |
quality | quick | balanced | standard | high | Für Arbeit mit Charakter-LoRAs high verwenden. balanced leitet Clips über 121 Frames stillschweigend auf den destillierten Q4-Transformer um, bei dem aktuelle LoRAs die Identität verlieren. |
stage1_steps, stage2_steps | int | HQ-Pipeline in zwei Stufen. Validierte Standardwerte: 10 / 3. |
teacache_thresh | float | Validiertes Plateau der Beschleunigung bei 1.8–2.0. Unter 1.6 keine Beschleunigung. Höher = aggressiveres Caching. |
cfg_scale | float | Classifier-Free Guidance. 3.0 ist der validierte Standard. |
bongmath_max_iter | int | Obergrenze der inneren Sampler-Schleife. 100 ist das Maximum von Upstream. |
upscale | off | fit_720p | fit_1080p | Optionale Nachbearbeitung. |
upscale_method | lanczos | pipersr | Wenn upscale != off. |
accel | off | (andere Modi, siehe Panel-Quellcode) | Regler für die Beschleunigung. |
enhance | true | false | Bei true schreibt Gemma den Prompt vor dem Kodieren um. Setze false, wenn der Prompt LoRA-Triggerwörter enthält, denn der Umschreiber kann sie entfernen. |
hdr | true | false | HDR-IC-LoRA-Durchgang. |
image | path | Nur I2V. Absoluter Pfad zu einem Referenz-PNG/JPG. Erforderlich: Seit v4.6.1 wird ein fehlendes oder leeres image bei i2v / i2v_clean_audio beim Start des Auftrags mit einer lesbaren Fehlermeldung abgewiesen, statt auf examples/reference.png zurückzufallen, eine Demodatei, die keine Installation je ausgeliefert hat (dieser Standard war der am weitesten verbreitete Render-Fehler in der Flotte: image not found: <path>, 35 Ereignisse bei 22 Personen in 14 Tagen). LTX_DEFAULT_IMAGE liefert weiterhin einen Standard, wenn es auf eine tatsächlich vorhandene Datei zeigt. |
audio | path | Optionale Audio-Referenz. |
label | string | Optionales UI-Label für die Karte in der Warteschlange. |
temporal_mode | native | fps12_interp24 | windows. windows rendert über ein 121-Frame-Fenster hinaus als SEQUENZ: ein generate, dann je ein extend pro weiterem Fenster auf dem behaltenen Ende des vorherigen (ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), auf die gewünschte Länge gekürzt. Braucht das Q8-Add-on und eine Stufe, die Verlängern erlaubt; sonst mit einem Satz abgelehnt. Wird am Auftrag als long_mode gespeichert. | |
window_prompts | JSON-Array (oder durch Zeilenumbrüche getrennt) mit einer Zeile pro Fenster; Zeile 1 leer = der Prompt; eine spätere leere Zeile hält den vorherigen Moment. Der Prompt jedes späteren Fensters ist seine Zeile ZUERST, dann der Fortsetzungssatz, dann Throughout: <window_invariants>.: der H3-Chain-Vertrag und die Regel, mit der Bewegung zu beginnen. | |
window_invariants | Was sich zwischen Fenstern nicht ändern darf (wer, wo, Licht, Objektiv). Wird in jedes spätere Fenster neu eingefügt. | |
loras | JSON-kodiertes Array | Siehe LoRA-Payload unten. |
Felder für Hailuo H3 (engine=h3), 4.19. H3 rendert t2v, i2v, keyframe, extend, a2v und v2a; jeder Modus nach i2v braucht ein Flag im INSTALLIERTEN Runner (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), und ein Auftrag für einen Modus, den der Runner nicht hat, wird mit einem Satz auf LTX gerendert (Sound hinzufügen hat keine LTX-Spur und wird stattdessen mit dem Update-Satz abgelehnt).
| Feld | Typ | Hinweis |
|---|---|---|
h3_quality, h3_length | string | Die Zelle. h3_quality=fast_hd = der Fast-Durchgang mit 640×384 plus Hochskalieren & Gesichtskorrektur auf 1280×768, zusammen eingereiht; Fast und die Korrektur sind erzwungen. |
h3_continuity | on | off | Standard on: Ein verketteter Abschnitt übernimmt die letzten 17 Frames des vorherigen und deren Ton (--chain-context-frames 17). off = die Übergabe mit einem Standbild. |
start_image, end_image, keyframes_json | path / JSON | mode=keyframe. Bei H3 ist das Startbild optional (ein Endbild allein ist die Last-Frame-Aufgabe von MiniMax); die Beats von keyframes_json landen bei ihrem frame_index auf der 24-fps-Zeitleiste. |
video_path, h3_extend_seconds | path / float | mode=extend: ein beliebiger Clip, fortgesetzt ab seinen letzten 17 Frames und deren Ton; danach werden 0,5 bis 15 s angefügt. |
audio, image, frames, audio_start_time, audio_stem_auto | mode=a2v mit engine=h3: Der Track wird exakt übernommen und das Bild dazu gerendert; frames (24 fps) ist die Länge, begrenzt auf das nach audio_start_time verbleibende Audio und auf 30 s; audio_stem_auto=on konditioniert auf die getrennte Gesangsspur und liefert das Original aus. | |
video_path | path | mode=v2a (Sound hinzufügen, nur H3): Das Bild des Clips bleibt exakt erhalten, und nur sein Ton wird erzeugt; bis zu 60 s. |
h3_prompt_guards | "" | off | all | comma list | Welche Prompt-Guards auf den Text laufen, den der Runner kodiert (h3_prompt_guards.py): ellipsis, spoken, hands, nouns. Leer = der Standardsatz (ellipsis, spoken, hands; nouns ist optional); off sendet den Prompt unverändert. Die angewendeten Guards werden als h3_prompt_guards_applied festgehalten; prompt behält, was getippt wurde. |
LoRA-Payload: Das Feld loras ist ein JSON-kodiertes Array aus Objekten {path, strength}. Stapel so viele wie nötig: Bei Hailuo H3 braucht das Stapeln das wiederholbare --lora der Engine (/status.h3.loras.max_stack > 1); ein älteres Paket nimmt einen Adapter, und das Feld h3_lora_slot entscheidet, ob er an Turbo oder an das LoRA geht.
[
{"path": "<panel-root>/mlx_models/loras/explorertrn_v2.safetensors", "strength": 1.0}
]
Rückgabe: {"ok": true, "id": "j-<...>"}: die Auftrags-ID zum Abfragen.
Beispiel:
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 für /queue/add (identisches Verhalten).
POST /queue/retry
Reiht einen Auftrag aus dem Verlauf mit denselben Parametern erneut ein. params.open_when_done wird auf false erzwungen (Wiederholungen laufen im Hintergrund).
| Feld | Typ | Hinweis |
|---|---|---|
id | string | ID des Quellauftrags. |
Gibt {"ok": true, "id": "<new-id>", "source_id": "<old-id>"} zurück.
POST /queue/remove
Entfernt einen eingereihten Auftrag. (Ein laufender Auftrag kann nicht entfernt werden; nutze /stop.)
| Feld | Typ | Hinweis |
|---|---|---|
id | string | Auftrags-ID. |
Gibt {"ok": true} zurück.
POST /queue/clear
Leert die Warteschlange. Gibt {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null} zurück. Das Token macht DIESES Leeren einmalig 60 s lang rückgängig (POST /queue/restore mit {"token": "<hex>"} stellt genau die entfernten Aufträge wieder her, mit den ursprünglichen IDs, vor allem, was seither eingereiht wurde). Ein späteres Leeren löst es ab; ein abgelaufenes oder verbrauchtes Token antwortet mit 410.
POST /queue/pause, POST /queue/resume
Pausiert oder setzt den Dispatcher der Warteschlange fort (wirkt sich nicht auf einen bereits laufenden Auftrag aus).
POST /stop
Fordert den laufenden Auftrag zum Stoppen auf. Gibt {"ok": true} zurück. Optional ?id=<job id> (das sendet das Panel): Stoppt nur, wenn dieser Auftrag noch der laufende ist, sonst 409 {"stale": true} und nichts wird gestoppt. /stop/after_part nimmt dasselbe id.
POST /queue/batch
Reicht mehrere Prompts als einen Stapel ein.
| Feld | Typ | Hinweis |
|---|---|---|
prompts | string | Durch Zeilenumbrüche getrennte Prompts. |
(plus alle Standardfelder von /queue/add, auf jede Zeile angewendet) |
Status: Auftragsstatus abfragen
One Shot: eine eigene Tür, POST /oneshot (2026-09-08)
One Shot ist ein Workflow-Tab und eine vollwertige API. Ein Skript sendet dasselbe Dokument, das der Tab sendet (ein JSON-Objekt), und bekommt den eingereihten Auftrag zurück:
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"}}
| Feld | Typ | Standard | Bedeutung |
|---|---|---|---|
prompt | str | erforderlich | Die ganze Einstellung, einmal: wer, wo, Tageszeit und Wetter, der Ton. Ohne Beats trägt er alle fünf Sekunden. |
seconds | int | 60 | Einer von 30 / 45 / 60 / 90 / 120. Jeder andere Wert wird abgelehnt, nie gerundet (eine 75 wurde früher als ein Clip gerendert). |
engine | ltx / h3 | ltx | LTX rendert Teile von 10 s (Gesichter, Stimmen, Dialog); H3 rendert Teile von 15 s (Bewegung, Landschaften). H3 wird abgelehnt, wenn es nicht installiert ist. |
quality | str | Standard der Engine | LTX: quick / balanced / standard / high; mit Charakter: draft / pro / high / high_720p; H3: draft / standard / high / native. |
beats | Liste oder Text mit Zeilenumbrüchen | keine | Eine Zeile pro fünf Sekunden. Eine leere Zeile hält diesen Moment; überzählige Zeilen werden verworfen. Fehlt es, ist der Prompt jeder Beat. |
camera | str | "" | Eine Bewegung für die ganze Einstellung, mit Richtung und Tempo; wird in jeden Teil übernommen (take_camera). |
image | path | keine | Ein Startbild, das schon auf diesem Mac liegt: erst mit POST /upload hochladen (Feld image) und den zurückgegebenen path übergeben. Macht den ersten Teil zu i2v. |
character_id | str | keine | Ein trainierter Charakter (nur LTX). Setzt die Qualität standardmäßig auf pro, den Export auf 720p Sharp und handoff auf speech. character_strength optional. |
handoff | last / speech | last (speech mit Charakter) | Wo ein Teil übergibt: sein letztes Frame oder ein sprechendes Frame, wobei das letzte Wort in den nächsten Teil mitgenommen wird (siehe den Take-Vertrag unten). |
light_lock / retake | on/off | on | Der Kontinuitätssatz in jedem Beat; ein Retake gegen Drift pro Teil. |
seed, label, no_music, turbo (H3), upscale, upscale_method | Wie bei /queue/add. |
GET /oneshot/options: was dieser Mac kann: 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}: Der Storyboard-Planer schreibt aus dem Prompt einen Beat pro fünf Sekunden (blockiert 20 bis 40 s): {ok, beats:[…]}.
GET /oneshot/status: current (id, label, part, parts, lipsync pro Teil, drift, handoff), queued, recent und die eigenen log-Zeilen des Takes.
Intern ist jedes One Shot der Take-Vertrag unten: POST /oneshot bildet das Dokument auf das Formular von make_job ab, sodass der Tab, die API und /queue/add exakt denselben Auftrag rendern.
Ein Take: take_seconds + beats bei POST /queue/add
Ein Clip, der länger ist als ein einzelner Durchgang, auf beiden Engines. take_seconds ist einer von 30 / 45 / 60 / 90 / 120; beats ist eine JSON-Liste (oder Text mit Zeilenumbrüchen) mit einem Prompt pro fünf Sekunden: Ein leerer Beat hält den vorherigen Moment, überzählige werden verworfen. Gar keine Beats (das Feld fehlt, ist leer oder enthält nur leere Zeilen) heißt, dass der prompt jeder Beat ist: Die Einstellung ist der Prompt, über den ganzen Take gehalten. Vor 4.12.1 wurde dieser Fall so gerendert, dass jedes Fenster nur den Haltesatz bekam, ein Take über nichts. Der Take überstimmt das eigene Längenfeld der Engine. Auf BEIDEN Engines wird er als TEILE gerendert, verkettet durch Übergabe des letzten Frames: run_take_job_inner führt pro Teil ein gewöhnliches Rendering aus, jeweils ausgehend vom letzten Frame des vorherigen (i2v, verankert), blendet die Teile in der Galerie aus und fügt sie zu <name>_take<seconds>s.mp4 zusammen:
| Engine | Teil | was make_job macht | Worker |
|---|---|---|---|
ltx | 10 s = zwei Beats = 241 Frames (ein Take von 45 s endet mit einem Teil aus einem Beat mit 121 Frames) | frames = 241, temporal_mode = native (ein Take ist nie die Windows-Kette, was auch immer das Formular sendet) | ein gewöhnliches LTX-Rendering pro Teil über run_job_inner: Teil 1 ist t2v oder i2v aus dem eigenen image des Auftrags, wenn er als i2v kam; jeder spätere Teil ist i2v aus dem letzten Frame des vorherigen mit i2v_reference_mode = anchor. Jede Qualität; das Q8-Paket wird nur für eine HQ-Qualität gebraucht, wie bei einem einzelnen Clip |
h3 | 15 s = drei Beats | h3_length=15s, h3_chain_prompts = die Beats des ersten Teils | ein gewöhnliches H3-Rendering pro Teil (--first-frame aus dem vorherigen letzten Frame) |
Zwei optionale Felder, beide standardmäßig on:
| Feld | off bedeutet |
|---|---|
take_light_lock | der Kontinuitätssatz (take_light_lock(), „it is still night…“) wird NICHT an die Beats angehängt; take.light_lock ist "", und ein leerer Beat hält allein mit dem Haltesatz |
take_retake | ein Teil, dessen Licht über TAKE_DRIFT_MAX hinaus driftet, wird wie gerendert behalten, statt einmal mit neuem Seed wiederholt zu werden; take.retake ist false |
take_camera | optional, freier Text, eine Bewegung für die GANZE Einstellung („a slow, steady clockwise arc around the table at eye level, wide to close“). take_camera_lock() setzt sie an den Anfang des Prompts von Teil 1 („Camera: …; one steady move at one speed, never stops, never changes direction“) und in jedem späteren Teil einen Satz, dass die Kamera sich bereits so bewegt und in derselben Richtung mit demselben Tempo weiterfährt: Die Übergabe verankert das Bild zwischen den Teilen, nicht die Bewegung, und die Naht war als Kamera sichtbar, die an jedem Übergang die Richtung wechselte oder anhielt und neu startete. Bleibt es leer, bekommen spätere Teile trotzdem den allgemeinen Kontinuitätssatz. Festgehalten als take.camera |
take_handoff | last (Standard) oder speech. Mit speech schneidet der Runner jeden Teil außer dem letzten auf einem SPRECHENDEN Frame: take_handoff_points() findet, wo die Zeile endet (Audio-RMS), und hält das Bild TAKE_TALKING_BACK = 0,2 s davor an (der Mund noch mitten im Wort: der einzige gemessene Anker, der die Stimme auf den Mund des nächsten Teils trägt: +0,54 / +0,47 gegenüber −0,15…−0,01 bei geschlossenem Mund), behält den Ton bis zum Ende der Zeile plus ihr Ausklingen von 0,4 s und mischt dieses Ende (part{k}_tail.wav, amix normalize=0) über den Anfang des nächsten Teils (part{k+1}_lead.mp4): ein J-Cut, damit das letzte Wort ganz zu hören ist. Schreibe den ersten Beat jedes Teils so, dass er IN STILLE BEGINNT, damit das Ende Platz hat. Das stille Ende nach jeder Zeile wird verworfen, daher ist der Take kürzer als seine Nennlänge; der letzte Teil wird nicht gekürzt. Jeder gesprochene Teil wird von take_lipsync_score() bewertet und bis zu TAKE_LIPSYNC_RETAKES = 2-mal mit neuen Seeds wiederholt (IDs -pNl, -pNl2), wenn er unter TAKE_LIPSYNC_MIN = 0,20 liegt; der beste Clip bleibt, und sein Wert wird in job["take_lipsync"] festgehalten. Festgehalten als take.handoff |
params.take am Auftrag: {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}; frames ist der ganze Take (seconds·24+1 bei LTX), part_frames ein voller Teil. Das Sidecar des Ergebnisses trägt take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake}, wobei parts die ausgeblendeten Teildateien sind, und image nur, wenn der Take mit dem eigenen Anker des Nutzers begann. Parameter laden stellt einen Take als Take wieder her.
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 ist die Zahl der Teile auf beiden Engines. Die Minuten sind Teile × der Einzelclip-Preis eines Teils aus demselben Kostenmodell wie jede andere Schätzung (H3: die gemessene 15-s-Zelle; LTX: die 10s-Zelle der Qualität in LTX_TIERS, das Ein-Beat-Ende mit ihrer 5s-Zelle); null, wo dieser Mac keine Zahl hat. needs_q8 ist jetzt immer false: Ein LTX-Take rendert auf dem, worauf die gewählte Qualität rendert.
GET /status
Jede Zeile in outputs[] trägt q: die durchsuchbaren Wörter des Ergebnisses, kleingeschrieben, aus seinem Sidecar im Listendurchlauf gebaut, der es ohnehin liest: Prompt, Label, Modus, Qualität, Engine, Charakter, Seed, WxH, Nf, LoRA-Dateinamen, der Name des Modellordners, der zeitliche Modus und windows. Das Suchfeld der Galerie ist ein Teilstring-Test über name + q; jedes getippte Wort muss passen, und beim Tippen werden die älteren Ergebnisse nachgeladen, sodass die Suche alles abdeckt.
Jede Videozeile trägt außerdem silent: true, wenn der Clip keinen Ton hat (keine Audiospur im mp4-Header oder eine Spur, die nie über −80 dB steigt), false mit Ton, null, solange es noch nicht bekannt ist. Das Lesen des Headers geschieht inline; die Pegelprüfung läuft einmal pro Datei in einem Hintergrund-Thread und wird pro (mtime, size) in state/output_silence.json zwischengespeichert, sodass eine Abfrage nie etwas dekodiert. Die Karte in der Galerie und der Player bieten bei einem silent-Clip Sound hinzufügen an, wenn /status.h3.video_to_audio wahr ist.
Gibt den vollständigen Zustand des Panels zurück.
{
"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...", ... ]
}
Bedeutung der Felder:
deferred_downloads(4.20):{ active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. Die Pakete, die eine frische Installation für nach dem Start eingereiht hat (state/install_deferred.json, geschrieben von install.js;required_files.json -> install.after_start).stateistidle,starting,downloading,waiting(ein anderer Download hält den Platz),waiting_disk(das Panel hältinstall.background_floor_gbfrei;messagesagt, wie viel freizugeben ist),retry_wait,failedoderdone. Leer undidlebei jeder Installation, die install.js nie eingereiht hat: Eine aktualisierte Installation lädt nichts herunter.downloadträgtbackground: true, solange der Fetcher den Platz hält.current: der aktuell laufende Auftrag (nullim Leerlauf).gpu(4.19.10):{ busy, holder, since, outside_queue }: das eine GPU-Tor des Panels.holderist"queue"für den Auftrag incurrentoder das, was die GPU außerhalb der Warteschlange hält:"image"(ein Rendering im Bild-Studio),"character_sheet","enhance"(Prompt Enhance),"lyrics","update"(das Skript nach dem Update). Ein Client, der Arbeit nicht unterbrechen darf (das Panel stoppen oder aktualisieren), wartet, biscurrentnullist, die Warteschlange pausiert oder leer ist UNDgpu.busyfalseist.app_models(nur Mac-App): der eigene Modell-Download der App:{ state, packs, active, locked, done_bytes, total_bytes }.locked(4.19.10) ist wahr, solange die App ihre Download-Sperre hält (<Phosphene home>/.locks/models.lock); das Panel bietet dann für diese Pakete keinen Download an und lehnt einen mit 409app_downloadingab. Ein zweitesscripts/fetch_pack_release.pyauf einem Paketordner, in den schon geschrieben wird, stoppt unverändert mit Exit-Code 75.queue: wartende Aufträge, FIFO-Reihenfolge.history: abgeschlossene oder fehlgeschlagene Aufträge. Jeder Eintrag hatstatus,elapsed_sec,output_path,raw_path(nativ vor dem Hochskalieren),error.log: rollender Puffer der stdout-Zeilen des Helpers (die letzten ~50 Aufträge).
Polling-Schleife: GET /status alle 15 bis 30 s. Ein Auftrag ist beendet, wenn sein status done, failed, cancelled, stopped oder error ist. Bis dahin ist er queued oder running.
stopped heißt, dass der Nutzer das Rendering absichtlich gestoppt hat (siehe POST /stop?mode=early). Es ist kein Fehler: Es wurde nichts gespeichert, weil der Clip nie fertig wurde, aber nichts ist schiefgegangen. stopped_reason trägt den eigenen Satz des Runners.
current.progress
Vorhanden, solange ein Auftrag läuft.
{
"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 fehlt, sofern die Live-Vorschau nicht an ist (Einstellungen → Speicher / Tempo) und der winzige Decoder nicht installiert ist. meaningful wird serverseitig berechnet und darf nicht neu abgeleitet werden: Die Regel unterscheidet sich je Pipeline: Schätzung 6 von 8 im destillierten Ablauf, dessen erste Schätzungen noch im Grunde Rauschen sind; Schätzung 2 im zweistufigen HQ-Pfad, der den Denoiser pro Schritt der Stufe 2 zweimal auswertet. Ein Client, der Schätzungen zählt, müsste wissen, welcher Ablauf läuft.
POST /stop?mode=early
Bittet das laufende Rendering, an der nächsten Forward-Grenze zu stoppen, indem ein ABORT-Sentinel angelegt wird. Der Runner beendet sich mit 75 (ein eigener Code, der „der Nutzer hat das gestoppt“ bedeutet, kein Absturz), und der Auftrag endet mit status: "stopped" ohne Ausgabedatei. Gibt 404 zurück, wenn nichts rendert, und 409, wenn das Rendering keine Live-Vorschau hat, über die gestoppt werden kann (nutze das harte POST /stop, das den Helper beendet).
Hinweis zur Kodierung: Der Log-Puffer kann wörtliche Steuerzeichen aus Prompts mit eingebetteten Zeilenumbrüchen enthalten. Entferne sie vor dem Parsen als JSON:
import re, json
raw = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', ' ', raw)
data = json.loads(raw, strict=False)
LoRAs
GET /loras
Gibt {"user": [...], "curated": [...], "loras_dir": "...", ...} zurück. Jeder Eintrag hat id, name, path, filename, size_bytes, recommended_strength, kind (train_character für über das Panel trainierte LoRAs; sonst null), adapter_verdict (siehe unten) und CivitAI-Metadaten, falls bekannt.
adapter_verdict: ob diese Datei überhaupt etwas bewirkt
Ein LoRA kann vollständig trainieren, ein gültiges Safetensors schreiben, ohne Warnung laden und nichts verändern: Die gelernten Deltas sind numerisch zu klein, um das Modell zu bewegen. Jede strukturelle Prüfung besteht, weil jede strukturelle Prüfung fragt, ob die KEYS passen, und keine fragt, ob etwas darin steckt (#61, #62).
adapter_verdict (_adapter_verdict) wird aus dem Block adapter_strength des Sidecars gelesen und ist einer von:
| Wert | Bedeutung |
|---|---|
ok | Gemessen, und der Delta-RMS liegt im Arbeitsbereich. |
weak | Gemessen, und die Deltas liegen bei oder unter WEAK_DELTA_RMS (2.0e-4). Die Datei bleibt; das Rendering sieht sehr wahrscheinlich aus, als gäbe es kein LoRA. |
unknown | Von einem Build trainiert, der nicht gemessen hat. Kein Synonym für weak: Schweigen ist keine Schwäche, und jedes LoRA, das älter ist als die Messung, liest sich so. |
Alles andere ist das, was der Trainer es genannt hat, unverändert durchgereicht.
Aufrufer sollten weak anzeigen, bevor ein Rendering darauf verwendet wird, um es herauszufinden, und unknown nicht ausschmücken.
GET /train/list trägt dasselbe Urteil plus adapter_advice: ein Satz, der nennt, was dagegen zu tun ist, leer bei ok oder unknown. Er berücksichtigt die Hardware: Auf einem Mac unter 64 GB sagt er nicht „train again on High“, weil diese Maschine das geprüfte Rezept nicht erreichen kann (siehe den Abschnitt zu den Profilen unten). Der Tab Training des Panels zeigt ihn als Banner über den Chips der trainierten Charaktere und in der Verlaufszeile des fertigen Auftrags; ein Urteil, auf das ein Nutzer nicht reagieren kann, ist eine Messung, keine Antwort (#62).
GET /hf/loras
Hugging Face als durchsuchbare Quelle neben CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1. Phosphene nennt keine Organisation: Die Anfrage ist eine Suche (leer = der Standardsuchbegriff der Lane), eine Autorenliste oder ein Repo; die Ergebnisse werden nach Lane aus Repo-Name und Tags gehalten, und die größte .safetensors jedes Repos plus sein Beispielclip werden zu einem Eintrag in derselben Form, die das CivitAI-Raster rendert (name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface"). Pro Lane und Anfrage zehn Minuten zwischengespeichert.
POST /hf/loras/download
Formular repo, filename, meta (das Eintrags-JSON). Lädt über huggingface_hub herunter (mit dem gespeicherten HF-Token, falls vorhanden) in das LoRA-Verzeichnis der Lane, führt die H3-Layout-Prüfung aus und schreibt dasselbe Sidecar wie eine CivitAI-Installation plus source, hf_repo, hf_url. Gibt { ok, skipped, name, path, sidecar_path, lane, layout, converted } zurück.
GET /civitai/download/state · POST /civitai/download/cancel (4.18.0)
POST /civitai/download nimmt ein optionales Formularfeld token (8-64 Zeichen, A-Z a-z 0-9 _ -), das der Aufrufer wählt. Solange dieser Download läuft, gibt GET /civitai/download/state?token=… { ok, state: "running"|"cancelled", bytes, total, name } zurück (404, sobald er beendet ist), und POST /civitai/download/cancel mit token stoppt ihn beim nächsten 256-KB-Block: Die Teildatei wird entfernt, nichts wird registriert, und die eigene Antwort des Downloads ist { ok: false, cancelled: true, error }. Ohne Token läuft ein Download genau wie vorher.
GET /loras/updates
Fragt CivitAI, ob ein installiertes LoRA mit einer civitai_id in seinem Sidecar eine neuere Version hat (modelVersions[0].id ≠ die civitai_version_id des Sidecars). Eine Anfrage pro solchem LoRA; nichts wird heruntergeladen.
{ "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": "..." } ] }
Das Update zu installieren ist das gewöhnliche POST /civitai/download mit diesem download_url + meta; die neue Datei landet neben der alten, die bleibt, bis sie gelöscht wird.
POST /loras/guide
Formular: path (ein installiertes LoRA aus GET /loras). Das Planer-Modell schreibt einen Absatz als Anleitung (was das LoRA tut, wie man es promptet, mit welcher Stärke man beginnt, womit es kollidiert) aus dem eigenen Namen, der Beschreibung und den Triggerwörtern des Sidecars und speichert ihn im Sidecar unter guide; Zeilen aus GET /loras tragen dann guide. Wird mit 409 abgelehnt, solange ein Rendering läuft (der Planer ist ein 12B-Modell).
Gibt { ok, guide } zurück.
POST /loras/refresh
Durchsucht mlx_models/loras/ neu. Gibt dieselbe Nutzlast wie /loras zurück.
POST /loras/delete
| Feld | Typ | Hinweis |
|---|---|---|
id | string | LoRA-ID aus /loras. |
Löscht die Datei. Gibt {"ok": true} zurück.
POST /h3/loras/import
multipart/form-data. Installiert einen Hailuo-H3-Adapter, den du schon hast, in die eigene LoRA-Bibliothek von H3 (mlx_models/hailuo-h3/loras/ oder wo das installierte Paket sie ablegt). Bewusst NICHT /upload: Referenzmedien können beliebige Bilder oder Audiodateien sein, während ein H3-Adapter den Layout-Vertrag des Runners bestehen muss, bevor er in der Auswahl erscheinen darf.
| Feld | Typ | Hinweis |
|---|---|---|
file | file | Genau eine .safetensors. Der Dateiname wird auf seinen Basisnamen reduziert und bereinigt; er darf nicht mit einer Datei kollidieren, die schon in der Bibliothek liegt. |
Der Body wird in ein verstecktes Staging-Verzeichnis gestreamt, nicht gepuffert, sodass ein Adapter von mehreren Gigabyte etwa 1 MiB residenten Speicher kostet. Content-Length ist erforderlich und auf H3_LORA_UPLOAD_MAX_BYTES (4 GiB) begrenzt.
Was mit der Datei geschieht, der Reihe nach: abgelegt unter .import.<pid>.<tid>/<name> → _h3_lora_prepare (bei einem ComfyUI-Repack wird der Namensraum diffusion_model. an Ort und Stelle entfernt, ein reines Umschreiben des Headers) → die Prüfungen von Nutzlast und Zielmodulen, die nur beim Import laufen → os.replace in die Bibliothek → Sidecar-JSON. Eine Ablehnung in irgendeinem Schritt hinterlässt nichts.
Gibt zurück:
{
"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 wird ins Sidecar geschrieben und vom Regler für die Stärke pro LoRA in der Auswahl übernommen. Der H3-Loader wendet B @ A an und kein Alpha, daher braucht ein Adapter, dessen PEFT-alpha/rank nicht schon in lora_B eingerechnet ist, diese Zahl hier; sie wird gemeldet, nie als Grund für eine Ablehnung verwendet.
Fehler: 411, wenn Content-Length fehlt oder null ist, 413, wenn der Body die Grenze überschreitet, 400 bei einer schlechten Datei (falsche Endung, leer, doppelter Name, unbrauchbares Layout, fehlerhafte Nutzlast, falsches Modell), sonst 500. Jede Meldung nennt die Datei, die der Nutzer gewählt hat.
Training
POST /train/upload
multipart/form-data-Upload. Fügt einem Trainingsdatensatz ein Bild hinzu: Diese Route nimmt eine Datei pro Anfrage, keinen Stapel. Sende die Bilder in einer Schleife und gib die zurückgegebene train_job_id bei jedem Aufruf nach dem ersten wieder mit, damit der ganze Satz in einem Verzeichnis landet.
| Feld | Typ | Hinweis |
|---|---|---|
job_id | string | Beim ERSTEN Aufruf optional (es wird eine neue ID erzeugt), danach erforderlich, damit der Stapel zusammenbleibt. Beachte den Namen: job_id, nicht train_job_id; die Antwort liefert ihn als train_job_id zurück. |
file | file | Genau EIN PNG/JPG/JPEG/WEBP/BMP oder eine .txt-Beschreibung. |
Der Request-Body ist auf TRAIN_MAX_BYTES_PER_IMAGE (32 MB) begrenzt. Da die Grenze für die ganze Anfrage gilt und die Route eine Datei nimmt, wird ein Body mit mehreren Dateien abgelehnt, selbst wenn jedes einzelne Bild klein ist.
Gibt den Zustand des Datensatzes zurück (train_job_id, Zahl der Bilder usw.).
POST /train/start
Startet das Training eines Charakter-LoRA. Das Panel ruft lora_lab.train_character auf und streamt Fortschrittsereignisse zurück in STATE['log'].
| Feld | Typ | Hinweis |
|---|---|---|
train_job_id | string | Aus /train/upload. |
trigger | string | Trigger-Token, z. B. explorertrn. Muss zusammengesetzt, selten und nur aus Buchstaben sein, damit es nicht mit normaler Sprache kollidiert: Ziffern werden zu einzelnen, sehr häufigen Tokens (mrz07 → m / rz / 0 / 7), und jeder Trigger, der hier eine Identität getragen hat, bestand nur aus Buchstaben; das Panel schlägt <3 consonants>trn vor (mrztrn) und protokolliert einen Hinweis, wenn ein Trigger Ziffern enthält (#62). Das Charakter-LoRA landet unter mlx_models/loras/<trigger>_v2.safetensors. |
preset | quick | medium | high | Hyperparameter-Preset. In v4.6.1 geändert: Ohne Angabe gilt jetzt high für train_type=character und quick für train_type=style (TRAIN_DEFAULT_PRESET); früher gab es für beide quick, die Stufe, die nie eine Identität getragen hat (#62). Siehe die Tabelle unten: Die Zahl der Schritte ist keine Konstante, und auf einem Mac unter 64 GB ist es sonst auch nichts. |
image_count | int | Vom Panel anhand der hochgeladenen Bilder bestätigt. |
Erweiterte Überschreibungen (alle optional, mit den Preset-Standards als Rückfall):
| Feld | Typ |
|---|---|
rank, alpha, steps, lr, resolution | int / float |
caption_strategy | class_word | trigger_only | auto_caption |
crop_strategy | center |
Gibt {"ok": true, "id": "j-<...>"} zurück. Verfolge den Fortschritt über /status (der Trainingsauftrag erscheint in current, dann in history).
Was die Presets tatsächlich sind
Die Schritte werden abgeleitet, nicht festgelegt: steps = epochs × image_count, mindestens 1 und durch das max_steps des Presets gedeckelt (_preset_steps_for, mlx_ltx_panel.py:1629). Die Obergrenze gehört zum Vertrag des Servers: Ein handgeschriebener API-Aufruf darf auf einem Mac mit knappem Speicher keinen Lauf mit mehreren Tausend Schritten einreihen können.
Auf einem Mac mit 64 GB oder mehr (TRAIN_PRESETS, mlx_ltx_panel.py:1558):
preset | Epochen | Rank | Auflösung | max_steps | Für Identität geprüft? |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | Nein. Das Etikett sagt „Identität ungeprüft“. |
medium | 60 | 16 | 576 | 12000 | Nein. Genauso. |
high | 100 | 32 | 512 | 20000 | Ja: das validierte v2-Rezept (Aria_v2, Bizarro_v2). Der Standard und der, den das Etikett mit „Empfohlen“ auszeichnet. |
Gemessen mit lora_compat.py: Rank-32-Adapter, die eine Identität tragen, liegen bei 5,4e-04 bis 1,6e-03 delta_rms; die quick-Läufe mit Rank 8 von zwei unabhängigen Nutzern maßen 1,54e-04 und 1,98e-04, beide bei oder unter der Untergrenze WEAK_DELTA_RMS von 2,0e-04 (#62).
high ergibt also bei 50 Bildern 5000 Schritte, bei 20 Bildern 2000, bei 300 Bildern 20000 (gedeckelt). Nur das Rank-32-Rezept wurde je einem Menschen vorgelegt und für gut befunden.
⚠️ Unter 64 GB ist jedes Preset stillschweigend ein anderes Preset
_select_train_profile (mlx_ltx_panel.py:1650) läuft einmal beim Import und wenn der gesamte RAM 0 < ram < 64 GB beträgt, verändert es TRAIN_PRESETS und TRAIN_STYLE_PRESETS an Ort und Stelle. Die Namen ändern sich nicht. Die Zahlen alle:
preset | Epochen | Rank | Auflösung | max_steps | Zielmodule |
|---|---|---|---|---|---|
quick | 2 | 4 | 384 | 120 | kompakter Satz |
medium | 5 | 8 | 384 | 300 | kompakter Satz |
high | 10 | 8 | 448 | 500 | kompakter Satz |
make_job spiegelt dieselben Begrenzungen serverseitig, daher werden auch rank / steps / resolution, die als erweiterte Überschreibungen übergeben werden, gedeckelt (max_rank 8, max_resolution 448, max_steps 500): Du kannst auf dieser Hardware nicht das geprüfte Rezept anfordern und es bekommen.
Das ist ein bewusster Kompromiss, und der Grund dafür ist real: Das volle LTX-LoRA-Training mit 512 px materialisiert Rückwärts-Aktivierungen für den Dev-Transformer, und ein Mac mit 48 GB gerät ins Swap-Thrashing und wird nie fertig. Aber sei dir klar, was das bedeutet: Auf einem Mac unter 64 GB gibt es kein Preset, das das Rezept trainiert, das irgendjemand geprüft hat. Rank 8 bei höchstens 500 Schritten ist genau das Regime, für das adapter_verdict gebaut wurde, also rechne hier häufiger mit weak und lies es als „diese Hardware, dieses Rezept“ statt als „dieser Datensatz“.
GET /status legt das aktive Profil als train_profile offen (key: compact_training | full_training, dazu label, ram_gb, max_rank, max_resolution, max_steps, note) und die tatsächlich geltenden Tabellen selbst als train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Lies diese, bevor du einem Preset-Namen traust: Es sind die Werte nach der Veränderung, also der einzige Ort, an dem sich die beiden Tabellen oben zur Laufzeit unterscheiden lassen.
Das Trainer-Ereignis adapter_strength
Kein Analytics-Ereignis: Nichts davon verlässt die Maschine (siehe docs/ANALYTICS.md für die vollständige Liste dessen, was das tut). Es ist ein Fortschrittsereignis im Stream des lora_lab-Subprozesses, das einmal ausgegeben wird, nachdem der Trainer die Datei gemessen hat, die er gerade geschrieben hat (mlx_ltx_panel.py:18005). Das Panel protokolliert den Median des Delta-RMS, das Maximum und wie viele Module tragen, und beendet den Auftrag dann im Zustand WARNUNG statt mit einem schlichten done, wenn das Urteil nicht ok ist. Das Urteil wird als adapter_strength: {"verdict": …} ins Sidecar des LoRA geschrieben und als adapter_verdict bei /loras und /characters wieder ausgelesen.
POST /train/install
Nach erfolgreichem Training wird das LoRA automatisch nach mlx_models/loras/ kopiert. Dieser Endpunkt dient der ausdrücklichen Neuinstallation und der Aktualisierung der Metadaten.
POST /train/delete, POST /train/remove-image
Löscht Trainingsdatensätze bzw. einzelne Trainingsbilder.
Charaktere
Trainierte Charakter-LoRAs als Bündel entdecken und steuern.
GET /characters
Gibt {"characters": [...]} zurück. Jeder Eintrag beschreibt einen Charakter, der in mlx_models/loras/ entdeckt wurde:
| Feld | Typ | Hinweis |
|---|---|---|
id, trigger | string | Derselbe Wert: das seltene Trigger-Token. |
name, pronoun, subject_noun | string | Aus der optionalen mlx_models/characters/<trigger>/bundle.json. |
face_lora_path | string | Absoluter Pfad zu <trigger>_v2.safetensors. Immer vorhanden. |
sample_image_url | string | null | URL zu einem Vorschaubild aus dem Trainingsdatensatz. |
sheet_image_path, sheet_image_url | string | null | Das erzeugte Charakterblatt mit mehreren Ansichten (mlx_models/characters/<trigger>/sheet.png), sofern es existiert. Erzeugt von POST /characters/<id>/sheet/generate, ausgeliefert von GET /characters/<id>/sheet. |
Regel für die Erkennung: <trigger>_v2.safetensors ist erforderlich; alles andere ist optional.
GET /characters/<id>/preview
Liefert das Beispielbild aus dem Training für den Charakter (PNG/JPEG).
GET /characters/<id>/sheet
Liefert das erzeugte PNG des Charakterblatts. ?w=<px> gibt über dieselbe Resize-Lane wie /image?w= eine zwischengespeicherte Vorschau (JPEG) zurück. 404, bis ein Blatt erzeugt wurde.
POST /characters/<id>/sheet/generate
Rendert aus dem Referenzbild des Charakters (zuerst der Avatar aus dem Bundle, ersatzweise ein Trainingsbeispiel) ein Turnaround-Blatt mit mehreren Ansichten und setzt es zu mlx_models/characters/<id>/sheet.png plus einem Sidecar sheet.json (phosphene/character_sheet@1) zusammen. Synchron wie /image/generate: Der Aufrufer blockiert während des ganzen Renderings; 429, wenn die GPU schon von einem Rendering-, Trainings- oder Bildauftrag gehalten wird (nie eingereiht).
Content-Type: application/json. Jedes Feld ist optional (ein leerer Body rendert das Standardblatt mit 3 Ansichten):
{
"engine_override": "qwen_edit_inline",
"views": ["front", "profile_left", "three_quarter"],
"wardrobe": "a red flight jacket",
"seed": -1
}
Es werden nur Engines akzeptiert, die Referenzen berücksichtigen (hidream_*_inline, qwen_edit_*_inline, mock_inline): Eine reine Text-Engine würde einen Fremden rendern. seed >= 0 gibt der Ansicht i den Seed seed + i, sodass sich ein ganzes Blatt aus einer Zahl reproduzieren lässt. Jeder Ansichts-Prompt bindet die Garderobe an die Referenz („wearing exactly the same clothes as in the reference image“); wardrobe wiederholt das Outfit zusätzlich in Worten. Ansichten nach der ersten verketten außerdem die erste gerenderte Ansicht als zweite Referenz: Bei einem dunklen Referenzbild haben Einzelrenderings von der Seite die Haarfarbe über Seeds und Formulierungen hinweg neu erfunden, und eine saubere Frontalansicht aus demselben Lauf verankert die Merkmale wieder, die die rohe Referenz zu wenig festlegt. Der Bildausschnitt pro Ansicht kann trotzdem driften (ein Motiv außermittig in einer Ansicht): Erzeuge neu oder variiere den Seed. Bei Erfolg wird in bundle.json das Feld preview nur auf sheet.png gesetzt, wenn es null war: Eine kuratierte Vorschau wird nie überschrieben.
POST /characters/<id>/generate
Setzt das gesperrte Produktionsrezept zusammen und reiht ein T2V-Rendering ein. Der Endpunkt akzeptiert prompt_body, framing, duration, quality und einen optionalen ganzzahligen seed (-1 bedeutet zufällig, wie bei /queue/add). Für exakte Wiedergabe- und Debug-Aufrufe können Aufrufer full_prompt sowie HQ-Überschreibungen wie stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step und audio_skip_step übergeben.
Bildgenerierung (getrennt vom Video)
POST /image/generate
Erzeugt Standbilder über die mitgelieferte Bild-Engine (mflux, BFL, Mock-Backend). Pro Aufruf austauschbar.
Content-Type: application/json. Nutzlast:
{
"prompt": "...",
"n": 4,
"engine_override": "mflux",
"aspect": "1:1",
"refs": ["/path/to/ref.png"],
"loras": [{"path": "...", "strength": 1.0}]
}
Siehe image_engine.py für Backend-spezifische Optionen.
GET /agent/image/config, POST /agent/image/config
Aus Gründen der Abwärtskompatibilität mit dem Frontend des Bild-Studios unter dem alten Pfad /agent/ belassen. Liest und schreibt die Konfiguration der Bild-Engine (Standard-Backend, mflux-Familie, BFL-Schlüssel usw.). Trotz des Pfads ist das die Konfiguration der Bild-Engine, NICHT der entfernte Chat-Agent.
Storyboard: einen Film planen, dann drehen
Ein Board ist ein Film: ein Konzept, eine Besetzung, Schauplätze und eine nummerierte Liste der Einstellungen. Jedes Rendering, das es startet, läuft über denselben Vertrag make_job → Warteschlange wie /queue/add; keine dieser Routen hat einen eigenen Ausführungspfad. Boards liegen unter state/storyboards/<board_id>/, wobei storyboard.json atomar geschrieben wird: Renderings laufen stundenlang, und ein zerrissenes Board würde den ganzen Lauf kosten.
Lesen
| Route | Liefert |
|---|---|
GET /storyboard/list | Jedes Board, das neueste zuerst. |
GET /storyboard/get?id=<bid> | Ein Board-Dokument. |
GET /storyboard/films | Die fertig zusammengesetzten Filme auf der Platte: Player-Pfad, Laufzeit, Bildgröße, Größe auf der Platte, wann er erstellt wurde. list_outputs durchsucht OUTPUT/*.mp4 per Glob und steigt nie hinab, daher wäre ohne dies das Einzige, was die Funktion erzeugt, das Einzige, was die App nicht zeigen kann. |
Schalter im Briefing (bei plan)
| Feld | Board-Schlüssel | Wirkung |
|---|---|---|
auto | auto | nach dem Plan: jede Einstellung rendern, schneiden, zusammensetzen, ohne weitere Schaltflächen |
anchor_stills | anchor_stills | Bevor eine Text- oder Charakter-Einstellung rendert, erzeugt ein gewöhnlicher Bildauftrag ihr erstes Frame (still_job_id → still; das Blatt des Charakters ist über qwen_edit_inline die Referenz, wenn es existiert), und der Clip wird daraus als i2v · Anker gerendert. Ein fehlgeschlagenes Standbild setzt still_error, und die Einstellung wird einmal ohne Anker gerendert |
long_windows | long_windows | Eine LTX-Einstellung über 121 Frames wird als temporal_mode=windows gerendert (eine Kette auf dem Q8-Dev-Transformer), mit dem Stil des Boards und dem Schauplatz der Einstellung als window_invariants, statt passend gekürzt zu werden. Extend kann pro Fenster kein Bild neu einspeisen, daher wird eine verankerte lange Einstellung nur durch ihr erstes Fenster verankert |
take_seconds | take_seconds | ein Take: Der Film ist eine Einstellung von 30 / 45 / 60 / 90 / 120 s. Der Planer schreibt einen Beat pro 5 s (_sb_take_concept), das Board behält EINE Einstellung mit beats (collapse_take), die Karte zeigt die Beats zum Bearbeiten, und shot_to_job sendet take_seconds + beats: der Take des Tabs Video, sodass das Rendering an beiden Türen dasselbe ist. 0 schaltet es aus |
Jedes Feld wird nur geändert, wenn es gesendet wird; ein fehlendes Feld behält den Wert des Boards.
POST /storyboard/restill: Formular id, n, optional pass: vergisst das Standbild der Einstellung n und den daraus gerenderten Clip, schaltet anchor_stills ein, falls es aus war, und rendert diese Einstellung allein (erst das Standbild, dann den Clip daraus). Dieselben Ablehnungen wie bei render (Planung läuft, Rendering läuft schon).
Schreiben: POST /storyboard/<action>
Der Director. plan akzeptiert soundtrack (eine Audiodatei auf diesem Mac) und bars_per_shot (1/2/4, Standard 2). Mit einem Track ist der Plan ein MUSIKVIDEO: beat_map() (dieselbe Anpassung, die das Vorbereiten im Editor ausführt) macht aus den Downbeats Slots von bars_per_shot Takten, die Zahl der Einstellungen ist die Zahl der Slots (die Chips für shots treten zurück; gedeckelt bei STORYBOARD_MAX_SHOTS mit einem Hinweis), das Briefing des Planers trägt die BPM, die Slot-Länge, eine Bogen-Anweisung und zwei Gesetze (jede Beschreibung beginnt mit der Bewegung; kein Dialog, der Track ersetzt den Ton jedes Clips), und die duration_s jeder geplanten Einstellung ist ihr Slot plus ein Handle von einer Sekunde, mit slot: {start, end} an der Einstellung. Die Song-Karte entscheidet, wie oft. song_map() (storyboard_edit) legt ABSCHNITTE auf dasselbe Takt-Raster, {start, end, label, energy, brightness}, mit den Labels intro / verse / chorus / bridge / outro nach Position, relativer Lautstärke und Helligkeit, und director_pacing() macht aus bars_per_shot eine Schrittweite pro Abschnitt: Der Chorus schneidet doppelt so oft, Intro und Outro halb so oft. Jeder Slot trägt seinen section; das Briefing sagt dem Planer, welche Einstellungen in welchen Abschnitt fallen und wie heiß er ist; ein Track, den die Karte nicht lesen kann, wird mit der Basis-Schrittweite geschnitten, und das Protokoll sagt es. Das Board hält soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections} fest, der erste Auto-Schnitt des Editors nutzt diesen Track, wenn das Vorbereiten keinen anderen zwischengespeichert hat (der Film öffnet also schon im Takt geschnitten), und GET /storyboard/edit liefert sections, damit das Lineal den Bogen zeichnen kann. Ein falscher Pfad ist ein 400, bevor der Planer läuft; die Planer-Stufe grid wird gemeldet, während der Beat gelesen wird.
Auto. plan akzeptiert auto=1: Sobald der Plan steht, startet das Draft-Rendering jeder Einstellung von selbst (_sb_auto_after_plan, sobald der Planer den Speicher zurückgegeben hat), und wenn der Render-Thread mit jeder gerenderten Einstellung fertig ist, wird der Film geschnitten (_sbe_auto_edit, im Takt, wenn es einen Track gibt) und vom selben Assembler zusammengesetzt, den auch Rendern nutzt (_sb_auto_film); das Board hält auto_film fest. Eine Einstellung, die nicht gerendert wurde, lässt den Film warten, und das Protokoll sagt, wie viele. Stopp stoppt weiterhin das Rendering; der Schnitt und der Film sind die gewöhnlichen und können danach neu geschnitten werden.
Formularkodiert, sofern nicht anders angegeben. id ist durchgehend die Board-ID.
| Aktion | Felder | Hinweis |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | Planen oder neu planen. 409, solange der Renderer Speicher hält oder der eine Planer-Slot belegt ist. shots wird eingehalten oder abgelehnt, nie stillschweigend durch eine andere Zahl ersetzt. Eine Neuplanung ERGÄNZT Schauplätze und Garderobe, statt sie zu überschreiben. |
cancel | id | Gibt einen Planer-Slot frei. |
save | JSON {id, board} | Schreibt ein von Hand bearbeitetes Board. |
grade | id, n, grade, note | Bewertet eine Einstellung. |
estimate | id, pass, only | Schätzung von Kosten und Dauer, bevor etwas ausgegeben wird. |
render | id, pass, only, out, music, music_mode | Dreht das Board. |
stop | id | Stoppt das laufende Board-Rendering. |
replan-shots | id, ns | Würfelt benannte Einstellungen neu. Eine Reparatur, die ein Gesetz bricht, wird abgelehnt; Neuwürfe werden in den AKTUELLEN Plan eingefügt, nicht in den ursprünglichen. |
add-shot | id, path | |
import-shots | id, from, only | REFERENZ-Clips von einem anderen Board. Herkunft (imported_from), die Quell-SCHAUPLÄTZE und die Quell-BESETZUNG reisen mit: Wird eines davon zurückgelassen, geht etwas Bestimmtes kaputt. Lehnt ab, solange der Ziel-Film rendert. |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Im Finder zeigen (macOS). |
delete | id |
Board-Schema: die Geografie-Felder
Eine Einstellung wird aus ihrem Schauplatz komponiert. Seit 2026-08-18 kann ein Schauplatz auch aus mehr als einer Richtung betrachtet werden, wodurch ein Gegenschuss ein Gegenschuss ist statt eines zweiten Schauplatzes.
"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"
…}
]
| Feld | Wo | Regeln |
|---|---|---|
locations[].views | Schauplatz | Liste aus {id, name, light, description}. Fehlt, nicht [], wenn ein Schauplatz keine hat: Jedes Board, das vor den Ansichten geschrieben wurde, hat keinen Schlüssel, und eine leere Liste wäre eine neue Form, zu der der Validator ohne Nutzen eine Meinung haben müsste. IDs folgen demselben Zeichensatz wie Schauplatz-IDs. |
shots[].view | Einstellung | Eine Ansichts-ID, die zur location_id dieser Einstellung gehört. Eine Ansicht bei einer Einstellung ohne Schauplatz oder eine Ansicht, die nicht zu diesem Schauplatz gehört, ist ein Validierungsfehler (unknown_view) und scheitert genau wie ein unbekannter Schauplatz: Eine stillschweigend verworfene Ansicht komponiert den Gegenschuss aus der Beschreibung der Establishing-Einstellung, und das Auto, das die Ansicht aus dem Bild nehmen sollte, ist wieder drin, ohne dass jemand etwas sagt. |
shots[].eyeline | Einstellung | Eines von left, right, lens: eine Tatsache über das BILD, nicht über den Raum. right = die Augen gehen über den rechten Rand hinaus. Alles andere ist ein Validierungsfehler (bad_eyeline). |
Was der Server damit macht. shot_scene_text fügt die Beschreibung der ANSICHT ein, wenn eine Einstellung eine nennt, und fällt sonst auf die des Schauplatzes zurück: Ein Board ohne Ansichten oder eine Einstellung ohne Ansicht rendert also exakt wie immer. eyeline_clause setzt beim Rendern "his eyes fixed past the right edge of frame" zusammen; lens erzeugt bewusst nichts (diesen Modellen zu sagen, sie sollen in den Lauf der Kamera blicken, bringt eine steifere Darstellung als Schweigen), und es existiert, damit eine Einstellung sagen kann, dass sie die Linse hält, wodurch die 180-Grad-Prüfung „blickt in die Kamera“ von „niemand hat eine geschrieben“ unterscheiden kann.
Die 180-Grad-Regel wird durchgesetzt, nicht vorgeschlagen. Nach dem Planen geht _enforce_eyelines die Einstellungen in Bildschirm-Reihenfolge durch und dreht die zweite von zwei benachbarten Einstellungen um, die zwischen zwei verschiedenen Charakteren am selben Schauplatz schneiden und beide dieselbe Seite beanspruchen, und sagt das in warnings. Sie repariert mechanisch, weil eyeline ein diskretes Feld mit genau einem Komplement ist: Das Umdrehen kann niemandes Prosa beschädigen. Gesetze auf Prosa-Ebene bekommen stattdessen einen Modell-Roundtrip, gerade weil ihnen diese Eigenschaft fehlt.
Editor: die Zeitleiste
Der Editor ist ein Workflow auf oberster Ebene, keine Stufe des Storyboards: engine-unabhängig, öffnet sich, ohne dass ein Board gerade rendert, und sein Dokument ist edit.json im Board-Verzeichnis. Eine Videospur, eine Musikspur. Der Ton pro Clip ist standardmäßig verknüpft und lässt sich trennen (J/L-Schnitte): Das ist keine zweite Audiospur.
Lesen
| Route | Liefert |
|---|---|
GET /storyboard/edit?id=<bid> | Die Anordnung. Beim ersten Aufruf für ein Board führt es den Auto-Schnitt EINMAL aus, speichert ihn in der automatischen Spur und gibt ihn mit generated: true zurück. Jedes spätere GET ist ein Lesen der Datei. Eine beschädigte edit.json gibt 500 mit corrupt: true zurück und wird nie stillschweigend ersetzt: Das würde die Anordnung wegwerfen, von der sie eine kaputte Kopie ist. |
GET /storyboard/edit/status?id=<bid> | Der Zustand des Prepare-Auftrags. |
GET /storyboard/edit/peaks?id=<bid> | Die Wellenform. Hunderte KB: einmal abrufen, nie bei einer Abfrage. 404, bis prepare gelaufen ist. |
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4 | Ein Proxy-Video, mit Range-Unterstützung ausgeliefert. Safari spult kein <video>, dessen Server schlicht mit 200 antwortet, was den ganzen Grund für Proxys zunichtemachen würde. name muss [A-Za-z0-9._-]{1,120}\.mp4 entsprechen: Es ist ein Basisname, den der Server vergeben hat, alles andere ist ein Test. |
GET /storyboard/edit/uploads | Videos, die der Nutzer mitgebracht hat (panel_uploads/timeline/, die neuesten zuerst, auf 200 begrenzt). Bewusst aus OUTPUT herausgehalten, weshalb sie überhaupt eine Route brauchen; Bilder brauchen keine, sie landen in der Bibliothek, die die Galerie ohnehin durchläuft. |
GET /storyboard/edit/sounds?id=<bid> | Die Quelle Sound des Medienpools: {sounds: [{path, name, where, mtime}], dir}: zuerst der eigene Ordner audio/ des Films (where: "film"), dann die Sounddateien (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) oben in OUTPUT, die neuesten zuerst, auf 300 begrenzt. Keine Prüfung; die Länge wird gelesen, wenn ein Sound hinzugefügt wird. |
GET /storyboard/edit/drafts?id=<bid> | {active, drafts: [...], backup}: siehe Entwürfe unten. |
GET /storyboard/edit/versions?id=<bid> | Nur Metadaten: Name, Revision, wann behalten, Zahl der Clips, Dauer, dazu keep (= EDIT_HISTORY_KEEP, 50). Die Dokumente selbst werden einmal von restore gelesen, auf Wunsch des Nutzers. Das Öffnen des Panels darf kein Download sein. |
Schreiben: POST /storyboard/edit/<sub>
| Sub | Felder | Hinweis |
|---|---|---|
prepare | id, music, target_seconds | Baut Proxys und Peaks. 400, wenn music keine Datei ist. |
add-clip | id, from, only, path, title, kind | kind ist video | still | slug: Wer es übergibt, verhindert, dass ein Bild als Video ohne Frames landet. |
add-sound | id, path | Eine Datei für eine Audiospur: geprüft ({path, title, duration_s, has_video, imported}), 400, wenn sie keinen Ton enthält. Eine Datei außerhalb von OUTPUT wird zuerst per Hardlink (über Volumes hinweg kopiert) in den eigenen Ordner audio/ des Films gelegt, weil /file nur OUTPUT ausliefert und ein Sound, den die Vorschau nicht abspielen kann, nur ein halber Sound ist. Der Streifen wird vom Client platziert und gespeichert. |
relink | id, only | Setzt Clips auf ihre fertigen (Auslieferungs-)Dateien um. Ein fertiger RETAKE gehört nie zu diesem Stapel: Er wird gegen seinen Clip mit retake: true in den relink-Zeilen der Nutzlast angeboten und mit only=<clip id> einzeln übernommen. |
cancel | id | Bricht den Prepare-Auftrag ab. |
auto | id, music, target_seconds, min_shot, max_shot | Führt den Schnitt der Maschine erneut aus. Landet in der automatischen Spur. |
save | JSON {id, edit, expect_revision?} | Siehe unten. |
draft | id, op, slug, name, from | Siehe Entwürfe. |
backup | JSON {id, edit} | Die stille Spur. Siehe Entwürfe. |
recover | id | Übernimmt das ausstehende Backup. |
discard-backup | id | Wirft es weg. |
version | id, label | Benennt eine Version. Benennen ist nicht Speichern: kein Hochzählen der Revision, kein Schreiben in edit.json, nichts an der Zeitleiste ändert sich, weshalb es genau deshalb jederzeit sicher gedrückt werden kann. |
restore | id, file | Stellt einen Verlaufseintrag wieder her. Lehnt ab, solange der Film rendert. |
render | id, out, music, music_mode, format, size | Setzt den Film zusammen. music_mode ist replace | under. Ausgeben als: format ist h264 (Standard, das Preset des Panels) | hevc (VideoToolbox, hvc1, etwa halb so viele Bytes) | prores (422 HQ, 10 Bit 4:2:2, PCM-Ton, eine .mov, die kein Browser als Vorschau zeigt); size ist native (wie geschnitten) | 1080p | 2160p: eine Lanczos-Skalierung nach den Overlays, nur nach oben, nie ein Zuschnitt, übersprungen, wenn der Schnitt schon diese Höhe hat. finish ist none | grain | heavy_grain: bewegtes Filmkorn (noise t+u, Stärke 9 / 18), das NACH der Größe hinzugefügt wird, damit eine 4K-Ausgabe 4K-Korn bekommt; eine Behandlung zur Ausgabezeit, nie im Dokument, nie in der Vorschau oder im Export. Eine andere Ausgabe ist eine andere Datei: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. Die Fakten tragen deliver: {format, size, finish, label}. |
export-nle | id | FCP7-XML + After-Effects-JSX + verknüpfte Medien. |
reveal | id, what | Im Finder zeigen. |
generate | id, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_of | Dreht einen neuen Clip direkt in einen Slot. Mit retake_of=<clip id> ist es ein Retake: Die eigene Einstellung des Clips wird GEKLONT (Charakter, Referenzen, Schauplatz, Engine), und nur Prompt, Länge und Seed ändern sich; die neue Einstellung trägt edit_slot.retake_of, und wenn sie gerendert ist, bietet der Editor sie gegen diesen Clip an („Use it“ / „Keep the old one“). 400, wenn der Clip nicht mehr auf der Zeitleiste liegt. |
Semantik von save. revision ist der Zähler des Servers, von der Platte genommen, nie von dem, woran sich der Client erinnert: Ein veralteter Tab darf ihn nicht zurückdrehen können. Übergib expect_revision, um zu erfahren, dass dir jemand zuvorgekommen ist, statt den anderen Tab stillschweigend zu überschreiben: Eine Abweichung gibt 409 mit conflict: true und die aktuelle Revision zurück. Validierungsfehler kommen alle auf einmal zurück (errors: [...], 400), wobei die Datei auf der Platte unberührt bleibt, sodass ein Client jeden fehlerhaften Clip in einem Durchgang markieren kann, statt Maulwurf zu spielen.
Schema von edit.json
version ist 2 (EDIT_VERSION). Version 1 wird nur beim LESEN aktualisiert (migrate_edit): Die Version hochzuzählen, ohne den Lesepfad zu aktualisieren, würde nicht alte Builds abweisen, sondern jede Zeitleiste, die jemand schon hat. Eine Version aus der Zukunft bleibt unberührt, damit der Validator das Ehrliche sagen kann.
{
"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[]
| Feld | Hinweis |
|---|---|
id, path, proxy | path/proxy sind bei einem Slug null. |
start, end | Das Fenster INNERHALB der Quelle. |
film_start, film_end | Der Slot im Film. Nie unabhängig: Ein Clip läuft mit 1x, daher gilt film_end - film_start == end - start innerhalb von LENGTH_TOLERANCE (2 ms). |
kind | video (fehlend bedeutet Video: Es bei 400 Clips einzutragen würde jede edit.json auf der Maschine umschreiben, nur um zu sagen, was ihr Fehlen schon sagt), still (gehalten für die Länge seines Slots; start/end werden aus dem Slot abgeleitet, duration: null), slug (schwarz, keine Datei). |
source | auto | human. |
locked | bool. |
adjust | {brightness}, ein additiver Offset von ffmpeg eq=brightness, begrenzt auf ±BRIGHTNESS_LIMIT (0,5). Neutral ist fehlend: Den Regler zurück auf null zu ziehen hinterlässt ein Dokument, das identisch ist mit einem, das nie einen Regler hatte. |
frame | {zoom, x, y}: ein Neu-Ausschnitt. Das Bild wird zoom-fach vergrößert (1 bis 3), und das Fenster wird beim Anteil (x, y) der Quelle zentriert. Render: ein crop der eigenen Pixel der Quelle vor der Anpassung, sodass eine Zeichenfolge bei jeder Größe stimmt; Vorschau: eine CSS-Skalierung um denselben Anker (ungefähr); Export: FCP7 Basic Motion (Skalierung + Mitte) und AE-Skalierung + Position. Neutral ist fehlend; ein Slug hat nichts zum Neu-Ausschneiden. |
speed | Abspielrate, SPEED_MIN bis SPEED_MAX (0,25 bis 4,0), nur Video. Der Slot ist (end - start) / speed, daher lautet die 1x-Regel oben „bei seiner Geschwindigkeit“. Das Bild ist setpts, der Ton ist atempo, verkettet über das Fenster von 0,5 bis 2,0 bei ffmpeg hinaus, und die Hüllkurve des Tons (afx) bleibt auf der GESPIELTEN Uhr des Streifens: Ein Keyframe bei 2 s ist nach einer Zeitänderung immer noch bei 2 s des Streifens. Fehlend ist 1x. Nie automatisch gesetzt. |
audio | Der geteilte Schnitt. Siehe unten. |
clip.audio: der J-Cut und der L-Cut
"audio": {"start": 3.5, "end": 7.0, "film_start": 12.25}
Nur Videoclips. Dieselben drei Zahlen wie beim Bild, für den TON: So kann der Ton vor seinem Bild beginnen (J) oder über es hinauslaufen (L), wodurch ein Schnitt keine stumpfe Naht mehr ist.
Fehlend bedeutet verknüpft, und das ist die ganze Migration: Jeder jemals geschriebene Clip hat keinen audio-Schlüssel, und jeder davon spielt seinen eigenen Ton unter seinem eigenen Bild. EDIT_VERSION hat sich dafür nicht bewegt, und kein Dokument wurde umgeschrieben.
Das VORHANDENSEIN des Feldes ist der Schalter, nicht die Werte darin. Leite „verknüpft“ nicht daraus ab, dass audio dem Bildfenster entspricht: Das Trennen schreibt das Fenster, das der Clip schon hat, daher würde ein Clip, den der Nutzer gerade getrennt hat, als verknüpft gelesen und sich nicht ziehen lassen. Der Schalter fügt das Objekt hinzu oder löscht es; sonst entscheidet nichts. normalise_edit rundet das Feld, entfernt es aber nie, aus demselben Grund, und streicht es bei einem Standbild oder einem Slug ganz.
Audiofenster dürfen sich ebenso wenig überlappen wie die Bilder. Ein geteilter Schnitt ist eine stumpfe Naht, die woanders landet, keine Mischung: Die Mischung ist das, wofür audio_tracks da ist.
audio_tracks[]: A3, A4, … unter der Musik
"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]]}}]}]
Beliebig viele Spuren, jede mit beliebig vielen Streifen. start/end sind die In- und Out-Punkte in der Datei (ein Streifen läuft mit 1x, ist also im Film end - start lang); film_start ist eine Sekunde der Zeitleiste, mit adelay genau wie das Bett angelegt. afx ist dasselbe Hüllkurven-Objekt, das der Ton eines Clips und das Bett tragen, gelesen von audio_gain_points; die gain des Streifens und die gain der Spur (linear 0 bis 1) multiplizieren es: track_strip_gain_points ist die eine Kurve, die Vorschau, Rendering und Export lesen. Fehlend ist keine, und neutral ist fehlend: Ein Schnitt ohne Spuren hat keinen Schlüssel, daher lädt, speichert und rendert er byte-identisch; eine leere Spur bleibt erhalten.
Streifen auf derselben Spur dürfen sich nicht überlappen (audio_track_strips_overlap, ein Fehler, TOUCH_TOLERANCE für eine stumpfe Naht); Streifen auf verschiedenen Spuren überlappen und mischen sich. Formfehler: 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*.
Rendern: Jeder hörbare Streifen (nicht stumm, Spur nicht stumm, Kurve nicht still) ist nach den Overlays ein -vn -i, atrim → volume (seine Kurve auf der Uhr des Streifens) → aresample → adelay (in Samples) → apad → atrim auf den Film, und alle werden per amix (normalize=0, duration=first) über den Ton der Clips und das Bett unter dem einen asoftclip-Limiter gemischt; die Film-Fakten tragen sound_strips und mix_peak. Ein Streifen, dessen Datei fehlt, lässt das Rendering mit seinem Pfad und seiner Spur scheitern. Export: Jede Spur ist eine eigene FCP7-Audiospur (Clipitems mit In/Out, Pegel-Keyframes, <enabled>FALSE</enabled> für Stummschaltung) und jeder Streifen eine After-Effects-Ebene mit dem Namen <track> · <title>.
transitions[]: ein typisiertes Objekt, dem eine GRENZE gehört
"transitions": [{"id": "t1", "after_clip": "<clip id>",
"kind": "dissolve" | "fade_black", "duration": 0.5}]
Eine Überblendung sind zwei Clips in derselben Sekunde, und die Regel der Bildspur, dass immer nur ein Clip läuft (clips_overlap), trägt: Daher ist ein Übergang keine Überlappung. Er benennt den AUSGEHENDEN Clip und sitzt auf dem Schnitt zwischen ihm und seinem Nachfolger in Filmreihenfolge; einer pro Grenze. Das eigene film_start/film_end der Clips bewegt sich nicht, und der Film bleibt genau so lang, wie die Zeitleiste sagt. Das Rendering holt die halbe Dauer an zusätzlichem Ende von jenseits des Out-Punkts des ausgehenden Clips und die halbe an zusätzlichem Anfang von vor dem In-Punkt des eingehenden (Material der Quelle, das die Kürzungen zurückgelassen haben), teilt die Bild-Verkettung an der Grenze und verbindet die beiden Läufe mit xfade (fade / fadeblack), zentriert auf den Schnitt. Der Ton braucht nichts Neues: Er nimmt den Spurpfad (_sb_split_audio_plan) genau wie ein J-Cut.
duration wird bei jedem Lesen (transition_duration) auf min(asked, half the shorter neighbour, 2.0 s) begrenzt und auf eine gerade Zahl von Frames gerundet; das Dokument behält die getippte Zahl. Eine Seite ohne Reservematerial wird abgelehnt: transition_no_handles nennt die Seite und den Fehlbetrag („clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there“). Jeder Code für Übergänge (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) ist ein Fehler; keiner steht in WARNING_CODES. render lehnt mit demselben Satz ab. Ein Standbild und ein Slug haben alle Reserven, die man sich wünschen kann.
overlays[]: Karten, Masken und Titel
kind ist still | video | text. Ein ausdrückliches kind gewinnt; ohne es entscheidet die Endung des Pfads (.png/.webp/.tif sind Standbilder), sodass jedes Overlay, das vor den Titeln geschrieben wurde, sich liest wie zuvor. Ein Titel ist ein Overlay, dessen Pixel das Rendering zeichnet:
{"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 ist px bei einem Bild mit 1080 Höhe und skaliert mit dem Film; x/y sind der Anker als Anteile des Bildes; align sagt, welche Kante des Textes auf x sitzt. overlay_text() ist der eine Zugriff, und der Stil wird nur dort geschrieben, wo er von den Standards abweicht. Die Schrift ist eine DATEI: LTX_TITLE_FONT, sonst die erste der TITLE_FONT_CANDIDATES, die auf der Maschine vorhanden ist, geprüft, bevor ffmpeg gebaut wird; ohne eine antwortet render mit 400 und einem Satz statt mit einem Film mit einem Loch. Das Raster ist ein bildgroßes RGBA-PNG neben dem Film (.titles/), das durch dieselbe Overlay-Kette wie eine hochgeladene Karte läuft, sodass ein Titel Alpha, Ein- und Ausblendungen und Z-Reihenfolge der Spur erbt. Titel werden auf der Bühne im DOM mit demselben Anker und derselben Größe gezeichnet; sie reisen nicht im NLE-Export (kein Pfad).
audio: der Soundtrack, als Objekt auf der Zeitleiste
"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
"offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
| Feld | Bedeutung |
|---|---|
offset | Die Sekunde der SPUR, die bei Filmzeit 0 spielt. Das bedeutet es schon, seit es den Editor noch nicht gab, sodass jedes Dokument auf der Platte weiter funktioniert. Es darf jetzt negativ sein: Die Spur beginnt -offset Sekunden im Film, mit Stille davor. |
trim_start / trim_end | In- und Out-Punkte INNERHALB der Spur, in Spursekunden. Fehlend bedeutet ungekürzt, weshalb eine davor geschriebene edit.json weiter gültig ist: kein Feld, keine Kürzung, derselbe Filtergraph. Eine Kürzung am oder hinter dem Ende der Spur ist keine Kürzung, und normalise_edit verwirft sie: Ein ganz zurückgezogener Griff hinterlässt einen byte-identischen Graphen. |
music_window(audio, duration=…) ist die einzige Stelle, an der daraus die Zahlen werden, die ffmpeg und jeder Exporter brauchen: start = max(trim_start, offset) (eine Kürzung am Anfang und ein positiver Offset sind dieselbe Geste aus zwei Richtungen; was mehr schneidet, gewinnt), end oder None für „bis zum Ende spielen“, und delay/film_start = start - offset. Das Kürzen der linken Kante schiebt den Rest der Spur nicht früher: Das wäre ein Ripple, und Musik rippelt nicht; daher kommen die Sekunden, die eine Kürzung am Anfang entfernt, als Stille davor zurück. Ein Fenster, das die Kürzungen ganz schließen, gibt „keine Musik“ zurück statt eines atrim der Länge null, das ffmpeg ablehnt.
Entwürfe, Backups und Verlauf: drei verschiedene Dinge
Entwürfe sind benannte Varianten desselben Films, in drafts/ mit einer index.json, die den aktiven benennt. Ein Board, das nur edit.json hat, hat genau einen Entwurf und hatte ihn immer; es hatte nur keinen Namen dafür. load_draft_index benennt ihn beim Auslesen statt in einem Umschreib-Durchlauf, damit das Upgrade nicht halb passieren kann.
POST /storyboard/edit/draft ist eine Route mit fünf Verben: Es sind fünf Änderungen am selben Zeiger auf den aktiven Entwurf, und sie aufzuteilen wären fünf Stellen, an denen dieser Zeiger falsch sein kann:
op | Zusätzliche Felder | Wirkung |
|---|---|---|
new | name, from=current | Neuer Entwurf, leer oder von dem kopiert, was auf dem Bildschirm ist. Wird aktiv. |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | Legt zuerst den aktuell aktiven Entwurf beiseite: verliert ihn nie. |
new, duplicate, delete und activate geben 409 mit busy: true zurück, solange dieser Film rendert: Das Rendering liest dieses Dokument Clip für Clip, und die Zeitleiste darunter auszutauschen ist dieselbe Gefahr, die import-shots und restore ablehnen.
Das Backup gehört uns, das Speichern dem Nutzer. POST /storyboard/edit/backup schreibt history/backup-<draft>.json und sonst nichts: kein edit.json, keine Revision, keine Konfliktprüfung. Der gespeicherte Entwurf des Nutzers bleibt genau das, was er zuletzt gespeichert hat. Es wird von GET …/drafts als backup gezeigt und angeboten, nie angewendet: recover übernimmt es, discard-backup wirft es weg.
Der Verlauf besteht aus zwei Spuren plus einer Behalten-Spur, unterschieden am Präfix des Dateinamens statt durch das Öffnen der Dateien: Ein Aufräumen, das fünfzig Dokumente lesen muss, um zu entscheiden, was gelöscht wird, scheitert beim ersten beschädigten auf halbem Weg:
| Präfix | Was | Aufgeräumt? |
|---|---|---|
edit-r* | Ein automatischer Schnappschuss. | Ja, begrenzt auf EDIT_HISTORY_KEEP (50). |
save-r* | Ein Speichern, das der Nutzer gedrückt hat. | Nie. |
keep-r* | Eine Version, die der Nutzer benannt hat (version). | Nie. |
Jedes Speichern archiviert seinen Vorgänger, bevor das neue Dokument landet (~5 KB pro Stück). Ein Fehler im Verlauf darf nie ein Speichern blockieren: Eine Brotspur zu verlieren ist nichts gegen die Weigerung, die Anordnung auf dem Bildschirm zu sichern. origin wird außerdem im JSON selbst gestempelt, für alles, was eine Datei für sich liest.
Ergebnisse verwalten
POST /output/delete
| Feld | Typ | Hinweis |
|---|---|---|
path | string | Muss unter mlx_outputs/ liegen. |
POST /output/hide, POST /output/show, POST /output/show_all
Blendet Ergebnisse in der Galerie aus oder wieder ein, ohne die Datei zu löschen.
POST /output/open_folder
Öffnet den Ordner des Ergebnisses im Finder (Mac).
Modelllizenzen (4.19.8)
GET /licences
Jede Lizenz, nach der das Panel fragt, mit dem Zustand der Annahme auf diesem Mac: {"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Schlüssel: h3, ideogram4, yue2, flux1_dev, fibo. Der Eintrag von H3 trägt außerdem territory_notice, excluded_territories, report_line, report_url und credit_line.
POST /licences/accept
Formularfelder key=<licence key> und accept=1 (das Kästchen, das der Nutzer angehakt hat). Hält die Annahme für die aktuelle version der Lizenz in state/model_licences.json fest (plus eine Markierungsdatei, die der H3-Installer liest) und gibt {"ok": true, "key": ..., "record": {...}, "licence": {...}} zurück. Eine geänderte Lizenzversion fragt erneut. Im Namen eines anderen zu akzeptieren heißt, für ihn zu akzeptieren: Ein Agent sollte dem Nutzer zuerst die Bedingungen aus GET /licences zeigen.
Helper / System
POST /helper/restart
Startet den warmen Helper-Subprozess neu (nach Änderungen an den Einstellungen, die einen frischen Prozess brauchen).
POST /stop_comfy
Beendet einen ComfyUI-Prozess, wenn Phosphene einen gestartet hat.
GET /version/check, POST /version/pull
Selbst-Update gegen das GitHub-Repo. /version/pull ist nur ein git pull: Es führt scripts/post_update.sh nicht aus, daher wird alles, was ein Update installiert (neue Pakete, Gewichte), dadurch nicht installiert. Seit 4.17.4 installiert das Panel einen fehlenden Stimmtrenner für die Lippensynchronisation beim nächsten Start selbst (siehe /a2v/separator).
POST /engine/repair
Führt nur den Schritt für die Engine-Umgebung erneut aus (scripts/pinokio/ltx_engine_env.sh, derselbe Schritt, den Install ausführt): installiert die Python-Pakete der Render-Engine in ihrer venv im Hintergrund neu. Keine Downloads, kein Neubau der venv, kein Stopp. Antwortet 202 (gestartet), 200 {nothing_to_do} (die Engine ist in Ordnung) oder 409 (eine Reparatur läuft, oder installing: true: Das Install von Pinokio schreibt noch in die venv). Fortschritt und Ergebnis laufen über GET /status -> engine_env (ok, fault, installing, repair.{state, active, log, error}).
POST /h3/repair
4.19.5. Führt nur scripts/pinokio/h3_deps.sh auf dem Hailuo-H3-Checkout erneut aus: installiert die Python-Pakete von H3 in dessen eigener venv auf dem Stand neu, mit dem dieses Release getestet wurde (scripts/pinokio/h3_constraints.txt, mit -c übergeben; uv setzt alles, was schon außerhalb liegt, zurück). Keine Gewichte, kein Stopp: Das Panel importiert die H3-venv nie. Antwortet 202 (gestartet) oder 409 (H3 ist nicht installiert, ein H3-Rendering läuft oder eine Reparatur läuft schon). Fortschritt und Ergebnis laufen über GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Ein H3-Rendering auf einer venv außerhalb dieses Satzes wird bei seinem Start mit H3 cannot start: the Hailuo H3 venv ... abgelehnt, und diese Reparatur steht auf der Karte.
Push-Benachrichtigungen: der Hinweis bei Fertigstellung für einen geschlossenen Tab
Der Signalton im Tab und die Browser-Benachrichtigung (Einstellungen → Hinweise bei Fertigstellung) brauchen die geöffnete Seite. Web Push nicht: Der Browser hält ein Abonnement für diesen Origin, das Panel signiert jede Nachricht mit einem VAPID-Schlüsselpaar, das es einmal erzeugt (state/vapid.json), und der Push-Dienst des Browsers weckt /sw.js, um die Benachrichtigung zu zeigen. Kein Relay: Das Panel sendet direkt an den Browser-Hersteller. Wird nur angeboten, wenn pywebpush importiert werden kann (GET /settings → push_available).
| Route | Was |
|---|---|
GET /sw.js | der Service Worker, aus dem Root-Scope mit Service-Worker-Allowed: / ausgeliefert |
GET /push/key | { ok, available, public_key, subscriptions }: der öffentliche VAPID-Schlüssel, mit dem der Browser abonniert (503, wenn nicht verfügbar) |
POST /push/subscribe | Formular subscription = das JSON der PushSubscription; ein Eintrag pro Endpunkt |
POST /push/unsubscribe | Formular endpoint |
POST /push/test | sendet „This is what a finished render will say.“ an jeden Abonnenten; { ok, sent } |
Jeder Auftrag, der mit done oder failed endet, sendet Phosphene — render done / — a render failed mit dem Label des Auftrags (oder den ersten 60 Zeichen seines Prompts), außerhalb der GPU-Sperre, nur solange notify_done an ist. Ein Abonnement, das der Hersteller als verschwunden meldet (404 / 410), wird verworfen.
POST /settings
| Feld | Typ | Hinweis |
|---|---|---|
| (jeder Einstellungsschlüssel) | string | Den kanonischen Satz siehe state/panel_settings.json. |
notify_done | 1/0 | Hinweise bei Fertigstellung: ein Signalton im Tab, wenn ein Rendering fertig wird oder scheitert, und eine Browser-Benachrichtigung, wenn der Tab im Hintergrund ist und die Person sie erlaubt hat. Standardmäßig an; GET /settings gibt es zurück. |
POST /prompt/enhance
Formularkodiert. Schreibt einen Prompt vorab mit Gemma um. Wird von den Schaltflächen Verbessern des Panels genutzt (Video und Lippensynchronisation).
| Feld | Hinweis |
|---|---|
prompt | erforderlich |
mode | t2v (Standard), i2v oder a2v (Lippensynchronisation: der i2v-Helper-Prompt plus das Prompt-Gesetz der Lippensynchronisation) |
preserve_tokens | JSON-Liste (oder kommagetrennte Liste) von Wörtern, die das Ergebnis exakt in dieser Schreibweise behalten muss: Triggerwörter |
translate | 0 behält einen nicht lateinischen Prompt in seiner eigenen Sprache; standardmäßig wird ins Englische übersetzt |
loras | 4.18.0: JSON-Liste installierter LoRA-Pfade für das Rendering. Das Panel liest Name, Triggerwörter und Anleitung jedes LoRA (sonst die Beschreibung des Urhebers) aus der LoRA-Bibliothek, Pfade, die dort nicht stehen, werden ignoriert, und übergibt höchstens 4, begrenzt, als abgegrenzten Referenztext an den Helper. Ein LoRA, dessen Triggerwörter alle im Ergebnis fehlen, bekommt sein erstes Triggerwort wieder an den Anfang gesetzt. |
Gibt { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] } zurück; { error } mit 409, solange ein Rendering die GPU hält.
409 needs_pack (4.20). Verbessern läuft auf Gemma 3, das eine frische Installation im Hintergrund nach dem ersten Start herunterlädt (siehe deferred_downloads unter GET /status). Bis es auf der Platte liegt, antwortet die Route mit 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state }, wobei pack_state downloading, queued, waiting_disk oder missing ist, und bittet den Helper nie, es zu laden. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan und /train/auto-caption antworten aus demselben Grund in derselben Form. POST /models/download repo_key=<needs_pack> holt es jetzt: Solange der Hintergrund-Fetcher den Download-Platz hält, antwortet das mit 202 { queued: true } und schiebt das Paket an den Anfang der Warteschlange ({ already: true }, wenn es das gerade ladende ist).
POST /upload
multipart/form-data. Lädt ein Referenzbild für die Modi I2V oder Keyframe hoch. Gibt {"path": "<absolute path under panel_uploads/>"} zurück.
Sidecar-JSON-Format
Jeder fertige Clip schreibt ein Sidecar unter <output>.mp4.json neben das MP4. Schema (vereinfacht):
{
"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 }
}
Lies Sidecars, um Läufe zu vergleichen, ohne das Panel erneut abzufragen.
Produktionsrezept (validiert 2026-05-15)
Für Video mit Charakter-LoRA das validierte, gesperrte Rezept:
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
Wall auf einem M4 Max mit 64 GB: ~7:06 pro Clip von 7 s bei 1024×576, ~3:24 bei 736×416.
Praxisbeispiel: ein Agent als Treiber
Reiche einen Clip mit zwei LoRAs ein, frage ab, bis er fertig ist, und gib den Pfad des Ergebnisses aus. Reine Standardbibliothek.
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')}")
Das ist das ganze Muster: einreichen → abfragen → Pfad des Ergebnisses lesen.
Was entfernt wurde (und was es ersetzt hat)
Die Funktion der agentischen Abläufe im Panel (ein vom Chat gesteuerter Einstellungsplaner) wurde am 2026-05-15 entfernt. Ein Snapshot von vor der Entfernung liegt dauerhaft auf GitHub als Tag pre-agent-removal-2026-05-15.
Alles, was der Chat früher konnte (mehrere Einstellungen planen, Kandidaten für Ankerbilder erzeugen, I2V mit diesen Ankern rendern, Sitzungen verwalten), lässt sich von einem externen Agenten über die oben dokumentierte API erreichen. Im Einzelnen:
- Einstellungen planen: Textüberlegung auf Seiten des Agenten, ohne Beteiligung des Panels.
- Ankerbilder erzeugen:
POST /image/generate. - Anker zu Video:
POST /queue/addmitmode=i2vundimage=<anchor_path>. - Sitzungszustand: Der Agent hält ihn extern.
Externe Agenten können die dokumentierten Abläufe über diese API nutzen.
Quelle: docs/API.md im öffentlichen Repo. Für diese Website vor der Veröffentlichung geprüft. Aus dem englischen Original übersetzt. Änderung vorschlagen.