Справка / API и агенты
HTTP API для агентов
Этот сайт описывает отдельные поддерживаемые сценарии и поля, а не весь внутренний API.
Используйте оригинальных или стилизованных персонажей либо свой собственный образ при документально подтверждённом согласии. Для любого изображения другого узнаваемого человека нужно документально подтверждённое согласие этого человека. Для всех референсов, обучающих данных, аудио и результатов соблюдайте Правила допустимого использования.
Внешние агенты (Claude Code, Codex, OSS или всё, что говорит по HTTP) управляют Phosphene через этот API. Чат внутри панели удалён 2026-05-15: встроенного в панель агента больше нет. Всё, что раньше делал чат, внешний агент может сделать через эти эндпоинты.
Готовые инструменты поверх этого API: команда phosphene и MCP-сервер для Claude Code,
Codex или любого MCP-клиента, в agents/. См. Инструменты для агентов.
Сервер
- Базовый URL:
http://127.0.0.1:8198при обычной установке.8199: порт профиля DEV, и все примеры на этой странице используют его, потому что панель, с которой они писались, работала именно на нём. Правило записано одной строкой в исходниках (mlx_ltx_panel.py:275):DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, и его можно переопределить черезLTX_PORT. Если запрос отсюда ничего не возвращает, вы, скорее всего, обращаетесь к порту, на котором нет панели: попробуйте другой. - Процесс:
mlx_ltx_panel.py(в корне репозитория) - Формат обмена: тела
POSTв форме form-encoded; исключения с JSON указаны у каждого эндпоинта. Ответы идут по HTTP/1.0 (это значениеBaseHTTPRequestHandlerпо умолчанию, оно нигде не переопределено), поэтому соединение закрывается после каждого запроса и конвейеризовать запросы через keep-alive нельзя. - Аутентификация: нет, привязка только к loopback.
Соглашения
- Каждый JSON-ответ имеет
Content-Type: application/json. - Ошибки возвращают
{"error": "<message>"}и статус HTTP не из семейства 2xx. - 451
licence_required(4.19.8). Запрос, который скачал бы или запустил модель, лицензия которой требует явного «Я принимаю» (Hailuo H3 по MiniMax H3 Community License и некоммерческие модели Ideogram 4, YuE2, FLUX.1 Krea [dev] и Bria FIBO), получает ответ HTTP 451 с{"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"}, пока эта лицензия один раз не принята на этом Mac. Относится к/queue/add,/queue/retry,/queue/batch,/image/generate,/h3/turbo/install,/h3/tristep/install,/music/install,/music/cover/installи/music/lora/fetch; задание, пришедшее любым другим путём, завершается ошибкой с тем же предложением. Прочитать условия можно черезGET /licences, принять черезPOST /licences/accept(ниже) или один раз в панели, которая сама покажет экран. - Пространство
/agent/*зарезервировано и удалено: любой путь под/agent/, кроме/agent/image/config, возвращает 410 Gone с{"error": "agentic flows removed; see docs/API.md"}. Новые эндпоинты в/agent/добавлять не следует.
Генерация: отправка заданий и управление ими
POST /queue/add: поставить рендер видео в очередь
Добавляет задание в очередь панели. Возвращает ответ сразу; помощник рендерит его асинхронно.
Поля формы (все обязательны, если не указано иное):
| Поле | Тип | Примечание |
|---|---|---|
mode | t2v | i2v | extend | keyframe | a2v | v2a | image | Тип задания. v2a («Добавить звук») есть только у Hailuo H3. |
prompt | string | Полный текст промпта. Слова-триггеры LoRA пишите сюда. |
negative_prompt | string | Необязательно. Учитывается только там, где конвейер использует classifier-free guidance: high, extend, keyframe, a2v. У дистиллированных путей quick / balanced / standard ветки guidance нет, и поле игнорируется (раньше они вклеивали эти термины в промпт, из-за чего модель их рисовала, #81). |
width, height | int | Оба делятся на 32. |
frames | int | Должно выполняться frames % 8 == 1. 121 = 5 с, 169 = 7 с, 241 = 10 с. |
frame_rate | float | По умолчанию 24. LTX обучен на 24 к/с; отклонение ухудшает качество. |
character_strength | float | По умолчанию 1.0. Сила LoRA персонажа, 0-2. |
seed | int или -1 | -1 = случайно. |
quality | quick | balanced | standard | high | Для работы с LoRA персонажа используйте high. balanced молча направляет клипы длиннее 121 кадра на дистиллированный трансформер Q4, где нынешние LoRA теряют сходство. |
stage1_steps, stage2_steps | int | Двухстадийный конвейер HQ. Проверенные значения по умолчанию: 10 / 3. |
teacache_thresh | float | Проверенное плато ускорения: 1.8–2.0. Ниже 1.6 ускорения нет. Чем выше, тем агрессивнее кеширование. |
cfg_scale | float | Classifier-free guidance. Проверенное значение по умолчанию: 3.0. |
bongmath_max_iter | int | Предел внутреннего цикла сэмплера. 100: максимум upstream. |
upscale | off | fit_720p | fit_1080p | Необязательная постобработка. |
upscale_method | lanczos | pipersr | Если upscale != off. |
accel | off | (другие режимы: см. исходники панели) | Параметр ускорения. |
enhance | true | false | Если true, Gemma переписывает промпт перед кодированием. Ставьте false, если в промпте есть слова-триггеры LoRA: переписыватель может их удалить. |
hdr | true | false | Проход HDR ic-lora. |
image | path | Только для I2V. Абсолютный путь к референсу PNG/JPG. Обязательно: начиная с v4.6.1 отсутствие или пустое значение image в i2v / i2v_clean_audio отклоняется при старте задания с понятной ошибкой, а не подменяется на examples/reference.png, демо-файл, которого не было ни в одной установке (эта подмена была самой распространённой ошибкой рендера в парке: image not found: <path>, 35 случаев у 22 человек за 14 дней). LTX_DEFAULT_IMAGE по-прежнему задаёт значение по умолчанию, если указывает на реально существующий файл. |
audio | path | Необязательный аудиореференс. |
label | string | Необязательная подпись для карточки в очереди. |
temporal_mode | native | fps12_interp24 | windows. windows рендерит длину больше одного окна в 121 кадр как ПОСЛЕДОВАТЕЛЬНОСТЬ: один generate, затем по одному extend на каждое следующее окно, отталкиваясь от сохранённого хвоста предыдущего (ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), с обрезкой до запрошенной длины. Нужны дополнение Q8 и уровень, допускающий «Продлить»; иначе отказ с пояснением. Сохраняется в задании как long_mode. | |
window_prompts | JSON-массив (или текст через перевод строки) с одной строкой на окно; пустая строка 1 = сам промпт; пустая строка дальше держит предыдущий момент. Промпт каждого следующего окна состоит из его строки В НАЧАЛЕ, затем фразы-продолжения, затем Throughout: <window_invariants>. (контракт цепочки H3 и правило «начинай с движения»). | |
window_invariants | Что не должно меняться между окнами (кто, где, свет, оптика). Подставляется заново в каждое следующее окно. | |
loras | JSON-массив | См. описание LoRA ниже. |
Hailuo H3 (engine=h3), поля версии 4.19. H3 рендерит t2v, i2v, keyframe, extend, a2v и v2a; каждому режиму после i2v нужен флаг у УСТАНОВЛЕННОГО раннера (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), а задание в режиме, которого у раннера нет, рендерится на LTX с пояснением («Добавить звук» на LTX не поддерживается, и вместо этого приходит отказ с предложением обновиться).
| Поле | Тип | Примечание |
|---|---|---|
h3_quality, h3_length | string | Ячейка. h3_quality=fast_hd = быстрый проход 640×384 + «Апскейл и Исправление лица» до 1280×768, поставленные вместе; быстрый проход и исправление включаются принудительно. |
h3_continuity | on | off | По умолчанию on: следующее окно цепочки получает последние 17 кадров предыдущего и их звук (--chain-context-frames 17). off = передача одним стоп-кадром. |
start_image, end_image, keyframes_json | path / JSON | mode=keyframe. В H3 начальный кадр необязателен (один конечный кадр запускает задачу MiniMax «последний кадр»); моменты из keyframes_json попадают на frame_index на таймлайне 24 к/с. |
video_path, h3_extend_seconds | path / float | mode=extend: любой клип, продолженный от своих последних 17 кадров и их звука; после него добавляется 0.5-15 с. |
audio, image, frames, audio_start_time, audio_stem_auto | mode=a2v при engine=h3: дорожка сохраняется точно, а картинка рендерится под неё; frames (24 к/с) задаёт длину, ограниченную остатком аудио после audio_start_time и 30 с; audio_stem_auto=on опирается на выделенный вокал и отдаёт оригинал. | |
video_path | path | mode=v2a («Добавить звук», только H3): картинка клипа сохраняется точно, генерируется только звук; до 60 с. |
h3_prompt_guards | "" | off | all | список через запятую | Какие защиты промпта работают над текстом, который кодирует раннер (h3_prompt_guards.py): ellipsis, spoken, hands, nouns. Пусто = набор по умолчанию (ellipsis, spoken, hands; nouns включается отдельно); off отправляет промпт как есть. Применённые защиты записываются как h3_prompt_guards_applied; в prompt остаётся набранный текст. |
Описание LoRA: поле loras: JSON-массив объектов {path, strength}. Складывать можно сколько нужно. В Hailuo H3 для этого нужен повторяемый --lora движка (/status.h3.loras.max_stack > 1); старый пакет принимает один адаптер, а поле h3_lora_slot решает, пойдёт ли он в Turbo или в LoRA.
[
{"path": "<panel-root>/mlx_models/loras/explorertrn_v2.safetensors", "strength": 1.0}
]
Результат: {"ok": true, "id": "j-<...>"}, идентификатор задания для опроса.
Пример:
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: псевдоним /queue/add (поведение идентично).
POST /queue/retry
Заново ставит в очередь задание из истории с теми же параметрами. params.open_when_done принудительно становится false (повторы идут в фоне).
| Поле | Тип | Примечание |
|---|---|---|
id | string | Идентификатор исходного задания. |
Возвращает {"ok": true, "id": "<new-id>", "source_id": "<old-id>"}.
POST /queue/remove
Удаляет задание из очереди. (Выполняющееся задание удалить нельзя: используйте /stop.)
| Поле | Тип | Примечание |
|---|---|---|
id | string | Идентификатор задания. |
Возвращает {"ok": true}.
POST /queue/clear
Очищает очередь. Возвращает {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}.
Токен один раз отменяет ИМЕННО эту очистку в течение 60 с (POST /queue/restore с
{"token": "<hex>"} возвращает ровно удалённые задания с прежними идентификаторами
перед всем, что поставлено в очередь после этого). Более поздняя очистка отменяет токен; просроченный или
использованный токен получает ответ 410.
POST /queue/pause, POST /queue/resume
Приостанавливает и возобновляет диспетчер очереди (уже выполняющееся задание не затрагивается).
POST /stop
Просит выполняющееся задание остановиться. Возвращает {"ok": true}. Необязательный ?id=<job id>
(его отправляет панель): остановка только если это задание всё ещё выполняется,
иначе 409 {"stale": true} и ничего не останавливается. /stop/after_part
принимает тот же id.
POST /queue/batch
Отправляет несколько промптов одним пакетом.
| Поле | Тип | Примечание |
|---|---|---|
prompts | string | Промпты через перевод строки. |
(плюс все стандартные поля /queue/add, применяемые к каждой строке) |
Состояние: опрос заданий
One Shot, отдельный вход: POST /oneshot (2026-09-08)
One Shot представляет собой вкладку рабочего процесса и полноценный API. Скрипт отправляет тот же документ, что и вкладка (один JSON-объект), и получает поставленное в очередь задание:
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"}}
| Поле | Тип | По умолчанию | Значение |
|---|---|---|---|
prompt | str | обязательно | Весь кадр один раз: кто, где, время суток и погода, звук. Без моментов он действует на каждые пять секунд. |
seconds | int | 60 | Одно из 30 / 45 / 60 / 90 / 120. Любое другое значение отклоняется, а не округляется (75 раньше рендерилось как один клип). |
engine | ltx / h3 | ltx | LTX рендерит части по 10 с (лица, голоса, диалоги); H3 рендерит части по 15 с (движение, пейзажи). Если H3 не установлен, он отклоняется. |
quality | str | по умолчанию для движка | LTX: quick / balanced / standard / high; с персонажем: draft / pro / high / high_720p; H3: draft / standard / high / native. |
beats | список или текст | нет | Одна строка на пять секунд. Пустая строка удерживает этот момент; лишние строки отбрасываются. Если поля нет, весь промпт и есть каждый момент. |
camera | str | "" | Одно движение на весь кадр, его направление и скорость; переносится в каждую часть (take_camera). |
image | path | нет | Начальный кадр, уже лежащий на этом Mac: сначала загрузите его через POST /upload (поле image) и передайте возвращённый path. Первая часть становится i2v. |
character_id | str | нет | Обученный персонаж (только LTX). По умолчанию качество pro, экспорт 720p Sharp, а handoff равен speech. character_strength необязателен. |
handoff | last / speech | last (speech с персонажем) | Как часть передаёт эстафету: своим последним кадром или кадром с речью, где последнее слово переходит в следующую часть (см. контракт дубля ниже). |
light_lock / retake | on/off | on | Фраза о непрерывности на каждом моменте; один пересъёмный дубль на часть при уходе света. |
seed, label, no_music, turbo (H3), upscale, upscale_method | Как у /queue/add. |
GET /oneshot/options: что умеет этот 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}: планировщик Storyboard пишет по одному моменту на пять секунд из промпта (блокирует на 20-40 с): {ok, beats:[…]}.
GET /oneshot/status: current (id, label, part, parts, lipsync по частям, drift, handoff), queued, recent и собственные строки log дубля.
Внутри каждый One Shot использует контракт дубля, описанный ниже: POST /oneshot отображает документ на форму make_job, поэтому вкладка, API и /queue/add рендерят абсолютно одно и то же задание.
Один дубль: take_seconds + beats в POST /queue/add
Клип длиннее одного прохода, на любом движке. take_seconds: одно из
30 / 45 / 60 / 90 / 120; beats: JSON-список (или текст через перевод строки) с одним
промптом на пять секунд: пустой момент удерживает предыдущий, лишние отбрасываются. Если моментов нет вовсе (поле отсутствует, пусто или состоит из пустых строк), то
prompt и есть каждый момент, то есть кадр представляет собой промпт, поддерживаемый весь дубль. До
4.12.1 в этом случае каждое окно рендерилось как фраза удержания, то есть дубль «ни о чём». Дубль важнее собственного поля длины движка. На ОБОИХ движках он
рендерится ЧАСТЯМИ, связанными передачей последнего кадра: run_take_job_inner запускает один
обычный рендер на часть, каждый начинается с последнего кадра предыдущего
(i2v, с якорем), скрывает части из галереи и склеивает их в
<name>_take<seconds>s.mp4:
| движок | часть | что делает make_job | исполнитель |
|---|---|---|---|
ltx | 10 с = два момента = 241 кадр (дубль на 45 с заканчивается частью из одного момента в 121 кадр) | frames = 241, temporal_mode = native (дубль никогда не идёт цепочкой окон, что бы ни прислала форма) | один обычный рендер LTX на часть через run_job_inner: часть 1 идёт как t2v или i2v по собственному image задания, если оно пришло как i2v; каждая следующая часть идёт как i2v по последнему кадру предыдущей с i2v_reference_mode = anchor. Любое качество; пакет Q8 нужен только для HQ-качества, как и для одиночного клипа |
h3 | 15 с = три момента | h3_length=15s, h3_chain_prompts = моменты первой части | один обычный рендер H3 на часть (--first-frame из предыдущего последнего кадра) |
Два необязательных поля, оба по умолчанию on:
| поле | off означает |
|---|---|
take_light_lock | фраза о непрерывности (take_light_lock(): «it is still night…») НЕ добавляется к моментам; take.light_lock равно "", а пустой момент удерживается одной фразой удержания |
take_retake | часть, у которой свет ушёл дальше TAKE_DRIFT_MAX, остаётся как отрендерена, а не пересобирается один раз с новым сидом; take.retake равно false |
take_camera | необязательный произвольный текст, одно движение на ВЕСЬ кадр («a slow, steady clockwise arc around the table at eye level, wide to close»). take_camera_lock() ставит его первым в промпт части 1 («Camera: …; one steady move at one speed, never stops, never changes direction»), а в каждую следующую часть добавляет фразу, что камера уже движется так и продолжает в том же направлении с той же скоростью: передача закрепляет картинку между частями, но не движение, и шов было видно как камеру, которая меняла направление или останавливалась и трогалась заново на каждом стыке. Если оставить пустым, следующие части всё равно получают общую фразу о непрерывности. Записывается как take.camera |
take_handoff | last (по умолчанию) или speech. При speech раннер режет каждую часть, кроме последней, на ГОВОРЯЩЕМ кадре: take_handoff_points() находит, где кончается реплика (по RMS звука), останавливает картинку за TAKE_TALKING_BACK = 0.2 с до этого (рот ещё посреди слова, и только такой якорь, по замерам, переносит голос на рот следующей части: +0.54 / +0.47 против -0.15…-0.01 на закрытом рту), сохраняет звук до конца реплики плюс 0.4 с затухания и накладывает этот хвост (part{k}_tail.wav, amix normalize=0) на начало следующей части (part{k+1}_lead.mp4), и получается J-склейка, чтобы последнее слово прозвучало целиком. Пишите первый момент каждой части так, чтобы он НАЧИНАЛСЯ В ТИШИНЕ, тогда хвосту хватит места. Тихий хвост после каждой реплики отбрасывается, поэтому дубль получается короче номинальной длины; последняя часть не обрезается. Каждая часть с речью оценивается через take_lipsync_score() и, если оценка ниже TAKE_LIPSYNC_MIN = 0.20, пересобирается до TAKE_LIPSYNC_RETAKES = 2 раз с новыми сидами (идентификаторы -pNl, -pNl2); лучший клип сохраняется, а его оценка записывается в job["take_lipsync"]. Записывается как take.handoff |
params.take у задания: {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}; frames: это
весь дубль (seconds·24+1 на LTX), part_frames: одна полная часть. Файл sidecar результата содержит take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake}, где parts содержит скрытые файлы частей, и
image, только если дубль начался с собственного якоря пользователя. «Загрузить параметры»
восстанавливает дубль как дубль.
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: число частей на обоих движках. Минуты
равны числу частей, умноженному на цену одиночного клипа одной части по той же модели стоимости, что и
в любой другой оценке (H3: измеренная ячейка 15 с; LTX: ячейка качества 10s
из LTX_TIERS, хвост из одного момента по ячейке 5s); null, если у этого
Mac нет числа. needs_q8 теперь всегда false: дубль LTX рендерится на
том же, на чём рендерится выбранное качество.
GET /status
Каждая строка outputs[] содержит q: слова результата для поиска в нижнем регистре, собранные из его sidecar при том же проходе листинга, который его и читает: промпт, подпись, режим, качество, движок, персонаж, сид, WxH, Nf, имена файлов LoRA, имя каталога модели, временной режим и windows. Поле поиска в галерее проверяет подстроку по name + q; должно совпасть каждое набранное слово, а набор текста подтягивает старые работы, так что поиск идёт по всему.
Каждая строка видео содержит и silent: true, если у клипа нет звука (в заголовке mp4 нет аудиодорожки или дорожка нигде не поднимается выше -80 дБ), false, если звук есть, null, пока это неизвестно. Чтение заголовка идёт сразу; проверка уровня выполняется один раз на файл в фоновом потоке и кешируется по (mtime, size) в state/output_silence.json, так что опрос ничего не декодирует. Карточка в галерее и плеер предлагают Добавить звук для клипа с silent, когда /status.h3.video_to_audio равно true.
Возвращает полное состояние панели.
{
"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...", ... ]
}
Смысл полей:
deferred_downloads(4.20):{ active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. Пакеты, которые свежая установка отложила до нажатия Start (state/install_deferred.json, записывает install.js;required_files.json -> install.after_start).stateбываетidle,starting,downloading,waiting(другая загрузка держит слот),waiting_disk(панель держитinstall.background_floor_gbсвободным; вmessageсказано, сколько освободить),retry_wait,failedилиdone. Пусто иidleна любой установке, которой install.js ничего не ставил в очередь: обновлённая установка ничего не скачивает.downloadсодержитbackground: true, пока загрузчик держит слот.current: задание, которое выполняется сейчас (nullв простое).gpu(4.19.10):{ busy, holder, since, outside_queue }, единственный шлюз GPU панели.holderравен"queue"для задания вcurrentили тому, что занимает GPU вне очереди:"image"(рендер в Image Studio),"character_sheet","enhance"(«Улучшить» промпт),"lyrics","update"(скрипт после обновления). Клиент, который не должен прерывать работу (остановка или обновление панели), ждёт, покаcurrentстанетnull, очередь будет на паузе или пуста Иgpu.busyстанетfalse.app_models(только приложение для Mac): собственная загрузка моделей приложения:{ state, packs, active, locked, done_bytes, total_bytes }.locked(4.19.10) истинно, пока приложение держит блокировку загрузки (<Phosphene home>/.locks/models.lock); тогда панель не предлагает Download для этих пакетов и отклоняет его с 409app_downloading. Второйscripts/fetch_pack_release.pyна папке пакета, которую уже пишут, останавливается без изменений с кодом выхода 75.queue: ожидающие задания, порядок FIFO.history: завершённые и неудавшиеся задания. У каждой записи естьstatus,elapsed_sec,output_path,raw_path(нативный результат до апскейла),error.log: скользящий буфер строк stdout помощника (последние ~50 заданий).
Цикл опроса: делайте GET /status каждые 15-30 с. Задание считается завершённым, когда его status равен done, failed, cancelled, stopped или error. До этого он queued или running.
stopped означает, что пользователь остановил рендер намеренно (см. POST /stop?mode=early). Это не сбой: ничего не сохранено, потому что клип так и не был закончен, но и ничего не пошло не так. В stopped_reason лежит собственное предложение раннера.
current.progress
Присутствует, пока задание выполняется.
{
"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 отсутствует, если не включён живой предпросмотр («Настройки» → «Память / скорость») и не установлен крошечный декодер. meaningful вычисляется на сервере, и его нельзя выводить заново на клиенте: правило зависит от конвейера: оценка 6 из 8 на дистиллированном расписании, где первые оценки ещё по сути шум; оценка 2 на двухстадийном пути HQ, который вызывает денойзер дважды за шаг второй стадии. Клиенту, считающему оценки, пришлось бы знать, какое расписание сейчас выполняется.
POST /stop?mode=early
Просит выполняющийся рендер остановиться на ближайшей границе прохода, создавая файл-сигнал ABORT. Раннер завершается с кодом 75, особым значением «пользователь остановил это», а не сбой, и задание получает status: "stopped" без выходного файла. Возвращает 404, если ничего не рендерится, и 409, если у рендера нет живого предпросмотра, через который его можно остановить (используйте жёсткий POST /stop, он убивает помощника).
Замечание о кодировке: буфер журнала может содержать буквальные управляющие символы из промптов со встроенными переводами строк. Удалите их перед разбором JSON:
import re, json
raw = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', ' ', raw)
data = json.loads(raw, strict=False)
LoRA
GET /loras
Возвращает {"user": [...], "curated": [...], "loras_dir": "...", ...}. У каждой записи есть id, name, path, filename, size_bytes, recommended_strength, kind (train_character для LoRA, обученных через панель; иначе null), adapter_verdict (см. ниже) и метаданные CivitAI, если они известны.
adapter_verdict: может ли этот файл вообще что-то делать
LoRA может обучиться до конца, записать корректный safetensors, загрузиться без предупреждения и при этом изменить ничего: выученные дельты численно слишком малы, чтобы сдвинуть модель. Все структурные проверки проходят, потому что каждая из них спрашивает, ПОПАДАЮТ ли ключи, и ни одна не спрашивает, есть ли в них хоть что-то (#61, #62).
adapter_verdict (_adapter_verdict) читается из блока adapter_strength в sidecar и принимает одно из значений:
| Значение | Что означает |
|---|---|
ok | Измерено, RMS дельт в рабочем диапазоне. |
weak | Измерено, дельты не превышают WEAK_DELTA_RMS (2.0e-4). Файл сохраняется; рендер, скорее всего, будет выглядеть так, будто LoRA нет. |
unknown | Обучено сборкой, которая не измеряла. Это не синоним weak: отсутствие данных не означает слабость, и так читается каждая LoRA старше измерения. |
Любое другое значение, названное тренером, передаётся без изменений.
Вызывающим стоит показывать weak до того, как будет потрачен рендер на проверку, и не помечать unknown.
GET /train/list несёт тот же вердикт и adapter_advice: одно предложение о том, что с ним делать, пустое при ok или unknown. Оно учитывает оборудование: на Mac с памятью меньше 64 ГБ оно не говорит «обучите заново на Высоком», потому что такой компьютер не достигнет проверенного рецепта (см. раздел о профиле ниже). Вкладка «Обучить персонажа» в панели показывает его как баннер над плашками обученных персонажей и в строке истории завершённого задания; вердикт, с которым пользователь ничего не может сделать, остаётся измерением, а не ответом (#62).
GET /hf/loras
Hugging Face как источник для просмотра рядом с CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1.
Phosphene не называет ни одной организации: запрос бывает поиском (пустой = поисковый термин по умолчанию для этой линии), списком автора или одним репозиторием;
результаты распределяются по линиям по имени репозитория и тегам, а самый большой .safetensors каждого репозитория вместе с примером клипа превращаются в один элемент в том же формате, который рисует сетка CivitAI
(name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface").
Кешируется на десять минут для каждой линии и запроса.
POST /hf/loras/download
Форма repo, filename, meta (JSON элемента). Скачивает через huggingface_hub (с сохранённым токеном HF, если он есть)
в каталог LoRA нужной линии, запускает проверку раскладки H3 и записывает тот же sidecar, что и установка с CivitAI, плюс
source, hf_repo, hf_url. Возвращает { ok, skipped, name, path, sidecar_path, lane, layout, converted }.
GET /civitai/download/state · POST /civitai/download/cancel (4.18.0)
POST /civitai/download принимает необязательное поле формы token (8-64 символа, A-Z a-z 0-9 _ -), которое выбирает
вызывающая сторона. Пока эта загрузка идёт, GET /civitai/download/state?token=… возвращает
{ ok, state: "running"|"cancelled", bytes, total, name } (404 после её завершения), а
POST /civitai/download/cancel с token останавливает её на ближайшем блоке в 256 КБ: частичный файл удаляется,
ничего не регистрируется, а сам ответ загрузки такой: { ok: false, cancelled: true, error }.
Без токена загрузка идёт как раньше.
GET /loras/updates
Спрашивает у CivitAI, есть ли у какой-либо установленной LoRA с civitai_id в sidecar
более новая версия (modelVersions[0].id ≠ civitai_version_id из sidecar). Один
запрос на такую LoRA; ничего не скачивается.
{ "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": "..." } ] }
Установка обновления выполняется обычным POST /civitai/download с этими
download_url + meta; новый файл ложится рядом со старым, который остаётся
до удаления.
POST /loras/guide
Форма: path (установленная LoRA из GET /loras). Модель-планировщик пишет
руководство из одного абзаца: что делает LoRA, как её промптить, с какой силы начинать,
с чем она конфликтует, на основе имени, описания и слов-триггеров из sidecar, и сохраняет его в sidecar под guide; строки GET /loras после этого содержат
guide. Отклоняется с 409, пока идёт рендер (планировщик, модель на 12B).
Возвращает { ok, guide }.
POST /loras/refresh
Заново сканирует mlx_models/loras/. Возвращает ту же нагрузку, что и /loras.
POST /loras/delete
| Поле | Тип | Примечание |
|---|---|---|
id | string | Идентификатор LoRA из /loras. |
Удаляет файл. Возвращает {"ok": true}.
POST /h3/loras/import
multipart/form-data. Устанавливает один уже имеющийся у вас адаптер Hailuo H3 в собственную
библиотеку LoRA для H3 (mlx_models/hailuo-h3/loras/ или туда, где его хранит установленный пакет).
Намеренно НЕ /upload: референсным материалом может быть любое изображение или аудио, а адаптер H3
должен пройти контракт раскладки раннера, прежде чем появиться в выборе.
| Поле | Тип | Примечание |
|---|---|---|
file | file | Ровно один .safetensors. Имя файла сводится к базовому и очищается; оно не должно совпадать с файлом, уже лежащим в библиотеке. |
Тело передаётся потоком в скрытый промежуточный каталог, а не буферизуется, поэтому адаптер на несколько гигабайт
занимает около 1 МиБ резидентной памяти. Content-Length обязателен и ограничен
H3_LORA_UPLOAD_MAX_BYTES (4 ГиБ).
Что происходит с файлом по порядку: попадает в .import.<pid>.<tid>/<name> →
_h3_lora_prepare (у переупаковки ComfyUI на месте удаляется пространство имён diffusion_model.,
перезапись только заголовка) → проверки полезной нагрузки и целевых модулей, выполняемые только при импорте →
os.replace в библиотеку → sidecar JSON. Отказ на любом шаге ничего не оставляет.
Возвращает:
{
"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 записывается в sidecar и подхватывается регулятором силы каждой LoRA в выборе. Загрузчик H3 применяет B @ A и не использует alpha, поэтому адаптеру, у которого PEFT
alpha/rank ещё не свёрнут в lora_B, нужно это число; оно сообщается,
но никогда не служит основанием для отказа.
Ошибки: 411, если Content-Length отсутствует или равен нулю, 413, если тело превышает предел,
400 для плохого файла (неверное расширение, пустой, дубликат имени, неподходящая раскладка, повреждённая
нагрузка, не та модель), иначе 500. В каждом сообщении указан файл, выбранный пользователем.
Обучение
POST /train/upload
Загрузка multipart/form-data. Добавляет в обучающий набор одно изображение: этот маршрут принимает
по одному файлу на запрос, а не пакет. Отправляйте изображения в цикле, возвращая полученный
train_job_id в каждом вызове после первого, чтобы весь набор оказался в одном каталоге.
| Поле | Тип | Примечание |
|---|---|---|
job_id | string | Необязательно при ПЕРВОМ вызове (будет создан новый идентификатор), далее обязательно, чтобы пакет оставался вместе. Обратите внимание на имя: job_id, а не train_job_id; в ответе оно возвращается как train_job_id. |
file | file | Ровно ОДИН PNG/JPG/JPEG/WEBP/BMP или описание .txt. |
Тело запроса ограничено значением TRAIN_MAX_BYTES_PER_IMAGE (32 МБ). Поскольку предел действует на
весь запрос, а маршрут принимает один файл, тело с несколькими файлами отклоняется, даже если каждое
изображение маленькое.
Возвращает состояние набора (train_job_id, число изображений и т. д.).
POST /train/start
Запускает обучение LoRA персонажа. Панель вызывает lora_lab.train_character и передаёт события прогресса обратно в STATE['log'].
| Поле | Тип | Примечание |
|---|---|---|
train_job_id | string | Из /train/upload. |
trigger | string | Токен-триггер, например explorertrn. Должен быть составным, редким и только из букв, чтобы не пересекаться с обычной речью: цифры токенизируются отдельными очень частыми токенами (mrz07 → m / rz / 0 / 7), а каждый триггер, который здесь удерживал сходство, состоял только из букв; панель предлагает <3 consonants>trn (mrztrn) и записывает в журнал заметку, если в триггере есть цифры (#62). LoRA персонажа ложится в mlx_models/loras/<trigger>_v2.safetensors. |
preset | quick | medium | high | Пресет гиперпараметров. Значение по умолчанию изменено в v4.6.1: если поле опущено, теперь получается high для train_type=character и quick для train_type=style (TRAIN_DEFAULT_PRESET); раньше для обоих было quick, а этот уровень ни разу не удержал сходство (#62). См. таблицу ниже: число шагов не постоянно, а на Mac с памятью меньше 64 ГБ не постоянно вообще ничего. |
image_count | int | Подтверждается панелью по загруженным изображениям. |
Дополнительные переопределения (все необязательны, по умолчанию берутся значения пресета):
| Поле | Тип |
|---|---|
rank, alpha, steps, lr, resolution | int / float |
caption_strategy | class_word | trigger_only | auto_caption |
crop_strategy | center |
Возвращает {"ok": true, "id": "j-<...>"}. Следите за ходом через /status (задание обучения появляется в current, затем в history).
Что на самом деле представляют собой пресеты
Шаги вычисляются, а не заданы жёстко: steps = epochs × image_count, не меньше 1 и не больше max_steps пресета (_preset_steps_for, mlx_ltx_panel.py:1629). Предел входит в контракт сервера: написанный вручную вызов API не должен суметь поставить в очередь запуск на многие тысячи шагов на Mac с ограниченной памятью.
На Mac с 64 ГБ памяти и больше (TRAIN_PRESETS, mlx_ltx_panel.py:1558):
preset | эпохи | ранг | разрешение | max_steps | Проверен на сходство? |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | Нет. На плашке написано «identity ungraded». |
medium | 60 | 16 | 576 | 12000 | Нет. То же. |
high | 100 | 32 | 512 | 20000 | Да: проверенный рецепт v2 (Aria_v2, Bizarro_v2). Он используется по умолчанию, и именно его плашка помечает «Recommended». |
Измерено через lora_compat.py: адаптеры ранга 32, удерживающие сходство, дают delta_rms от 5.4e-04 до 1.6e-03; запуски quick ранга 8 у двух независимых пользователей дали 1.54e-04 и 1.98e-04, и оба не выше порога WEAK_DELTA_RMS, равного 2.0e-04 (#62).
Так что high на 50 изображениях даёт 5000 шагов, на 20 изображениях 2000, на 300 изображениях 20000 (предел). Только рецепт ранга 32 когда-либо показывали человеку и признавали хорошим.
⚠️ Меньше 64 ГБ: каждый пресет молча оказывается другим пресетом
_select_train_profile (mlx_ltx_panel.py:1650) запускается один раз при импорте и, когда общая память равна 0 < ram < 64 ГБ, изменяет TRAIN_PRESETS и TRAIN_STYLE_PRESETS на месте. Имена не меняются. Меняются все числа:
preset | эпохи | ранг | разрешение | max_steps | целевые модули |
|---|---|---|---|---|---|
quick | 2 | 4 | 384 | 120 | компактный набор |
medium | 5 | 8 | 384 | 300 | компактный набор |
high | 10 | 8 | 448 | 500 | компактный набор |
make_job повторяет те же ограничения на стороне сервера, поэтому rank / steps / resolution, переданные как дополнительные переопределения, тоже ограничиваются (max_rank 8, max_resolution 448, max_steps 500): запросить проверенный рецепт на этом оборудовании и получить его нельзя.
Это сознательный компромисс, и причина у него настоящая: полное обучение LoRA для LTX при 512 px материализует обратные активации для dev-трансформера, и Mac на 48 ГБ уходит в подкачку и не заканчивает. Но надо ясно понимать, что это значит: на Mac с памятью меньше 64 ГБ нет пресета, который обучает рецепт, кем-либо проверенный. Ранг 8 при ≤500 шагов как раз тот режим, который должен ловить adapter_verdict, поэтому weak здесь будет встречаться чаще; читайте его как «это оборудование, этот рецепт», а не «этот набор данных».
GET /status отдаёт действующий профиль как train_profile (key: compact_training | full_training, плюс label, ram_gb, max_rank, max_resolution, max_steps, note) и сами действующие таблицы как train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Прочитайте их, прежде чем доверять имени пресета: это значения после изменения, то есть единственное место, где две таблицы выше различаются во время работы.
Событие тренера adapter_strength
Это не событие аналитики: ничего из него не покидает машину (полный список того, что покидает, см. в docs/ANALYTICS.md). Это событие прогресса в потоке подпроцесса lora_lab, которое отправляется один раз, когда тренер измерил только что записанный файл (mlx_ltx_panel.py:18005). Панель записывает в журнал медиану RMS дельты, максимум и число модулей, которые что-то несут, а затем завершает задание в состоянии WARNING, а не простым done, если вердикт не ok. Вердикт записывается в sidecar LoRA как adapter_strength: {"verdict": …} и читается обратно как adapter_verdict в /loras и /characters.
POST /train/install
После успешного обучения LoRA автоматически копируется в mlx_models/loras/. Этот эндпоинт нужен для явной переустановки и обновления метаданных.
POST /train/delete, POST /train/remove-image
Удаляют обучающие наборы и отдельные обучающие изображения.
Персонажи
Находите обученных персонажей LoRA и управляйте ими как пакетами.
GET /characters
Возвращает {"characters": [...]}. Каждая запись описывает одного персонажа, найденного в mlx_models/loras/:
| Поле | Тип | Примечание |
|---|---|---|
id, trigger | string | Одно и то же значение: редкий токен-триггер. |
name, pronoun, subject_noun | string | Из необязательного mlx_models/characters/<trigger>/bundle.json. |
face_lora_path | string | Абсолютный путь к <trigger>_v2.safetensors. Есть всегда. |
sample_image_url | string | null | URL превью-изображения из обучающего набора. |
sheet_image_path, sheet_image_url | string | null | Сгенерированный лист персонажа с несколькими ракурсами (mlx_models/characters/<trigger>/sheet.png), если он есть. Создаётся через POST /characters/<id>/sheet/generate, отдаётся через GET /characters/<id>/sheet. |
Правило обнаружения: <trigger>_v2.safetensors обязателен; всё остальное необязательно.
GET /characters/<id>/preview
Отдаёт пример обучающего изображения персонажа (PNG/JPEG).
GET /characters/<id>/sheet
Отдаёт сгенерированный PNG-лист персонажа. ?w=<px> возвращает кешированную миниатюру (JPEG) через ту же линию изменения размера, что и /image?w=. 404, пока лист не создан.
POST /characters/<id>/sheet/generate
Рендерит лист-разворот с несколькими ракурсами из референсного изображения персонажа (сначала аватар из пакета, запасной вариант: пример из обучения) и собирает его в mlx_models/characters/<id>/sheet.png + sidecar sheet.json (phosphene/character_sheet@1). Синхронно, как /image/generate: вызывающий блокируется на весь рендер; 429, если GPU уже занят рендером, обучением или заданием на изображение (в очередь не ставится).
Content-Type: application/json. Все поля необязательны (пустое тело рендерит лист по умолчанию из 3 ракурсов):
{
"engine_override": "qwen_edit_inline",
"views": ["front", "profile_left", "three_quarter"],
"wardrobe": "a red flight jacket",
"seed": -1
}
Принимаются только движки, учитывающие референс (hidream_*_inline, qwen_edit_*_inline, mock_inline): чисто текстовый движок нарисовал бы незнакомца. seed >= 0 даёт ракурсу i сид seed + i, так что весь лист воспроизводится по одному числу. Промпт каждого ракурса привязывает одежду к референсу («wearing exactly the same clothes as in the reference image»); wardrobe повторяет наряд словами поверх этого. Ракурсы после первого также цепляют первый отрендеренный ракурс вторым референсом: на тусклом референсе одиночные боковые рендеры по-разному воображали цвет волос от сида к сиду и от формулировки к формулировке, а чистый фронтальный ракурс из того же запуска заново фиксирует признаки, которые сырой референс описывает слабо. Кадрирование отдельного ракурса всё же может плыть (объект смещён от центра в одном из ракурсов): пересоздайте его или смените сид. При успехе preview в bundle.json указывает на sheet.png только если раньше был null: вручную выбранное превью никогда не затирается.
POST /characters/<id>/generate
Собирает зафиксированный производственный рецепт и ставит в очередь рендер T2V. Эндпоинт принимает prompt_body, framing, duration, quality и необязательный целочисленный seed (-1 означает случайный, как в /queue/add). Для точного воспроизведения и отладки можно передать full_prompt плюс поля переопределения HQ, такие как stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step и audio_skip_step.
Генерация изображений (отдельно от видео)
POST /image/generate
Генерирует неподвижные изображения через встроенный движок изображений (mflux, BFL, mock-бэкенд). Выбирается отдельно для каждого вызова.
Content-Type: application/json. Нагрузка:
{
"prompt": "...",
"n": 4,
"engine_override": "mflux",
"aspect": "1:1",
"refs": ["/path/to/ref.png"],
"loras": [{"path": "...", "strength": 1.0}]
}
Параметры конкретных бэкендов см. в image_engine.py.
GET /agent/image/config, POST /agent/image/config
Оставлены под устаревшим путём /agent/ ради обратной совместимости с интерфейсом Image Studio. Читают и записывают конфигурацию движка изображений (бэкенд по умолчанию, семейство mflux, ключ BFL и т. д.). Несмотря на путь, это конфигурация движка изображений, а НЕ удалённый чат-агент.
Storyboard: спланировать фильм, затем снять его
Доска означает фильм: замысел, актёры, локации и пронумерованный список кадров. Каждый рендер, который она запускает, проходит через тот же контракт make_job → очередь, что и /queue/add; ни у одного из этих маршрутов нет собственного пути выполнения. Доски лежат в state/storyboards/<board_id>/, а storyboard.json записывается атомарно: рендеры идут часами, и порванная доска погубила бы весь запуск.
Чтение
| Маршрут | Что возвращает |
|---|---|
GET /storyboard/list | Все доски, новые первыми. |
GET /storyboard/get?id=<bid> | Один документ доски. |
GET /storyboard/films | Собранные фильмы на диске: путь для плеера, длительность, размер картинки, размер на диске, когда сделан. list_outputs ищет по маске OUTPUT/*.mp4 и не заходит глубже, поэтому без этого маршрута единственное, что создаёт эта функция, было бы единственным, что приложение не может вам показать. |
Переключатели задания (в plan)
| Поле | Ключ доски | Эффект |
|---|---|---|
auto | auto | после плана: отрендерить каждый кадр, смонтировать, собрать, и больше никаких кнопок |
anchor_stills | anchor_stills | прежде чем рендерится текстовый или персонажный кадр, обычное задание на изображение создаёт его первый кадр (still_job_id → still; лист персонажа служит референсом через qwen_edit_inline, если он есть), и клип рендерится как i2v · anchor от него. Если стоп-кадр не получился, ставится still_error, и кадр один раз рендерится без якоря |
long_windows | long_windows | кадр LTX длиннее 121 кадра рендерится как temporal_mode=windows (цепочка на dev-трансформере Q8) со стилем доски и локацией кадра в качестве window_invariants, а не подрезается. «Продлить» не умеет подставлять изображение в каждое окно, поэтому длинный кадр с якорем закреплён только в первом окне |
take_seconds | take_seconds | один дубль: фильм состоит из одного кадра на 30 / 45 / 60 / 90 / 120 с. Планировщик пишет по одному моменту на 5 с (_sb_take_concept), доска хранит ОДИН кадр с beats (collapse_take), карточка показывает моменты для правки, а shot_to_job отправляет take_seconds + beats, то есть дубль вкладки «Видео», так что рендер одинаков через обе двери. 0 выключает |
Каждое поле меняется, только если оно передано; отсутствующее поле сохраняет значение доски.
POST /storyboard/restill: форма id, n, необязательный pass: забывает стоп-кадр кадра n
и клип, отрендеренный из него, включает anchor_stills, если он был выключен,
и рендерит только этот кадр (сначала стоп-кадр, затем клип из него). Отказы те же,
что у render (идёт планирование, уже рендерится).
Запись: POST /storyboard/<action>
Режиссёр. plan принимает soundtrack (аудиофайл на этом Mac) и bars_per_shot (1/2/4, по умолчанию 2). С дорожкой план превращается в МУЗЫКАЛЬНОЕ ВИДЕО: beat_map() (та же подгонка, что делает «Подготовить» в Редакторе) превращает сильные доли в слоты по bars_per_shot тактов, число кадров равно числу слотов (чипы shots отходят в сторону; предел STORYBOARD_MAX_SHOTS с заметкой), задание планировщика содержит темп, длину слота, указание о дуге и два закона (каждое описание начинать с движения; без диалога: дорожка заменяет звук каждого клипа), а duration_s каждого запланированного кадра равно его слоту плюс запас в одну секунду, с slot: {start, end} на кадре. Частоту решает карта песни. song_map() (storyboard_edit) кладёт РАЗДЕЛЫ на ту же сетку тактов: {start, end, label, energy, brightness} с метками intro / verse / chorus / bridge / outro по положению, относительной громкости и яркости, а director_pacing() превращает bars_per_shot в шаг по каждому разделу: припев режется вдвое чаще, вступление и концовка вдвое реже. Каждый слот несёт свой section; задание сообщает планировщику, какие кадры в каком разделе и насколько он горячий; дорожка, которую карта не может прочитать, режется базовым шагом, и журнал об этом говорит. Доска записывает soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections}, первый автомонтаж Редактора использует эту дорожку, если «Подготовить» не закешировал другую, так что фильм открывается уже смонтированным по биту, а GET /storyboard/edit возвращает sections, чтобы линейка могла нарисовать дугу. Неверный путь даёт 400 до запуска планировщика; пока читается бит, сообщается стадия планировщика grid.
Авто. plan принимает auto=1: когда план готов, сам начинается черновой рендер каждого кадра (_sb_auto_after_plan, как только планировщик вернёт память), а когда поток рендера заканчивает все кадры, фильм монтируется (_sbe_auto_edit, по биту, если есть дорожка) и собирается тем же сборщиком, что использует «Рендер» (_sb_auto_film); доска записывает auto_film. Если какой-то кадр не отрендерился, фильм ждёт, а журнал сообщает, сколько их. «Стоп» по-прежнему останавливает рендер; монтаж и фильм самые обычные, их можно потом перемонтировать.
Form-encoded, если не указано иное. id везде означает идентификатор доски.
| Действие | Поля | Примечание |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | Спланировать или перепланировать. 409, пока рендерер держит память или занят единственный слот планировщика. shots соблюдается или отклоняется, но никогда не подменяется молча другим числом. Повторный план ДОПОЛНЯЕТ локации и гардероб, а не перезаписывает. |
cancel | id | Освободить слот планировщика. |
save | JSON {id, board} | Записать доску, отредактированную вручную. |
grade | id, n, grade, note | Оценить один кадр. |
estimate | id, pass, only | Оценка стоимости и времени до расходов. |
render | id, pass, only, out, music, music_mode | Снять доску. |
stop | id | Остановить идущий рендер доски. |
replan-shots | id, ns | Перебросить названные кадры. Исправление, нарушающее закон, отклоняется; новые варианты вставляются в ТЕКУЩИЙ план, а не в исходный. |
add-shot | id, path | |
import-shots | id, from, only | РЕФЕРЕНСНЫЕ клипы с другой доски. Происхождение (imported_from), исходные ЛОКАЦИИ и исходный СОСТАВ актёров переезжают вместе с ними: если оставить любой из них, сломается что-то конкретное. Отказывает, пока целевой фильм рендерится. |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Показать в Finder (macOS). |
delete | id |
Схема доски: поля географии
Кадр складывается из своей локации. С 2026-08-18 локацию можно также снимать с нескольких направлений, и именно это делает обратный ракурс обратным ракурсом, а не второй локацией.
"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"
…}
]
| Поле | Где | Правила |
|---|---|---|
locations[].views | локация | Список {id, name, light, description}. Отсутствует, а не [], если у локации их нет: у каждой доски, записанной до появления ракурсов, нет этого ключа, а пустой список был бы новой формой, по поводу которой у валидатора появилось бы мнение без всякой пользы. Идентификаторы используют тот же набор символов, что и идентификаторы локаций. |
shots[].view | кадр | Идентификатор ракурса, принадлежащего location_id этого кадра. Ракурс у кадра без локации или ракурс, не принадлежащий его локации, это ошибка проверки (unknown_view), и она падает точно так же, как неизвестная локация: молча отброшенный ракурс составит обратный план из описания установочного, и машина, которую ракурс должен был вывести из кадра, вернётся в него, и об этом никто не скажет. |
shots[].eyeline | кадр | Одно из left, right, lens: факт о КАДРЕ, а не о комнате. right = глаза смотрят за правый край. Любое другое значение даёт ошибку проверки (bad_eyeline). |
Что с ними делает сервер. shot_scene_text подставляет описание РАКУРСА, если кадр его называет, а иначе возвращается к описанию локации: поэтому доска без ракурсов или кадр без названного ракурса рендерится точно так же, как всегда. eyeline_clause во время рендера складывает "his eyes fixed past the right edge of frame"; lens намеренно не даёт ничего (если сказать этим моделям смотреть в объектив, игра станет скованнее, чем при молчании), и он существует, чтобы кадр мог сказать, что держит объектив, благодаря чему проверка правила 180 градусов отличает «смотрит в камеру» от «никто ничего не написал».
Правило 180 градусов соблюдается, а не рекомендуется. После планирования _enforce_eyelines проходит по кадрам в экранном порядке и переворачивает второй из любых двух соседних кадров, которые склеиваются между двумя разными персонажами в одной локации и оба заявляют одну сторону, и сообщает об этом в warnings. Он исправляет механически, потому что eyeline это дискретное поле ровно с одним дополнением: переворот не может повредить ничьей прозе. Законы уровня прозы получают круг через модель именно потому, что у них этого свойства нет.
Редактор: таймлайн
Редактор является рабочим процессом верхнего уровня, а не стадия Storyboard: он не зависит от движка, открывается, когда доска не в середине рендера, а его документ, edit.json в каталоге доски. Одна видеодорожка, одна музыкальная. Звук каждого клипа по умолчанию связан с ним, но его можно отделить (J/L-склейки), и это не вторая аудиодорожка.
Чтение
| Маршрут | Что возвращает |
|---|---|
GET /storyboard/edit?id=<bid> | Раскладка. При первом вызове для доски один раз запускает автомонтаж, сохраняет его на автоматическую дорожку и возвращает с generated: true. Каждый следующий GET просто читает файл. Повреждённый edit.json возвращает 500 с corrupt: true и никогда не заменяется молча: это уничтожило бы раскладку, чьей сломанной копией он является. |
GET /storyboard/edit/status?id=<bid> | Состояние задания подготовки. |
GET /storyboard/edit/peaks?id=<bid> | Форма волны. Сотни КБ: запрашивайте один раз, никогда не в опросе. 404, пока не выполнен prepare. |
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4 | Прокси-видео с поддержкой Range. Safari не станет перематывать <video>, если сервер отвечает простым 200, а это свело бы на нет всю причину существования прокси. name должно соответствовать [A-Za-z0-9._-]{1,120}\.mp4: это базовое имя, созданное сервером, поэтому любое другое имя считается зондированием. |
GET /storyboard/edit/uploads | Видео, которые пользователь принёс с собой (panel_uploads/timeline/, новые первыми, не больше 200). Они намеренно хранятся вне OUTPUT, поэтому им вообще нужен маршрут; изображениям он не нужен, они попадают в библиотеку, которую галерея и так обходит. |
GET /storyboard/edit/sounds?id=<bid> | Источник Sound в медиатеке: {sounds: [{path, name, where, mtime}], dir}: сначала собственная папка audio/ фильма (where: "film"), затем звуковые файлы (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) в корне OUTPUT, новые первыми, не больше 300. Без зондирования; длина читается при добавлении звука. |
GET /storyboard/edit/drafts?id=<bid> | {active, drafts: [...], backup}: см. Черновики ниже. |
GET /storyboard/edit/versions?id=<bid> | Только метаданные: имя, ревизия, когда сохранено, число клипов, длительность и keep (= EDIT_HISTORY_KEEP, 50). Сами документы читаются один раз, командой restore, по слову пользователя. Открытие панели не должно быть загрузкой. |
Запись: POST /storyboard/edit/<sub>
| Sub | Поля | Примечание |
|---|---|---|
prepare | id, music, target_seconds | Построить прокси и пики. 400, если music не файл. |
add-clip | id, from, only, path, title, kind | kind принимает video | still | slug; именно его передача не даёт изображению попасть как видео без кадров. |
add-sound | id, path | Один файл для аудиодорожки: зондируется ({path, title, duration_s, has_video, imported}), 400, если в нём нет звука. Файл вне OUTPUT сначала привязывается жёсткой ссылкой (копируется между томами) в собственную папку audio/ фильма, потому что /file отдаёт только OUTPUT, а звук, который предпросмотр не может проиграть, это ползвука. Полосу размещает и сохраняет клиент. |
relink | id, only | Перенаправить клипы на их готовые (итоговые) файлы. Готовая ПЕРЕСЪЁМКА никогда не входит в этот пакет: она предлагается рядом со своим клипом с retake: true в строках relink нагрузки и принимается по одному клипу через only=<clip id>. |
cancel | id | Отменить задание подготовки. |
auto | id, music, target_seconds, min_shot, max_shot | Заново запустить машинный монтаж. Попадает на автоматическую дорожку. |
save | JSON {id, edit, expect_revision?} | См. ниже. |
draft | id, op, slug, name, from | См. Черновики. |
backup | JSON {id, edit} | Тихая дорожка. См. Черновики. |
recover | id | Принять ожидающую резервную копию. |
discard-backup | id | Выбросить её. |
version | id, label | Назвать версию. Назвать не значит сохранить: ревизия не увеличивается, edit.json не записывается, в таймлайне ничего не меняется, и именно поэтому это безопасно нажимать в любой момент. |
restore | id, file | Восстановить запись истории. Отказывает, пока фильм рендерится. |
render | id, out, music, music_mode, format, size | Собрать фильм. music_mode: replace | under. Сохранить как: format: h264 (по умолчанию, пресет панели) | hevc (VideoToolbox, hvc1, примерно вдвое меньше байт) | prores (422 HQ, 10 бит 4:2:2, звук PCM, .mov, который не покажет ни один браузер); size: native (как смонтировано) | 1080p | 2160p: одно масштабирование Lanczos после наложений, только вверх, никогда не обрезка, пропускается, если монтаж уже такой высоты. finish: none | grain | heavy_grain: движущееся плёночное зерно (noise t+u, сила 9 / 18), добавляемое ПОСЛЕ размера, чтобы 4K-выдача получила 4K-зерно; обработка на стадии выдачи, никогда не попадающая в документ, предпросмотр или экспорт. Другая выдача даёт другой файл: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. Факты содержат deliver: {format, size, finish, label}. |
export-nle | id | FCP7 XML + After Effects JSX + связанные медиа. |
reveal | id, what | Показать в Finder. |
generate | id, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_of | Снять новый клип прямо в слот. С retake_of=<clip id> это пересъёмка: собственный кадр клипа КЛОНИРУЕТСЯ (персонаж, референсы, локация, движок), а меняются только промпт, длина и сид; новый кадр несёт edit_slot.retake_of, и когда он отрендерится, Редактор предложит его для этого клипа («Use it» / «Keep the old one»). 400, если клипа уже нет на таймлайне. |
Семантика save. revision: счётчик сервера, берётся с диска, а не из того, что запомнил клиент: устаревшая вкладка не должна уметь отматывать его назад. Передайте expect_revision, чтобы узнать, что вас опередили, вместо тихой перезаписи другой вкладки: несовпадение возвращает 409 с conflict: true и текущую ревизию. Ошибки проверки приходят все сразу (errors: [...], 400), а файл на диске остаётся нетронутым, так что клиент может подсветить каждый плохой клип за один проход, а не играть в «убей крота».
Схема edit.json
version равно 2 (EDIT_VERSION). Версия 1 обновляется только при ЧТЕНИИ (migrate_edit): повышение версии без обновления на пути чтения не отказало бы старым сборкам, а отказало бы каждому таймлайну, который у кого-то уже есть. Версия из будущего остаётся как есть, чтобы валидатор мог сказать честную вещь.
{
"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[]
| Поле | Примечание |
|---|---|
id, path, proxy | path/proxy равны null у слага. |
start, end | Окно ВНУТРИ источника. |
film_start, film_end | Слот на фильме. Никогда не независимы: клип идёт в 1x, поэтому film_end - film_start == end - start с точностью до LENGTH_TOLERANCE (2 мс). |
kind | video (отсутствие означает video: если проставлять его на 400 клипах, пришлось бы переписать каждый edit.json на машине, чтобы он сказал то, что и так говорит его отсутствие), still (держится на длину своего слота; start/end синтезируются из слота, duration: null), slug (чёрный, без файла). |
source | auto | human. |
locked | bool. |
adjust | {brightness}, аддитивное смещение ffmpeg eq=brightness, ограниченное ±BRIGHTNESS_LIMIT (0.5). Нейтральное значение отсутствует: если вернуть ползунок на ноль, документ остаётся идентичным документу, где ползунка не было. |
frame | {zoom, x, y}: перекадрирование. Картинка увеличивается в zoom раз (1-3), а окно центрируется на доле (x, y) источника. Рендер: crop собственных пикселей источника перед вписыванием, так что одна строка верна при любом размере; предпросмотр: CSS-масштаб вокруг той же точки (приблизительно); экспорт: FCP7 Basic Motion (масштаб + центр) и масштаб + позиция в AE. Нейтральное значение отсутствует; у слага перекадрировать нечего. |
speed | Скорость воспроизведения, SPEED_MIN-SPEED_MAX (0.25-4.0), только видео. Слот равен (end - start) / speed, так что правило 1x выше читается как «на своей скорости». Картинка обрабатывается через setpts, звук через atempo, сцепленный за пределами окна ffmpeg 0.5-2.0, а огибающая звука (afx) остаётся на ВОСПРОИЗВОДИМЫХ часах полосы: ключ на 2 с остаётся на 2 с полосы и после изменения скорости. Отсутствие означает 1x. Никогда не ставится автоматически. |
audio | Разделённая склейка. См. ниже. |
clip.audio: J-склейка и L-склейка
"audio": {"start": 3.5, "end": 7.0, "film_start": 12.25}
Только для видеоклипов. Те же три числа, что у картинки, но для ЗВУКА: звук может начаться раньше своей картинки (J) или пройти дальше неё (L), и именно так стык перестаёт быть стыком встык.
Отсутствие означает «связан», и это вся миграция: ни у одного когда-либо записанного клипа нет ключа audio, и каждый из них играет собственный звук под своей картинкой. EDIT_VERSION из-за этого не менялась, и ни один документ не переписывался.
Переключателем служит НАЛИЧИЕ поля, а не значения в нём. Не выводите «связан» из того, что audio равно окну картинки: отвязывание записывает окно, которое у клипа уже есть, поэтому только что отвязанный клип читался бы как связанный и отказывался перетаскиваться. Переключатель добавляет объект или удаляет его; больше ничто не решает. normalise_edit округляет поле, но никогда не удаляет его по той же причине, и полностью убирает его у стоп-кадра или слага.
Звуковые окна не могут перекрываться друг с другом так же, как картинки. Разделённая склейка означает стык встык, который просто приземляется в другом месте, а не микс; микс делается через audio_tracks.
audio_tracks[]: A3, A4, … под музыкой
"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]]}}]}]
Дорожек может быть сколько угодно, и в каждой сколько угодно полос. start/end: точки входа и выхода внутри файла (полоса идёт в 1x, так что на фильме она длится end - start); film_start: секунда таймлайна, размещаемая через adelay точно так же, как подложка. afx: тот же объект огибающей, который несут звук клипа и подложка, его читает audio_gain_points; gain полосы и gain дорожки (линейно 0-1) умножаются на него: track_strip_gain_points: единая кривая, которую читают предпросмотр, рендер и экспорт. Отсутствие означает «нет», а нейтральное значение отсутствует: в монтаже без дорожек нет ключа, поэтому он загружается, сохраняется и рендерится побайтно идентично; пустая дорожка сохраняется.
Полосы на одной дорожке не могут перекрываться (audio_track_strips_overlap, ошибка, для стыка встык допуск TOUCH_TOLERANCE); полосы на разных дорожках перекрываются и смешиваются. Ошибки формы: 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*.
Рендер: каждая слышимая полоса (не отключена, дорожка не отключена, кривая не молчит) превращается в один -vn -i после наложений, atrim → volume (её кривая на часах полосы) → aresample → adelay (в сэмплах) → apad → atrim до длины фильма, и все они смешиваются через amix (normalize=0, duration=first) поверх звука клипов и подложки под единым лимитером asoftclip; факты фильма несут sound_strips и mix_peak. Полоса, чей файл пропал, отказывает рендеру с указанием пути и дорожки. Экспорт: каждая дорожка становится отдельной аудиодорожкой FCP7 (clipitem с точками входа/выхода, ключами уровня и <enabled>FALSE</enabled> для отключения), а каждая полоса становится слоем After Effects с именем <track> · <title>.
transitions[]: типизированный объект, которому принадлежит СТЫК
"transitions": [{"id": "t1", "after_clip": "<clip id>",
"kind": "dissolve" | "fade_black", "duration": 0.5}]
Перекрёстное растворение означает два клипа в одну и ту же секунду, а правило видеодорожки «один клип за раз» (clips_overlap) несущее, поэтому переход не является перекрытием. Он называет ВЫХОДЯЩИЙ клип и сидит на стыке между ним и следующим за ним в порядке фильма; один на стык. Собственные film_start/film_end клипов не двигаются, и фильм остаётся ровно такой длины, как говорит таймлайн. Рендер берёт половину длительности лишнего хвоста за точкой выхода выходящего клипа и половину лишней головы перед точкой входа входящего клипа (материал источника, оставшийся за обрезками), разрезает конкатенацию картинки на стыке и соединяет два отрезка через xfade (fade / fadeblack) с центром на стыке. Звуку ничего нового не нужно: он идёт по пути дорожек (_sb_split_audio_plan) точно так же, как J-склейка.
duration ограничивается при каждом чтении (transition_duration) значением min(asked, half the shorter neighbour, 2.0 s) и подгоняется до чётного числа кадров; документ хранит набранное число. Сторона без запаса материала отклоняется: transition_no_handles называет сторону и нехватку («clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there»). Каждый код перехода (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) считается ошибкой; ни один не входит в WARNING_CODES. render отказывает тем же предложением. У стоп-кадра и слага есть все запасы, о которых только можно попросить.
overlays[]: карточки, маски и титры
kind: still | video | text. Явный kind главнее; если его нет, решает суффикс пути (.png/.webp/.tif дают стоп-кадры), так что каждое наложение, записанное до появления титров, читается как раньше. Титр является наложением, пиксели которого рисует рендер:
{"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 задан в px для кадра высотой 1080 и масштабируется вместе с фильмом; x/y: якорь в долях кадра; align говорит, какой край текста сидит на x. overlay_text(): единственный accessor, а стиль записывается только там, где он отличается от значений по умолчанию. Шрифт задаётся ФАЙЛОМ: LTX_TITLE_FONT, иначе первый из TITLE_FONT_CANDIDATES, найденный на машине; он проверяется до сборки ffmpeg, а если шрифта нет, render отвечает 400 с пояснением, а не выдаёт фильм с дырой. Растром служит RGBA PNG размером с кадр рядом с фильмом (.titles/), он идёт через ту же цепочку наложений, что и загруженная карточка, так что титр наследует альфу, затухания и порядок слоёв дорожки. Титры рисуются на сцене в DOM с тем же якорем и размером; в экспорт NLE они не попадают (нет пути).
audio: саундтрек как объект на таймлайне
"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
"offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
| Поле | Значение |
|---|---|
offset | Секунда ДОРОЖКИ, которая играет в момент фильма 0. Оно означает это с тех пор, как редактора ещё не было, поэтому каждый документ на диске продолжает работать. Теперь оно может быть отрицательным: дорожка начинается через -offset секунд после начала фильма, а перед ней тишина. |
trim_start / trim_end | Точки входа и выхода ВНУТРИ дорожки, в секундах дорожки. Отсутствие означает «без обрезки», поэтому edit.json, записанный до этого, остаётся корректным: нет поля, нет обрезки, тот же filtergraph. Обрезка на конце дорожки или за ним уже не обрезка, и normalise_edit её отбрасывает: ручка, оттащенная до конца обратно, оставляет побайтно идентичный граф. |
music_window(audio, duration=…): единственное место, где всё это превращается в числа, нужные ffmpeg и каждому экспортёру: start = max(trim_start, offset) (обрезка головы и положительный сдвиг по сути один и тот же жест с двух сторон; побеждает то, что режет больше), end или None для «играть до конца», и delay/film_start = start - offset. Обрезка левого края не сдвигает остальную дорожку раньше: это был бы ripple, а музыка не делает ripple, поэтому секунды, убранные обрезкой головы, возвращаются тишиной в начале. Окно, которое обрезки закрывают целиком, возвращает «нет музыки», а не atrim нулевой длины, от которого ffmpeg отказывается.
Черновики, резервные копии и история: три разные вещи
Черновики представляют собой именованные варианты одного и того же фильма, в drafts/ с index.json, называющим активный. У доски, где есть только edit.json, ровно один черновик, и так было всегда; у него просто не было имени. load_draft_index называет его на выходе, а не в проходе перезаписи, так что обновление не может случиться наполовину.
POST /storyboard/edit/draft реализован как один маршрут с пятью глаголами: это пять правок одного и того же указателя на активный черновик, и если их разделить, указателю будет где ошибиться в пяти местах:
op | Дополнительные поля | Эффект |
|---|---|---|
new | name, from=current | Новый черновик, пустой или скопированный с того, что на экране. Становится активным. |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | Сначала откладывает текущий активный черновик, так что он никогда не теряется. |
new, duplicate, delete и activate возвращают 409 с busy: true, пока этот фильм рендерится: рендер читает этот документ клип за клипом, и подмена таймлайна под ним создаёт ту же опасность, от которой отказываются import-shots и restore.
Резервная копия наша, а сохранение остаётся делом пользователя. POST /storyboard/edit/backup записывает history/backup-<draft>.json и больше ничего: ни edit.json, ни ревизии, ни проверки конфликта. Сохранённый черновик пользователя остаётся ровно таким, каким он сохранил его в последний раз. GET …/drafts показывает копию как backup и предлагает, но никогда не применяет: recover принимает её, discard-backup выбрасывает.
История состоит из двух дорожек и дорожки хранения, различаемые по префиксу имени файла, а не по содержимому: очистка, которой для решения о том, что удалять, нужно прочитать пятьдесят документов, ломается на полпути на первом же повреждённом:
| Префикс | Что это | Очищается? |
|---|---|---|
edit-r* | Автоматический снимок. | Да, ограничено EDIT_HISTORY_KEEP (50). |
save-r* | Сохранение, которое нажал пользователь. | Никогда. |
keep-r* | Версия, которую назвал пользователь (version). | Никогда. |
Каждое сохранение архивирует предшественника до того, как ляжет новый документ (около 5 КБ каждый). Сбой истории никогда не должен блокировать сохранение: потерять крошку хлеба ничто по сравнению с отказом сохранить раскладку, которая на экране. origin также проставляется внутри JSON, для всего, что читает один файл само по себе.
Управление результатами
POST /output/delete
| Поле | Тип | Примечание |
|---|---|---|
path | string | Должен быть внутри mlx_outputs/. |
POST /output/hide, POST /output/show, POST /output/show_all
Скрывают и возвращают работы в галерее без удаления файла.
POST /output/open_folder
Открывает в Finder (Mac) папку, где лежит работа.
Лицензии моделей (4.19.8)
GET /licences
Каждая лицензия, о которой спрашивает панель, с состоянием её принятия на этом Mac:
{"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Ключи: h3, ideogram4, yue2,
flux1_dev, fibo. В записи H3 также есть territory_notice, excluded_territories, report_line,
report_url и credit_line.
POST /licences/accept
Поля формы key=<licence key> и accept=1 (флажок, который отметил пользователь). Записывает принятие для
текущей version лицензии в state/model_licences.json (плюс файл-маркер, который читает установщик H3)
и возвращает {"ok": true, "key": ..., "record": {...}, "licence": {...}}. Изменившаяся версия лицензии
спрашивает снова. Принять от чужого имени значит принять за него: агент должен сначала показать
пользователю условия из GET /licences.
Помощник и система
POST /helper/restart
Перезапускает тёплый подпроцесс помощника (нужно после изменений настроек, которым требуется свежий процесс).
POST /stop_comfy
Завершает процесс ComfyUI, если его запустил Phosphene.
GET /version/check, POST /version/pull
Самообновление из репозитория GitHub. /version/pull выполняет только git pull: он
не запускает scripts/post_update.sh, так что всё, что ставит Update (новые
пакеты, веса), им не устанавливается. Начиная с 4.17.4 панель при следующем запуске сама устанавливает
недостающий разделитель голоса для «Синхронизации губ» (см.
/a2v/separator).
POST /engine/repair
Заново выполняет только шаг окружения движка (scripts/pinokio/ltx_engine_env.sh,
тот же шаг, что и при установке): переустанавливает пакеты Python движка рендера
в его venv в фоне. Без загрузок, без пересборки venv, без Stop.
Отвечает 202 (запущено), 200 {nothing_to_do} (с движком всё в порядке) или 409
(ремонт уже идёт или installing: true: собственная установка Pinokio ещё
пишет venv). Ход и результат идут в GET /status -> engine_env
(ok, fault, installing, repair.{state, active, log, error}).
POST /h3/repair
4.19.5. Заново выполняет только scripts/pinokio/h3_deps.sh на копии Hailuo H3:
переустанавливает пакеты Python для H3 в его собственный venv в том наборе, с которым
тестировался этот релиз (scripts/pinokio/h3_constraints.txt, передаётся через -c; uv
возвращает всё, что вышло за него). Без весов, без Stop: панель никогда не
импортирует venv H3. Отвечает 202 (запущено) или 409 (H3 не установлен, идёт
рендер H3 или ремонт уже идёт). Ход и результат идут в GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Рендер H3 в venv, выбившемся из набора, отклоняется при старте с
H3 cannot start: the Hailuo H3 venv ... и этим ремонтом на карточке.
Push-уведомления: сигнал о завершении для закрытой вкладки
Сигнал во вкладке и уведомление браузера («Настройки» → «Сигналы о завершении») требуют
открытой страницы. Web Push нет: браузер хранит подписку для этого источника, панель
подписывает каждое сообщение парой ключей VAPID, которую один раз создаёт
(state/vapid.json), а push-служба браузера будит /sw.js, чтобы показать
уведомление. Без ретранслятора: панель отправляет прямо вендору браузера. Предлагается
только если импортируется pywebpush (GET /settings → push_available).
| Маршрут | Что |
|---|---|
GET /sw.js | сервис-воркер, отдаваемый из корневой области с Service-Worker-Allowed: / |
GET /push/key | { ok, available, public_key, subscriptions }: публичный ключ VAPID, на который подписывается браузер (503, если недоступно) |
POST /push/subscribe | форма subscription = JSON PushSubscription; одна запись на endpoint |
POST /push/unsubscribe | форма endpoint |
POST /push/test | отправляет “This is what a finished render will say.” каждому подписчику; { ok, sent } |
Каждое задание, завершившееся как done или failed, отправляет Phosphene — render done /
— a render failed с подписью задания (или первыми 60 символами
промпта), вне блокировки GPU и только при включённом notify_done. Подписка,
которую вендор сообщает как исчезнувшую (404 / 410), удаляется.
POST /settings
| Поле | Тип | Примечание |
|---|---|---|
| (любой ключ настройки) | string | Канонический набор см. в state/panel_settings.json. |
notify_done | 1/0 | Сигналы о завершении: звук во вкладке, когда рендер закончился или упал, и уведомление браузера, когда вкладка в фоне и человек их разрешил. По умолчанию включено; GET /settings возвращает значение. |
POST /prompt/enhance
Form-encoded. Предварительно переписывает промпт через Gemma. Используется кнопками «Улучшить» в панели («Видео» и «Синхронизация губ»).
| Поле | Примечание |
|---|---|
prompt | обязательно |
mode | t2v (по умолчанию), i2v или a2v («Синхронизация губ»: помощник промпта i2v плюс закон промпта для синхронизации губ) |
preserve_tokens | JSON-список (или список через запятую) слов, которые результат должен сохранить с точностью до регистра: слова-триггеры |
translate | 0 оставляет промпт не на латинице на его языке; по умолчанию переводится на английский |
loras | 4.18.0: JSON-список путей установленных LoRA в рендере. Панель читает у каждой имя, слова-триггеры и руководство (иначе описание автора) из библиотеки LoRA (пути, которых там нет, игнорируются) и передаёт помощнику не больше 4, ограниченных, как ограждённый справочный текст. Если в результате нет ни одного слова-триггера LoRA, её первый триггер возвращается в начало. |
Возвращает { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] }; { error } с 409, пока рендер держит GPU.
409 needs_pack (4.20). «Улучшить» работает на Gemma 3, которую свежая установка скачивает в фоне после первого запуска (см. deferred_downloads в GET /status). Пока модели нет на диске, маршрут отвечает 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state }, где pack_state принимает одно из downloading, queued, waiting_disk, missing, и никогда не просит помощника её загрузить. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan и /train/auto-caption отвечают тем же по той же причине. POST /models/download repo_key=<needs_pack> скачивает её сразу: пока фоновый загрузчик держит слот загрузки, ответ 202 { queued: true } и пакет выдвигается в начало очереди ({ already: true }, если он и есть скачиваемый).
POST /upload
multipart/form-data. Загружает референсное изображение для режимов I2V и «Ключевые кадры». Возвращает {"path": "<absolute path under panel_uploads/>"}.
Формат sidecar JSON
Каждый завершённый клип записывает sidecar в <output>.mp4.json рядом с MP4. Схема (упрощённо):
{
"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 }
}
Читайте sidecar, чтобы сравнивать запуски, не обращаясь к панели заново.
Производственный рецепт (проверен 2026-05-15)
Для видео с LoRA персонажа проверенный зафиксированный рецепт:
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
Время на M4 Max 64 ГБ: ~7:06 на клип в 7 с при 1024×576, ~3:24 при 736×416.
Рабочий пример: один агент-драйвер
Отправьте клип с двумя LoRA, опрашивайте, пока не завершится, и выведите путь к результату. Только стандартная библиотека.
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')}")
Вот весь шаблон: отправить → опрашивать → прочитать путь к результату.
Что было удалено (и чем заменено)
Встроенная функция агентных потоков (планировщик кадров через чат) была удалена 2026-05-15. Снимок до удаления надёжно хранится на GitHub как тег pre-agent-removal-2026-05-15.
Всё, что делал чат, то есть планирование нескольких кадров, создание кандидатов в якорные изображения, рендер I2V по этим якорям и управление сессиями, внешний агент может сделать через описанный выше API. В частности:
- Планирование кадров: рассуждения на стороне агента, панель не участвует.
- Создание якорей:
POST /image/generate. - От якоря к видео:
POST /queue/addсmode=i2vиimage=<anchor_path>. - Состояние сессии: агент хранит его снаружи.
Внешние агенты могут использовать описанные процессы через этот API.
Источник: docs/API.md в открытом репозитории. Проверено для этого сайта перед публикацией. Переведено с английского оригинала. Предложить правку.