Pro
中文
登录账户 下载 Mac 版
下载 Mac 版

帮助文档 / API 与智能体

面向智能体的 HTTP API

本站只记录部分受支持的工作流程和字段,并非完整的内部 API。

请使用原创或风格化的角色,或经过书面同意的自己的形象。任何涉及其他可识别真人的形象,都需要对方的书面同意。所有参考图、训练数据、音频和输出,都必须遵守使用规范。

外部智能体(Claude Code、Codex、开源工具,或任何会说 HTTP 的程序)通过这套 API 来驱动 Phosphene。面板内置的聊天已在 2026-05-15 移除,面板里不再嵌入任何智能体。聊天过去能做的一切,现在都可以由外部智能体通过这些端点完成。

基于这套 API 的现成工具: phosphene 命令,以及面向 Claude Code、Codex 或任何 MCP 客户端的 MCP 服务器,位于 agents/。见智能体工具。

Server

  • 基础 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 请求体;用 JSON 的例外会在各个端点处注明。响应是 HTTP/1.0(这是 BaseHTTPRequestHandler 的默认值,从未被覆盖),所以每次请求后连接都会关闭,没有 keep-alive 可用于流水线化请求。
  • 认证: 无,只绑定在回环地址上。

Conventions

  • 每个 JSON 响应都带有 Content-Type: application/json。
  • 出错时返回 {"error": "<message>"},并带非 2xx 的 HTTP 状态码。
  • 451 licence_required(4.19.8)。 如果一个请求会下载或运行某个要求明确“我接受”的模型,也就是 Hailuo H3(MiniMax H3 Community License)和非商用模型 Ideogram 4、YuE2、FLUX.1 Krea [dev] 以及 Bria FIBO,在这台 Mac 上接受该许可之前,都会返回 HTTP 451 和 {"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"}。适用于 /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/image/config 外,/agent/ 下的任何路径都会返回 410 Gone 和 {"error": "agentic flows removed; see docs/API.md"}。新的端点不应添加到 /agent/ 下。

生成:提交和管理任务

POST /queue/add:把一次视频渲染加入队列

向面板的队列添加一个任务。立即返回;helper 会异步渲染它。

表单字段(除标注为可选的外,都是必填):

FieldTypeNote
modet2v | i2v | extend | keyframe | a2v | v2a | image任务类型。v2a(添加声音)仅限 Hailuo H3。
promptstring完整的提示词文本。LoRA 的触发词写在这里。
negative_promptstring可选。只有在流水线运行 classifier-free guidance 时才生效:high、extend、keyframe、a2v。经过蒸馏的 quick / balanced / standard 路径没有引导分支,会忽略它(它们过去会把这些词并入提示词,结果模型反而把它们画了出来,#81)。
width, heightint都必须能被 32 整除。
framesint必须满足 frames % 8 == 1。121 = 5 秒,169 = 7 秒,241 = 10 秒。
frame_ratefloat默认 24。LTX 是按 24 fps 训练的,偏离会降低质量。
character_strengthfloat默认 1.0。角色 LoRA 的强度,0-2。
seedint or -1-1 = 随机。
qualityquick | balanced | standard | high做角色 LoRA 时请用 high。 balanced 会悄悄把超过 121 帧的片段路由到 Q4 蒸馏 transformer,而目前的 LoRA 在那里会丢失身份。
stage1_steps, stage2_stepsintHQ 两阶段流水线。经过验证的默认值:10 / 3。
teacache_threshfloat经过验证的提速平台在 1.8–2.0。低于 1.6 没有提速。越高,缓存越激进。
cfg_scalefloatClassifier-free guidance。3.0 是经过验证的默认值。
bongmath_max_iterint采样器内循环上限。100 是上游的最大值。
upscaleoff | fit_720p | fit_1080p可选的后处理。
upscale_methodlanczos | pipersr当 upscale != off 时使用。
acceloff | (其他模式见面板源码)加速开关。
enhancetrue | false为 true 时,Gemma 会在编码前改写提示词。如果提示词包含 LoRA 触发词,请设为 false,因为改写器可能会把它们删掉。
hdrtrue | falseHDR ic-lora 处理。
imagepath仅用于 I2V。参考 PNG/JPG 的绝对路径。必填:自 v4.6.1 起,i2v / i2v_clean_audio 的 image 如果缺省或为空,会在任务开始时被拒绝并给出可读的错误,而不是默认使用 examples/reference.png,那是一个从未随任何安装包发布过的演示文件(这个默认值曾是整个用户群里传播最广的渲染失败:14 天内 22 个人出现 35 次 image not found: <path>)。如果 LTX_DEFAULT_IMAGE 指向一个真实存在的文件,仍然会用它作为默认值。
audiopath可选的音频参考。
labelstring可选,队列卡片上显示的标签。
temporal_modenative | fps12_interp24 | windows。windows 会把超过一个 121 帧窗口的渲染做成一个序列:先一次 generate,之后每个窗口用上一个窗口保留的尾部做一次 extend(ltx_windows.py:stride = window - discard - overlap,count = 1 + ceil((total - window + discard) / stride)),最后裁剪到要求的长度。需要 Q8 附加组件和允许 Extend 的档位,否则会拒绝并给出一句说明。在任务中保存为 long_mode。
window_prompts每个窗口一行的 JSON 数组(或用换行分隔);第 1 行留空 = 使用 prompt;之后的空行表示延续上一个时刻。之后每个窗口的提示词,是它那一行排在最前,然后是延续子句,再然后是 Throughout: <window_invariants>.,这就是 H3 链式合约,以及“把动作放在最前面”的规则。
window_invariants窗口之间不能改变的东西(谁、在哪、光线、镜头)。会重新注入到之后的每个窗口里。
lorasJSON-encoded array见下面的 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 上没有对应通道,所以会直接被拒绝并给出更新提示)。

FieldTypeNote
h3_quality, h3_lengthstring就是那个组合格。h3_quality=fast_hd = 640×384 的 Fast 通道,加上超清放大与人脸修复到 1280×768,一起排队;Fast 和修复都是强制的。
h3_continuityon | off默认 on:链式窗口会带上前一个窗口的最后 17 帧和它们的声音(--chain-context-frames 17)。off = 只用一张静帧交接。
start_image, end_image, keyframes_jsonpath / JSONmode=keyframe。在 H3 上起始帧是可选的(只有结束帧,就是 MiniMax 的尾帧任务);keyframes_json 里的节拍会落在 24 fps 时间线上它们的 frame_index 处。
video_path, h3_extend_secondspath / floatmode=extend:任意片段,从它的最后 17 帧和声音继续;在其后增加 0.5-15 秒。
audio, image, frames, audio_start_time, audio_stem_auto带 engine=h3 的 mode=a2v:音轨被原样保留,画面按它来渲染;frames(24 fps)是长度,上限是 audio_start_time 之后剩余的音频,且不超过 30 秒;audio_stem_auto=on 会以分离出的人声为条件,并交付原始音频。
video_pathpathmode=v2a(添加声音,仅限 H3):片段的画面原样保留,只生成它的声音;最长 60 秒。
h3_prompt_guards"" | off | all | comma list对运行器要编码的文本运行哪些提示词防护(h3_prompt_guards.py):ellipsis、spoken、hands、nouns。为空 = 默认集合(ellipsis、spoken、hands;nouns 需要主动开启);off 原样发送提示词。实际应用的防护会记录为 h3_prompt_guards_applied;prompt 保留输入的原文。

LoRA 载荷: loras 字段是由 {path, strength} 对象组成的 JSON 编码数组。需要几个就叠加几个:在 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-<...>"},也就是用于轮询的任务 ID。

示例:

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(重试在后台进行)。

FieldTypeNote
idstring源任务 ID。

返回 {"ok": true, "id": "<new-id>", "source_id": "<old-id>"}。

POST /queue/remove

移除一个排队中的任务。(正在运行的任务不能移除,请用 /stop。)

FieldTypeNote
idstring任务 ID。

返回 {"ok": true}。

POST /queue/clear

清空队列。返回 {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}。 这个令牌可以在 60 秒内撤销这一次清空(带上 {"token": "<hex>"} 调用 POST /queue/restore,就会把被移除的任务原样放回,原 ID 不变,排在此后新排队的任务之前)。之后再次清空会使它失效;过期或已用过的令牌会返回 410。

POST /queue/pause, POST /queue/resume

暂停或恢复队列调度器(不影响已经在运行的任务)。

POST /stop

请求停止正在运行的任务。返回 {"ok": true}。可选的 ?id=<job id>(面板发送的就是它):只有当那个任务仍是正在运行的任务时才会停止,否则返回 409 {"stale": true},且什么都不会被停止。/stop/after_part 接受同样的 id。

POST /queue/batch

把多个提示词作为一批提交。

FieldTypeNote
promptsstring用换行分隔的提示词。
(plus all the standard /queue/add fields, applied to each row)

状态:轮询任务状态

One Shot:它自己的入口 POST /oneshot(2026-09-08)

一镜到底既是一个工作流标签页,也是一等公民的 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"}}
FieldTypeDefaultMeaning
promptstrrequired整个镜头,只写一次:谁、在哪、一天中的时间和天气、声音。没有 beats 时,它会应用到每五秒。
secondsint6030 / 45 / 60 / 90 / 120 之一。其他值会被拒绝,绝不会取整(75 曾经会被渲染成一个片段)。
engineltx / h3ltxLTX 渲染 10 秒的部分(人脸、声音、对话);H3 渲染 15 秒的部分(动作、风景)。H3 未安装时会被拒绝。
qualitystr引擎默认值LTX:quick / balanced / standard / high;带角色时:draft / pro / high / high_720p;H3:draft / standard / high / native。
beatslist or newline textnone每五秒一行。空行表示延续那个时刻;多余的行会被丢弃。缺省 = 提示词就是每一个 beat。
camerastr""整个镜头的一个运镜动作,包括方向和速度;会带入每个部分(take_camera)。
imagepathnone已经在这台 Mac 上的起始帧:先用 POST /upload(字段 image)上传,再传入返回的 path。这会让第一部分成为 i2v。
character_idstrnone一个训练好的角色(仅限 LTX)。画质默认为 pro,导出默认为 720p Sharp,handoff 默认为 speech。character_strength 可选。
handofflast / speechlast(有角色时为 speech)各部分如何交接:用它的最后一帧,或者用一个说话的帧,并把最后一个词带到下一个部分(见下面的 take 合约)。
light_lock / retakeon/offon每个 beat 上的连续性语句;每个部分一次漂移重拍。
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}:分镜规划器根据提示词,每五秒写一个 beat(会阻塞 20-40 秒):{ok, beats:[…]}。 GET /oneshot/status:current(id、label、part、parts、每个部分的 lipsync、drift、handoff)、queued、recent,以及这次 take 自己的 log 行。

实际上每个一镜到底都是下面的 take 合约:POST /oneshot 把文档映射到 make_job 的表单上,所以标签页、API 和 /queue/add 渲染的是完全相同的任务。

一个 take:POST /queue/add 上的 take_seconds + beats

比单次生成更长的片段,两个引擎都支持。take_seconds 是 30 / 45 / 60 / 90 / 120 之一;beats 是一个 JSON 列表(或换行分隔的文本),每五秒一个提示词:空 beat 表示延续上一个时刻,多余的会被丢弃。完全没有 beats(字段缺省、为空或只有空行)意味着 prompt 就是每一个 beat:这个镜头就是把提示词持续整个 take。在 4.12.1 之前,这种情况会把每个窗口都渲染成延续语句,得到一个什么都没发生的 take。take 的长度优先于引擎自己的长度字段。在两个引擎上,它都会渲染成用最后一帧交接串起来的若干部分:run_take_job_inner 为每个部分运行一次普通渲染,每个部分都从前一个部分的最后一帧开始(i2v,带锚点),把这些部分从作品库中隐藏,并把它们拼接成 <name>_take<seconds>s.mp4:

enginepartwhat make_job doesworker
ltx10 秒 = 两个 beat = 241 帧(45 秒的 take 以一个单 beat 的 121 帧部分结尾)frames = 241,temporal_mode = native(take 永远不是 windows 链,不管表单发了什么)每个部分通过 run_job_inner 做一次普通 LTX 渲染:第 1 部分是 t2v,或者当任务本身以 i2v 进来时,用任务自己的 image 做 i2v;之后每个部分都用前一个部分的最后一帧做 i2v,并设置 i2v_reference_mode = anchor。任意画质;只有 HQ 画质才需要 Q8 包,和单个片段一样
h315 秒 = 三个 beath3_length=15s,h3_chain_prompts = 第一个部分的 beats每个部分做一次普通 H3 渲染(--first-frame 取自前一个部分的最后一帧)

两个可选字段,默认都是 on:

fieldoff means
take_light_lock连续性语句(take_light_lock(),“it is still night…”)不会附加到 beats 上;take.light_lock 是 "",空 beat 只用延续语句
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_handofflast(默认)或 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 剪,这样最后一个词能完整地听到。请把每个部分的第一个 beat 写成在静默中开始,这样尾音才有空间。每句台词之后的静默尾部会被丢弃,所以 take 比它的标称长度要短;最后一个部分不会被裁剪。每个有说话的部分都会由 take_lipsync_score() 打分,如果低于 TAKE_LIPSYNC_MIN = 0.20,最多会用新种子重拍 TAKE_LIPSYNC_RETAKES = 2 次(ID 为 -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 是整个 take(LTX 上是 seconds·24+1),part_frames 是一个完整部分。输出的附属文件里带有 take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake},其中 parts 是被隐藏的各部分文件,只有当 take 以用户自己的锚点开头时才会有 image。载入参数时,take 会被还原成 take。

GET /take/estimate

?engine=h3|ltx&quality=<engine quality key>&seconds=<take_seconds> → { ok, seconds, beats, parts, beats_per_part, part_frames, engine, frames, minutes, eta, needs_q8 }。parts 是两个引擎上的部分数。分钟数等于部分数乘以一个部分的单片段价格,使用与其他所有估算相同的成本模型(H3:实测的 15 秒格;LTX:该画质在 LTX_TIERS 里的 10s 格,单 beat 的尾部使用它的 5s 格);这台 Mac 没有数字时为 null。needs_q8 现在永远是 false:LTX 的 take 用所选画质所用的任何东西来渲染。

GET /status

每个 outputs[] 行都带有 q:这个输出可搜索的词,小写,在已经读取它的列表遍历中由它的附属文件构建而成:提示词、标签、模式、画质、引擎、角色、种子、WxH、Nf、LoRA 文件名主干、模型目录名、时间模式和 windows。作品库的搜索框对 name + q 做子串测试;每个输入的词都必须匹配,输入时会把更早的输出也拉进来,所以搜索覆盖全部内容。

每个视频行还带有 silent:当片段没有声音(mp4 头里没有音轨,或者音轨从未超过 −80 dB)时为 true,有声音时为 false,尚不清楚时为 null。读取头部是内联完成的;电平检查对每个文件在后台线程里只运行一次,并按(mtime、大小)缓存在 state/output_silence.json 里,所以轮询从不会解码任何东西。当 /status.h3.video_to_audio 为 true 时,silent 片段在作品库卡片和播放器上会提供添加声音。

返回完整的面板状态。

{
  "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。在 install.js 从未排过队的安装上,为空且为 idle:更新过的安装不会下载任何东西。当下载器占着名额时,download 带有 background: true。
  • current:正在运行的任务(空闲时为 null)。
  • gpu(4.19.10):{ busy, holder, since, outside_queue },是面板唯一的 GPU 闸门。holder 对 current 里的任务是 "queue",否则是队列之外占用 GPU 的东西:"image"(一次图片工作室渲染)、"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)时为 true;此时面板不会为这些包提供下载,并以 409 app_downloading 拒绝下载请求。对一个正在写入的包文件夹再运行一个 scripts/fetch_pack_release.py,会原样停止,退出码为 75。
  • queue:等待中的任务,先进先出。
  • history:已完成或失败的任务。每一项都有 status、elapsed_sec、output_path、raw_path(放大之前的原始分辨率)、error。
  • log:helper 标准输出行的滚动缓冲(最近约 50 个任务)。

轮询循环: 每 15-30 秒 GET 一次 /status。当任务的 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 是在服务端计算的,不要自己重新推导:规则因流水线而异:在蒸馏调度上是 8 个估算里的第 6 个,因为它最初的几个估算基本还是噪声;在两阶段 HQ 路径上是第 2 个,因为它在阶段 2 的每一步里要对去噪器求值两次。客户端如果自己数估算,就必须知道当前在跑哪种调度。

POST /stop?mode=early

通过创建一个 ABORT 哨兵文件,请求运行中的渲染在下一个前向边界停止。运行器以退出码 75 退出,这个特殊的码表示“用户停止了它”,而不是崩溃,任务的结果为 status: "stopped",没有输出文件。当没有任何渲染在运行时返回 404;当渲染没有实时预览可用来停止时返回 409(请改用硬性的 POST /stop,它会杀掉 helper)。

编码提示: 日志缓冲里可能含有字面的控制字符,来自带嵌入换行的提示词。解析 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(通过面板训练的 LoRA 为 train_character,否则为 null)、adapter_verdict(见下文),以及已知的 CivitAI 元数据。

adapter_verdict:这个文件到底有没有用

一个 LoRA 可以顺利训练完成、写出合法的 safetensors、加载时没有任何警告,却什么都没有改变:它学到的差值在数值上小到推不动模型。所有结构性检查都会通过,因为结构性检查问的都是键能不能对上,没有一个检查里面到底有没有东西(#61、#62)。

adapter_verdict(_adapter_verdict)是从附属文件的 adapter_strength 块里读出来的,取值如下:

ValueMeaning
ok已测量,差值的 RMS 处在有效区间内。
weak已测量,差值等于或低于 WEAK_DELTA_RMS(2.0e-4)。文件会保留;渲染时很可能看起来像没有 LoRA。
unknown由一个没有做测量的版本训练。不等于 weak:没有结果不代表很弱,所有早于这项测量的 LoRA 都是这个读数。

其他任何值,都是训练器给它起的名字,原样透传。

调用方应该在花掉一次渲染去验证之前,就把 weak 提示出来,而不应该给 unknown 加任何装饰。

GET /train/list 带有同样的结论,外加 adapter_advice:一句话,说明该怎么办;当结论是 ok 或 unknown 时为空。它会考虑硬件:在 64 GB 以下的 Mac 上,它不会说“用高重新训练”,因为那台机器达不到经过评测的配方(见下面的配置部分)。面板的训练标签页把它显示成已训练角色标签上方的一条横幅,以及已完成任务的历史行;用户无法据此行动的结论只是一次测量,不是答案(#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 布局探测,并写入与 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), 带 token 的 POST /civitai/download/cancel 会在下一个 256 KB 数据块处停止它:部分下载的文件会被删除,不会登记任何内容,下载本身的响应是 { ok: false, cancelled: true, error }。 不带令牌时,下载的运行方式和以前完全一样。

GET /loras/updates

向 CivitAI 询问:附属文件里带有 civitai_id 的已安装 LoRA,是否有更新的版本(modelVersions[0].id ≠ 附属文件的 civitai_version_id)。每个这样的 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": "..." } ] }

安装更新就是带着那个 download_url + meta 的普通 POST /civitai/download;新文件会放在旧文件旁边,旧文件会一直保留,直到被删除。

POST /loras/guide

表单:path(GET /loras 里一个已安装的 LoRA)。规划模型会根据附属文件自己的名称 / 描述 / 触发词,写一段话的指南:这个 LoRA 做什么、怎么写提示词、从什么强度开始、它和什么冲突,并把它保存在附属文件的 guide 下;之后 GET /loras 的各行就带有 guide。渲染期间会以 409 拒绝(规划器是一个 12B 模型)。返回 { ok, guide }。

POST /loras/refresh

重新扫描 mlx_models/loras/。返回与 /loras 相同的载荷。

POST /loras/delete

FieldTypeNote
idstring/loras 里的 LoRA id。

删除文件。返回 {"ok": true}。

POST /h3/loras/import

multipart/form-data。把你已经有的一个 Hailuo H3 适配器安装到 H3 自己的 LoRA 库里(mlx_models/hailuo-h3/loras/,或者已安装的包存放它的位置)。 刻意不使用 /upload:参考媒体可以是任何图片或音频,而 H3 适配器必须先通过运行器的布局合约,才能出现在选择器里。

FieldTypeNote
filefile恰好一个 .safetensors。文件名会被缩减为基本名并做净化处理;不能与库里已有的文件重名。

请求体会以流式写入一个隐藏的暂存目录,而不是缓冲,所以几个 GB 的适配器也只占约 1 MiB 的常驻内存。必须带 Content-Length,上限为 H3_LORA_UPLOAD_MAX_BYTES(4 GiB)。

文件的处理顺序是:暂存到 .import.<pid>.<tid>/<name> → _h3_lora_prepare(ComfyUI 重新打包的文件会就地去掉它的 diffusion_model. 命名空间,只改写文件头)→ 仅导入时的载荷和目标模块检查 → os.replace 放入库中 → 附属 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 会写入附属文件,并被选择器里每个 LoRA 的强度控件读取。H3 加载器应用的是 B @ A,不带 alpha,所以一个 PEFT 的 alpha/rank 还没有折叠进 lora_B 的适配器,就需要在这里给出这个数字:它只是被报告出来,绝不会作为拒绝的理由。

错误:缺少 Content-Length 或为零时 411,请求体超过上限时 413,文件有问题(扩展名错误、为空、重名、布局不可用、载荷格式错误、模型不对)时 400,其他情况 500。每条消息都会指明用户选的那个文件。


训练

POST /train/upload

multipart/form-data 上传。向训练数据集添加一张图片:这个路由一次请求一个文件,不是批量。请循环发送图片,并在第一次之后的每次调用里回传返回的 train_job_id,这样整个数据集才会落在同一个目录里。

FieldTypeNote
job_idstring第一次调用时可选(会生成一个新的 id),之后必填,用来把这一批放在一起。注意名称:是 job_id,不是 train_job_id,响应里把它返回为 train_job_id。
filefile恰好一个 PNG/JPG/JPEG/WEBP/BMP,或一个 .txt 描述文件。

请求体的上限是 TRAIN_MAX_BYTES_PER_IMAGE(32 MB)。因为这个上限针对整个请求,而路由只接受一个文件,所以即使每张图片都很小,包含多个文件的请求体也会被拒绝。

返回数据集状态(train_job_id、图片数量等)。

POST /train/start

启动一次角色 LoRA 训练。面板会调用 lora_lab.train_character,并把进度事件以流的方式写回 STATE['log']。

FieldTypeNote
train_job_idstring来自 /train/upload。
triggerstring触发词,例如 explorertrn。必须是复合的、罕见的,并且只含字母,这样才不会和普通语言冲突:数字会被分词成单个、非常常见的词元(mrz07 → m / rz / 0 / 7),而在这里真正承载了身份的触发词,全都是只含字母的;面板建议 <3 consonants>trn(mrztrn),并在触发词带数字时在日志里记一条提示(#62)。角色 LoRA 会放在 mlx_models/loras/<trigger>_v2.safetensors。
presetquick | medium | high超参数预设。v4.6.1 起默认值有变化:省略它时,train_type=character 得到 high,train_type=style 得到 quick(TRAIN_DEFAULT_PRESET),以前两者都得到 quick,而那一档从未承载过身份(#62)。见下表,步数不是常量,在 64 GB 以下的 Mac 上,其他任何东西也都不是。
image_countint由面板根据上传的图片确认。

高级覆盖项(都是可选的,缺省时使用预设的默认值):

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

返回 {"ok": true, "id": "j-<...>"}。通过 /status 跟踪进度(训练任务先出现在 current,然后进入 history)。

预设实际是什么

步数是推导出来的,不是固定的:steps = epochs × image_count,下限为 1,上限为预设的 max_steps(_preset_steps_for,mlx_ltx_panel.py:1629)。这个上限是服务端合约的一部分:手写的 API 调用不能在内存受限的 Mac 上排入一个几千步的训练。

在 64 GB 或更多内存的 Mac 上(TRAIN_PRESETS,mlx_ltx_panel.py:1558):

presetepochsrankresolutionmax_steps是否评测过身份?
quick3085128000没有。 标签上写着“身份未评测”。
medium601657612000没有。 同上。
high1003251220000有。 经过验证的 v2 配方(Aria_v2、Bizarro_v2)。这是默认值,也是标签上标注“推荐”的那一个。

用 lora_compat.py 测量:承载身份的 rank-32 适配器,delta_rms 处在 5.4e-04 到 1.6e-03;两位独立用户的 rank-8 quick 训练分别测得 1.54e-04 和 1.98e-04,都等于或低于 WEAK_DELTA_RMS 的下限 2.0e-04(#62)。

所以 high 用 50 张图片是 5000 步,20 张是 2000 步,300 张是 20000 步(达到上限)。只有 rank-32 的配方,曾经摆在真人眼前并被评价为好。

⚠️ 在 64 GB 以下,每个预设其实都悄悄变成了另一个预设

_select_train_profile(mlx_ltx_panel.py:1650)在导入时运行一次,当总内存满足 0 < ram < 64 GB 时,它会就地修改 TRAIN_PRESETS 和 TRAIN_STYLE_PRESETS。名称不变,数字全变:

presetepochsrankresolutionmax_stepstarget modules
quick24384120compact set
medium58384300compact set
high108448500compact set

make_job 在服务端镜像了同样的限制,所以作为高级覆盖项传入的 rank / steps / resolution 也会被限制住(max_rank 8、max_resolution 448、max_steps 500),你无法在这种硬件上要求经过评测的配方并真的得到它。

这是一个有意的取舍,而且理由很实在:完整的 512 px LTX LoRA 训练要为 dev transformer 物化反向传播的激活值,48 GB 的 Mac 会陷入交换抖动,永远跑不完。但请明确它意味着什么:在 64 GB 以下的 Mac 上,没有任何一个预设能训练出有人评测过的配方。 在 ≤500 步下用 rank 8,正是 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 的中位数、最大值,以及有多少个模块在起作用,然后在结论不是 ok 时,让任务以警告状态结束,而不是单纯的 done。结论会写入 LoRA 的附属文件,形如 adapter_strength: {"verdict": …},并在 /loras 和 /characters 上作为 adapter_verdict 读回。

POST /train/install

训练成功后,LoRA 会自动复制到 mlx_models/loras/。这个端点用于显式地重新安装或刷新元数据。

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

删除训练数据集或单张训练图片。


角色

把训练好的角色 LoRA 作为打包好的整体来发现和驱动。

GET /characters

返回 {"characters": [...]}。每一项描述在 mlx_models/loras/ 里发现的一个角色:

FieldTypeNote
id, triggerstring同一个值,即罕见的触发词。
name, pronoun, subject_nounstring来自可选的 mlx_models/characters/<trigger>/bundle.json。
face_lora_pathstring<trigger>_v2.safetensors 的绝对路径。始终存在。
sample_image_urlstring | null指向训练数据集中一张预览图的 URL。
sheet_image_path, sheet_image_urlstring | 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> 通过与 /image?w= 相同的缩放通道返回缓存的缩略图(JPEG)。在生成设定图之前为 404。

POST /characters/<id>/sheet/generate

根据角色的参考图(优先用角色包里的头像,其次用训练样本)渲染一张多视角转面设定图,并把它合成到 mlx_models/characters/<id>/sheet.png,外加一个 sheet.json 附属文件(phosphene/character_sheet@1)。与 /image/generate 一样是同步的:调用方会在整个渲染期间被阻塞;当 GPU 已被渲染、训练或图片任务占用时返回 429(绝不排队)。

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 会在此基础上再用文字重述这套服装。第一个之后的视图,还会把渲染出的第一个视图作为第二张参考图串联进来:在一张偏暗的参考图上实测,单独渲染的侧面视图会在不同种子和措辞之间重新想象发色,而同一次运行里干净的正面图,会把原始参考图描述不足的属性重新锚定下来。每个视图的构图仍然可能漂移(主体在某个视图里偏离中心),可以重新生成或换种子。成功之后,只有当 bundle.json 的 preview 为 null 时,才会把它指向 sheet.png,人工挑选的预览绝不会被覆盖。

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/ 路径下。用来读写图像引擎配置(默认后端、mflux 系列、BFL 密钥等)。尽管路径如此,这是图像引擎的配置,不是被移除的聊天智能体。


分镜:规划一部影片,然后拍摄

一个画板就是一部影片:一个构思、一组演员、若干场景,以及一份带编号的镜头清单。它发起的每一次渲染,都走与 /queue/add 相同的 make_job → 队列合约;这些路由里没有任何一个有私有的执行路径。画板放在 state/storyboards/<board_id>/ 下,storyboard.json 以原子方式写入:渲染一跑就是几个小时,一块写坏的画板会让整次运行白费。

读取

RouteReturns
GET /storyboard/list所有画板,最新的在前。
GET /storyboard/get?id=<bid>一份画板文档。
GET /storyboard/films磁盘上已组装好的影片:播放路径、时长、画面尺寸、占用空间、制作时间。list_outputs 只对 OUTPUT/*.mp4 做 glob,从不深入子目录,所以没有这个路由,这个功能产出的唯一成果,反而是应用看不到的那一个。

画板简报开关(用于 plan)

FieldBoard keyEffect
autoauto规划完成后:渲染每一个镜头、剪辑、组装,不再需要任何按钮
anchor_stillsanchor_stills在文字或角色镜头渲染之前,先由一个普通的图片任务生成它的第一帧(still_job_id → still;存在角色设定图时,会通过 qwen_edit_inline 把它作为参考),然后片段以 i2v · anchor 的方式从这张图开始渲染。如果某张静帧失败,会设置 still_error,该镜头改为不带锚点地渲染一次
long_windowslong_windows超过 121 帧的 LTX 镜头会渲染为 temporal_mode=windows(在 Q8 dev transformer 上的链式渲染),把画板的风格和镜头的场景作为 window_invariants,而不是被裁剪到刚好合适。Extend 无法在每个窗口重新注入图片,所以带锚点的长镜头只有它的第一个窗口被锚定
take_secondstake_seconds一个 take:整部影片是一个 30 / 45 / 60 / 90 / 120 秒的镜头。规划器每 5 秒写一个 beat(_sb_take_concept),画板只保留带 beats 的一个镜头(collapse_take),卡片会显示这些 beats 供编辑,shot_to_job 提交 take_seconds + beats,也就是视频标签页的 take,所以从两个入口渲染出来的结果相同。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 的部分会被截断并附一条说明),规划器的简报里带有 bpm、槽位长度、一条弧线指示和两条规则(每段描述都以动作开头;不要对白,音轨取代每个片段的声音),每个已规划镜头的 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。有镜头没有渲染出来时,影片会等待,日志会说明差了多少个。停止仍然会停止渲染;剪辑和影片都是普通的,之后可以重新剪。

除非另有注明,都是表单编码。id 在所有地方都指画板 id。

ActionFieldsNote
planconcept, id, notes, shots, must, engine, character_id, style, locations, wardrobe规划或重新规划。渲染器占用内存、或唯一的规划器名额被占用时返回 409。 shots 要么被遵守,要么被拒绝,绝不会被悄悄换成另一个数量。重新规划会修补(PATCH)场景和服装,而不是覆盖它们。
cancelid释放规划器名额。
saveJSON {id, board}写入手动编辑过的画板。
gradeid, n, grade, note给一个镜头打分。
estimateid, pass, only花费之前的成本 / 耗时估算。
renderid, pass, only, out, music, music_mode拍摄这块画板。
stopid停止正在运行的画板渲染。
replan-shotsid, ns重新生成指定的镜头。违反规则的修复会被拒绝;重新生成的内容会拼接到当前的规划里,而不是最初的规划。
add-shotid, path
import-shotsid, from, only来自另一块画板的参考片段。来源信息(imported_from)、来源场景和来源演员都会跟着一起过来,漏掉任何一项都会在某个具体的地方出问题。目标影片正在渲染时会拒绝。
exportid, auto_edit, music, target_seconds, music_mode
revealid, name, what在访达中显示(macOS)。
deleteid

画板结构:地理相关字段

一个镜头由它的场景构成。自 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"
   …}
]
FieldWhereRules
locations[].viewslocation由 {id, name, light, description} 组成的列表。当场景没有视角时,是缺省,而不是 []:视角出现之前写出的每一块画板都没有这个键,而一个空列表对验证器来说是一种新形态,白白让它多出意见。id 使用与场景 id 相同的字符集。
shots[].viewshot属于该镜头 location_id 的一个视角 id。没有场景的镜头上带了视角,或者视角不属于那个场景,就是一个验证错误(unknown_view),失败的方式与未知场景完全相同:悄悄被丢掉的视角,会用 establishing 视角的描述来构成反打镜头,视角本来要排除出画面的那辆车就又回到画面里,而且没有任何提示。
shots[].eyelineshotleft、right、lens 之一,这是关于画面(FRAME)的事实,不是关于房间的。right = 视线投向画面右边缘之外。其他任何值都是验证错误(bad_eyeline)。

服务器如何处理它们。 当镜头指定了视角时,shot_scene_text 会注入该视角的描述,否则回退到场景的描述,所以没有视角的画板,或没有指定视角的镜头,渲染起来和以前完全一样。eyeline_clause 在渲染时组成 "his eyes fixed past the right edge of frame";lens 有意不产生任何内容(让这些模型直视镜头,得到的表演比什么都不说更僵硬),它存在的意义,是让一个镜头可以声明自己直视镜头,这样 180 度检查才能分清“面向镜头”和“没人写过”。

180 度规则是强制执行的,不是建议。 规划之后,_enforce_eyelines 按画面顺序遍历镜头,只要相邻两个镜头在同一个场景里、在两个不同的角色之间切换,并且都声称同一侧,就翻转其中的第二个,并在 warnings 里说明。它用机械方式修复,因为 eyeline 是只有一个互补值的离散字段,翻转它不会损坏任何人的文字。文字层面的规则则要走一次模型往返,恰恰因为它们没有这个性质。


编辑器:时间线

编辑器是一个顶层工作流,不是分镜的一个阶段:与引擎无关,不需要画板正在渲染就能打开,它的文档是画板目录下的 edit.json。一条视频轨道,一条音乐通道。每个片段的声音默认是关联的,也可以拆开(J/L 剪),这不是第二条音轨。

读取

RouteReturns
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>波形。有几百 KB:只取一次,绝不要放在轮询里。在 prepare 运行之前为 404。
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4一个代理视频,支持 range 提供。Safari 不会对只返回普通 200 的服务器上的 <video> 做拖动定位,那会让代理存在的全部理由落空。name 必须匹配 [A-Za-z0-9._-]{1,120}\.mp4:它是服务器生成的基本名,其他任何形式都是探测。
GET /storyboard/edit/uploads用户自己带来的视频(panel_uploads/timeline/,最新的在前,上限 200 个)。有意放在 OUTPUT 之外,所以才需要一个路由;图片则不需要,它们会进入作品库已经遍历的那个库。
GET /storyboard/edit/sounds?id=<bid>媒体池里的声音来源:{sounds: [{path, name, where, mtime}], dir}:先是影片自己的 audio/ 文件夹(where: "film"),再是 OUTPUT 顶层的声音文件(.wav .m4a .mp3 .aac .flac .aif .ogg .opus),最新的在前,上限 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>

SubFieldsNote
prepareid, music, target_seconds构建代理和波形峰值。如果 music 不是文件则返回 400。
add-clipid, from, only, path, title, kindkind 是 video | still | slug:传入它,才能避免一张图片被当成没有任何帧的视频。
add-soundid, path为一条音轨添加一个文件:会做探测({path, title, duration_s, has_video, imported}),如果不含声音则返回 400。OUTPUT 之外的文件,会先硬链接(跨卷则复制)到影片自己的 audio/ 文件夹,因为 /file 只服务 OUTPUT,而预览无法播放的声音只算半个声音。声音条由客户端放置和保存。
relinkid, only把片段重新指向它们已完成(交付)的文件。已完成的重拍绝不属于这一批:它会以 retake: true 出现在载荷的 relink 行里,针对它自己的片段提出,并通过 only=<clip id> 逐个采用。
cancelid取消准备任务。
autoid, music, target_seconds, min_shot, max_shot重新运行机器的剪辑。结果落在自动通道。
saveJSON {id, edit, expect_revision?}见下文。
draftid, op, slug, name, from见草稿。
backupJSON {id, edit}静默通道。见草稿。
recoverid采用待处理的备份。
discard-backupid丢弃它。
versionid, label给一个版本命名。命名不是保存:不增加修订号,不写入 edit.json,时间线上没有任何变化,这正是它可以在任何时刻放心按下的原因。
restoreid, file恢复一条历史记录。影片正在渲染时会拒绝。
renderid, 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-nleidFCP7 XML + After Effects JSX + 链接的媒体。
revealid, what在访达中显示。
generateid, 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[]

FieldNote
id, path, proxy在 slug 上,path/proxy 为 null。
start, end源文件内部的窗口。
film_start, film_end片段在影片上的槽位。绝不独立:片段以 1 倍速播放,所以在 LENGTH_TOLERANCE(2 毫秒)范围内,film_end - film_start == end - start。
kindvideo(缺省表示视频:给 400 个片段都打上它,会让这台机器上的每个 edit.json 都被改写,去写它的缺省本来就已经说明的事),still(在其槽位的长度内保持不变;start/end 由槽位合成,duration: null),slug(黑场,没有文件)。
sourceauto | human。
lockedbool。
adjust{brightness},一个 ffmpeg eq=brightness 的加性偏移,限制在 ±BRIGHTNESS_LIMIT(0.5)。中性值就是缺省:把滑块拖回零,得到的文档与从未有过滑块的文档完全一致。
frame{zoom, x, y}:重新取景。画面被放大 zoom 倍(1-3),窗口以源画面的 (x, y) 比例位置为中心。渲染:在适配之前,对源文件自己的像素做一次 crop,所以一个字符串对每种尺寸都正确;预览:围绕同一个锚点的 CSS 缩放(近似);导出:FCP7 的 Basic Motion(缩放 + 中心)和 AE 的缩放 + 位置。中性值就是缺省;slug 没有可重新取景的东西。
speed播放速率,SPEED_MIN-SPEED_MAX(0.25-4.0),仅限视频。槽位是 (end - start) / speed,所以上面的 1 倍速规则读作“按它的速度”。画面用 setpts,声音用 atempo,并串联超出 ffmpeg 0.5-2.0 范围的部分,声音的包络(afx)保持在声音条的播放时钟上,所以 2 秒处的关键帧,在变速之后仍然在声音条的 2 秒处。缺省是 1 倍速。 从不自动设置。
audio拆分剪辑。见下文。

clip.audio:J 剪和 L 剪

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

只用于视频片段。给声音的三个数字,与画面的那三个一样,所以声音可以比画面先开始(J),也可以延续到画面之后(L),这就是剪辑不再是生硬对接的原因。

缺省表示关联,这就是全部的迁移工作:写出的每个片段都没有 audio 键,它们每一个都在自己的画面下播放自己的声音。EDIT_VERSION 没有因此提升,也没有任何文档被改写。

开关是这个字段是否存在,而不是其中的值。 不要通过 audio 是否等于画面窗口来推断“关联”:取消关联写入的正是片段已有的那个窗口,所以刚被用户取消关联的片段,会被读成仍然关联,并拒绝被拖动。切换时添加这个对象或删除它;没有别的东西来决定。normalise_edit 会对该字段取整,但出于同样的原因绝不会移除它,并且会把它从静帧或 slug 上彻底去掉。

声音窗口之间不能互相重叠,就像画面一样。拆分剪辑是落在别处的生硬对接,而不是混合,混合是 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 是文件内部的入点和出点(声音条以 1 倍速播放,所以它在影片上长 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>),每个声音条是一个名为 <track> · <title> 的 After Effects 图层。

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 会以同样的句子拒绝。静帧和 slug 拥有任何人能要的全部余量。

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 是 1080 高画面下的像素,并随影片缩放;x/y 是锚点,以画面的比例表示;align 说明文字的哪条边落在 x 上。overlay_text() 是唯一的读取入口,样式只在与默认值不同时才写入。字体是一个文件:LTX_TITLE_FONT,否则是这台机器上存在的 TITLE_FONT_CANDIDATES 里的第一个,在构建 ffmpeg 之前就会验证;如果一个都没有,render 会返回 400 和一句话,而不是产出一部有窟窿的影片。栅格是影片旁边(.titles/)一张与画面同尺寸的 RGBA PNG,经过与上传的卡片相同的叠加链,所以标题继承该通道的 alpha、淡入淡出和层叠顺序。标题在舞台的 DOM 里以相同的锚点和大小绘制;它们不会进入 NLE 导出(没有路径)。

audio:配乐,作为时间线上的一个对象

"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
          "offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
FieldMeaning
offset在影片时间 0 处播放的那一秒,以音轨的时间计。在编辑器出现之前它就是这个含义,所以磁盘上的每个文档都仍然有效。现在它可以为负:音轨从影片中第 -offset 秒处开始,前面是静音。
trim_start / trim_end音轨内部的入点 / 出点,以音轨的秒数计。缺省表示没有修剪,所以在此之前写出的 edit.json 仍然有效:没有字段,就没有修剪,滤镜图也一样。位于或超过音轨结尾的修剪不算修剪,normalise_edit 会把它丢掉:把手柄一路拖回去,得到的图逐字节相同。

music_window(audio, duration=…) 是把这些变成 ffmpeg 和每个导出器所需数字的唯一地方:start = max(trim_start, offset)(头部修剪和正的偏移,是从两个方向做的同一个手势,取切得更多的那个),end 或 None 表示“播放到结尾”,delay/film_start = start - offset。修剪左边缘不会让音轨其余部分提前滑动,那是波纹编辑,而音乐不做波纹,所以头部修剪去掉的那些秒数,会作为前面的静音回来。被修剪完全关闭的窗口,会返回“没有音乐”,而不是 ffmpeg 会拒绝的零长度 atrim。

草稿、备份和历史:三件不同的事

草稿是同一部影片的命名变体,放在 drafts/ 里,由一个 index.json 指明当前的那个。只有 edit.json 的画板,恰好有一个草稿,而且一直如此,只是它没有名字。load_draft_index 是在读出时给它命名,而不是在一次改写过程中,所以升级不会只完成一半。

POST /storyboard/edit/draft 是一个带五个动词的路由:这是对同一个当前指针的五种编辑,拆开会让这个指针有五个出错的地方:

opExtra fieldsEffect
newname, from=current新建草稿,空的,或从屏幕上的内容复制。成为当前草稿。
duplicateslug, name
renameslug, name
deleteslug
activateslug先把当前草稿存起来,绝不丢失它。

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 丢弃它。

历史是两条通道加一条保留通道,靠文件名前缀区分,而不是打开文件:为了决定删什么而要读五十份文档的清理,会在第一份损坏的文档上半途失败:

PrefixWhatPruned?
edit-r*自动快照。会,上限为 EDIT_HISTORY_KEEP(50)。
save-r*用户按下保存的一次保存。从不。
keep-r*用户命名的版本(version)。从不。

每次保存,都会在新文档落地之前归档它的前一份(每份约 5 KB)。历史记录失败绝不能阻止保存,丢掉一个面包屑,与拒绝保存屏幕上的编排相比,算不了什么。origin 也会写进 JSON 内部,供任何单独读取一个文件的东西使用。


输出管理

POST /output/delete

FieldTypeNote
pathstring必须位于 mlx_outputs/ 下。

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

在作品库里隐藏或重新显示输出,而不删除文件。

POST /output/open_folder

在访达中打开该输出所在的文件夹(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 里的条款展示给用户看。

Helper / system

POST /helper/restart

重启常驻的 helper 子进程(在需要全新进程的设置变更之后使用)。

POST /stop_comfy

如果 Phosphene 启动过 ComfyUI 进程,就把它关掉。

GET /version/check, POST /version/pull

对照 GitHub 仓库自我更新。/version/pull 只是一次 git pull:它不会运行 scripts/post_update.sh,所以更新会安装的任何东西(新的软件包、权重)它都不会安装。自 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 自己的 Install 仍在写 venv)。进度和结果通过 GET /status -> engine_env 提供(ok、fault、installing、repair.{state, active, log, error})。

POST /h3/repair

4.19.5。只重新运行 Hailuo H3 检出目录上的 scripts/pinokio/h3_deps.sh:把 H3 的 Python 包重新安装到它自己的 venv 里,版本固定为本版本测试时用的那一组(scripts/pinokio/h3_constraints.txt,用 -c 传入;uv 会把已经在这组之外的东西移回来)。不下载权重,不需要 Stop,面板从不导入 H3 的 venv。返回 202(已开始)或 409(H3 未安装、H3 渲染正在运行,或修复已在运行)。进度和结果通过 GET /status -> h3_env 提供(ok、fault、repair.{state, active, log, error})。在不属于这一组的 venv 上做 H3 渲染,会在开始时被拒绝,并显示 H3 cannot start: the Hailuo H3 venv ...,同时卡片上带有这个修复。

推送提醒:标签页关闭后的完成提醒

标签页里的提示音和浏览器提醒(设置 → 完成提醒)需要页面保持打开。Web Push 不需要:浏览器为这个来源保存一个订阅,面板用它自己生成一次的 VAPID 密钥对给每条消息签名(state/vapid.json),由浏览器厂商的推送服务唤醒 /sw.js 来显示通知。没有中继:面板直接向浏览器厂商发送。只有当 pywebpush 能导入时才提供(GET /settings → push_available)。

RouteWhat
GET /sw.jsservice worker,从根作用域提供,带 Service-Worker-Allowed: /
GET /push/key{ ok, available, public_key, subscriptions },浏览器用来订阅的 VAPID 公钥(不可用时返回 503)
POST /push/subscribe表单 subscription = PushSubscription 的 JSON;每个 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

FieldTypeNote
(any setting key)string标准的完整集合见 state/panel_settings.json。
notify_done1/0完成提醒:渲染完成或失败时,标签页里响起提示音;标签页在后台、且用户已允许时,还会有浏览器通知。默认开启;GET /settings 会返回它。

POST /prompt/enhance

表单编码。用 Gemma 预先改写一个提示词。面板里的“优化”按钮(视频和对口型)使用它。

FieldNote
prompt必填
modet2v(默认)、i2v 或 a2v(对口型:i2v 的辅助提示词加上对口型提示词规则)
preserve_tokens结果中必须保留的词的 JSON 列表(或逗号分隔的列表),大小写完全一致,也就是触发词
translate0 表示让非拉丁文字的提示词保持它自己的语言;默认会翻译成英语
loras4.18.0:渲染所用的已安装 LoRA 路径的 JSON 列表。面板会从 LoRA 库里读取每一个的名称、触发词和指南(没有就用作者的描述),库里没有列出的路径会被忽略,最多把 4 个、有限长度的内容作为带围栏的参考文本交给 helper。如果某个 LoRA 的触发词在结果里全部缺失,会把它的第一个触发词放回最前面。

返回 { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] };当渲染占用 GPU 时返回带 409 的 { error }。

409 needs_pack(4.20)。 优化功能运行在 Gemma 3 上,全新安装会在第一次启动之后,于后台下载它(见 GET /status 下的 deferred_downloads)。在它落到磁盘之前,这个路由返回 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state },其中 pack_state 是 downloading、queued、waiting_disk、missing 之一,并且绝不会要求 helper 去加载它。/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/>"}。


附属 JSON 格式

每个完成的片段,都会在 MP4 旁边写一个 <output>.mp4.json 附属文件。结构(简化):

{
  "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 }
}

读取附属文件,就可以不用再向面板查询而比较各次运行。


制作配方(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

在 64 GB 的 M4 Max 上耗时:1024×576 时每个 7 秒片段约 7:06,736×416 时约 3:24。


完整示例:一个智能体驱动程序

提交一个带两个 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 移除。移除前的快照以标签 pre-agent-removal-2026-05-15 持久保存在 GitHub 上。

聊天过去能做的一切:规划多个镜头、生成候选的锚点图片、渲染以这些锚点为条件的 I2V、管理会话,都可以由外部智能体通过上面记录的 API 完成。具体来说:

  • 镜头规划:由智能体一侧的文本推理完成,不需要面板参与。
  • 锚点生成:POST /image/generate。
  • 锚点到视频:POST /queue/add,带 mode=i2v 和 image=<anchor_path>。
  • 会话状态:由智能体在外部维护。

外部智能体可以通过这套 API 使用文档里记载的工作流程。

来源:docs/API.md,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。