ヘルプ / APIとエージェント
エージェント用HTTP API
このサイトでは、サポート対象のワークフローとフィールドのうち一部だけを取り上げています。内部APIの全体は載せていません。
オリジナルまたは様式化されたキャラクター、あるいは文書で同意が確認できる自分自身の姿を使ってください。ほかの実在の人物を描く場合は、その人物の文書による同意が必要です。すべての参照画像、学習データ、音声、出力について、利用規約(Acceptable Use Policy)に従ってください。
外部のエージェント(Claude Code、Codex、OSS、またはHTTPが話せるものなら何でも)は、このAPIを通してPhospheneを操作します。パネル内のチャットは2026-05-15に廃止されたため、パネルの中にエージェントはもう組み込まれていません。以前チャットでできたことは、すべて外部のエージェントがこれらのエンドポイントを使って実行できます。
このAPIの上に作られた既製ツール: Claude Code、Codex、その他のMCPクライアント向けの phosphene コマンドとMCPサーバーが agents/ にあります。エージェント用ツールをご覧ください。
サーバー
- ベースURL: 通常のインストールでは
http://127.0.0.1:8198です。8199はDEVプロファイルのポートで、このページの例はすべて、書かれた当時のパネルに合わせて8199を使っています。ルールはソース内の1行(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のデフォルトのままで、上書きしていません。そのためリクエストのたびに接続が閉じ、パイプライン化できるキープアライブはありません。 - 認証: なし。ループバックにのみバインドされています。
規約
- すべての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で一度同意するまで、{"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"}とともにHTTP 451で返ります。対象は/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/以下のパスは、{"error": "agentic flows removed; see docs/API.md"}とともに 410 Gone を返します。/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 fpsで学習されており、外れると品質が落ちます。 |
character_strength | float | 初期値は 1.0。キャラクターLoRAの強さ、0〜2。 |
seed | int or -1 | -1 = ランダム。 |
quality | quick | balanced | standard | high | キャラクターLoRAを使う作業では high を使ってください。 balanced は、121フレームを超えるクリップを黙ってQ4の蒸留トランスフォーマーに回し、現行のLoRAでは本人らしさが失われます。 |
stage1_steps, stage2_steps | int | HQの2段階パイプライン。検証済みの初期値:10 / 3。 |
teacache_thresh | float | 検証済みの高速化の頭打ちは 1.8–2.0。1.6 未満では高速化しません。高いほどキャッシュが積極的になります。 |
cfg_scale | float | Classifier-free guidance。3.0 が検証済みの初期値です。 |
bongmath_max_iter | int | サンプラー内部ループの上限。100 が上流の最大値です。 |
upscale | off | fit_720p | fit_1080p | 任意の後処理。 |
upscale_method | lanczos | pipersr | upscale != off の場合。 |
accel | off | (ほかのモードはパネルのソースを参照) | 高速化のつまみ。 |
enhance | true | false | true の場合、エンコード前にGemmaがプロンプトを書き換えます。プロンプトにLoRAのトリガーワードが含まれる場合は false にしてください。 書き換えでトリガーワードが消えることがあります。 |
hdr | true | false | HDR ic-loraのパス。 |
image | path | I2V専用。参照PNG/JPGへの絶対パス。必須:v4.6.1以降、i2v / i2v_clean_audio で image を省略または空にすると、読みやすいエラーとともにジョブ開始時に拒否されます。以前は、どのインストールにも同梱されたことのないデモファイル examples/reference.png が既定になっていました(その既定が、全体で最も多かったレンダリング失敗の原因です:image not found: <path>、14日間で22人に35件)。LTX_DEFAULT_IMAGE が実在するファイルを指している場合は、引き続き既定として使われます。 |
audio | path | 任意の音声参照。 |
label | string | キューカードに表示する任意のUIラベル。 |
temporal_mode | native | fps12_interp24 | windows。windows は、121フレーム1つ分を超えるレンダリングを連続したシーケンスとして処理します。1回の generate のあと、直前のウィンドウの残したテールから、後続のウィンドウごとに1回ずつ extend を実行し、指定の長さに切り詰めます(ltx_windows.py:stride = window - discard - overlap、count = 1 + ceil((total - window + discard) / stride))。Q8アドオンと、延長を許可するティアが必要で、そうでなければ文言付きで拒否されます。ジョブには long_mode として保存されます。 | |
window_prompts | ウィンドウごとに1行のJSON配列(または改行区切り)。1行目が空 = プロンプト、後ろの空行は直前の場面を保持。後続の各ウィンドウのプロンプトは、まずその行、次に継続の文、最後に Throughout: <window_invariants>. という順になります。これがH3のチェーン規約であり、動きから書き始めるルールです。 | |
window_invariants | ウィンドウ間で変えないもの(誰、どこ、光、レンズ)。後続のすべてのウィンドウに再度挿入されます。 | |
loras | JSON-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の経路がないため、アップデートを促す文言とともに拒否されます)。
| フィールド | 型 | 備考 |
|---|---|---|
h3_quality, h3_length | string | セル。h3_quality=fast_hd = 640×384のFastパスと、1280×768へのアップスケール&フェイス修正を一緒にキューに入れたもの。FastとFixは強制されます。 |
h3_continuity | on | off | 初期値は on:連鎖したウィンドウは、直前のウィンドウの最後の17フレームとその音を引き継ぎます(--chain-context-frames 17)。off = 1枚の静止画での引き継ぎ。 |
start_image, end_image, keyframes_json | path / JSON | mode=keyframe。H3では開始フレームは任意です(終了フレームだけの場合はMiniMaxのラストフレームタスク)。keyframes_json のビートは、24 fpsのタイムライン上の frame_index の位置に置かれます。 |
video_path, h3_extend_seconds | path / float | mode=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_path | path | mode=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)が必要です。古いパックはアダプターを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 になります(再試行はバックグラウンドです)。
| フィールド | 型 | 備考 |
|---|---|---|
id | string | 元のジョブID。 |
{"ok": true, "id": "<new-id>", "source_id": "<old-id>"} を返します。
POST /queue/remove
キューにあるジョブを削除します。(実行中のジョブは削除できません。/stop を使ってください。)
| フィールド | 型 | 備考 |
|---|---|---|
id | string | ジョブ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
複数のプロンプトを1つのバッチとして送信します。
| フィールド | 型 | 備考 |
|---|---|---|
prompts | string | 改行で区切ったプロンプト。 |
(そのほか /queue/add の標準フィールドがすべて、各行に適用されます) |
ステータス:ジョブの状態をポーリングする
ワンショット専用の入口:POST /oneshot(2026-09-08)
ワンショットはワークフローのタブであり、第一級のAPIでもあります。スクリプトは、タブが送るのと同じドキュメント(1つのJSONオブジェクト)をPOSTし、キューに入ったジョブを受け取ります。
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 | 必須 | ショット全体を一度だけ。誰が、どこで、時間帯と天気、音。ビートがない場合は、5秒ごとのすべてにこれが使われます。 |
seconds | int | 60 | 30 / 45 / 60 / 90 / 120 のいずれか。ほかの値は丸められずに拒否されます(以前は75が1本のクリップとしてレンダリングされていました)。 |
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 | list or newline text | なし | 5秒ごとに1行。空行はその瞬間を保持し、余分な行は捨てられます。なし = プロンプトがすべてのビートになります。 |
camera | str | "" | ショット全体で1つの動き(向きと速さ)。すべてのパートに引き継がれます(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 | すべてのビートに付く連続性の文。パートごとにドリフト用のリテイクが1回。 |
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}:絵コンテのプランナーが、プロンプトから5秒ごとに1ビートを書きます(20〜40秒の間はブロックされます):{ok, beats:[…]}。
GET /oneshot/status:current(id、label、part、parts、パートごとの lipsync、drift、handoff)、queued、recent、およびテイク自身の log 行。
内部では、すべてのワンショットが下記のテイク規約に従います。POST /oneshot はドキュメントを make_job のフォームに写像するので、タブ、API、/queue/add は、まったく同じジョブをレンダリングします。
1テイク:POST /queue/add の take_seconds と beats
どちらのエンジンでも、1回のパスより長いクリップを作れます。take_seconds は 30 / 45 / 60 / 90 / 120 のいずれかで、beats は5秒ごとに1つのプロンプトを並べたJSONリスト(または改行区切りのテキスト)です。空のビートは直前の場面を保持し、余分なものは捨てられます。ビートがまったくない場合(フィールドがない、空、または空行だけ)、prompt がすべてのビートになります。つまり、テイク全体を通して持続するプロンプトのショットです。4.12.1より前は、この場合すべてのウィンドウが「保持」の文でレンダリングされ、何についてでもないテイクになっていました。テイクは、エンジン自身の長さフィールドより優先されます。両方のエンジンで、最後のフレームの引き継ぎでつながれた複数のパーツとしてレンダリングされます。run_take_job_inner はパートごとに通常のレンダリングを1回ずつ実行し、それぞれが直前のパートの最後のフレームから始まり(i2v、アンカー付き)、パートをギャラリーから隠して、<name>_take<seconds>s.mp4 に結合します。
| engine | パート | make_jobが行うこと | ワーカー |
|---|---|---|---|
ltx | 10秒 = 2ビート = 241フレーム(45秒のテイクは、1ビートの121フレームのパートで終わります) | frames = 241、temporal_mode = native(テイクは、フォームが何を送っても、ウィンドウのチェーンにはなりません) | パートごとに run_job_inner を通した通常のLTXレンダリングが1回:パート1は t2v、またはジョブが i2v として届いた場合はそのジョブ自身の image からの i2v。以降のすべてのパートは、直前のパートの最後のフレームからの i2v で、i2v_reference_mode = anchor です。画質は任意。Q8パックが必要になるのは、1本のクリップと同じく、HQ画質の場合だけです |
h3 | 15秒 = 3ビート | h3_length=15s、h3_chain_prompts = 最初のパートのビート | パートごとに通常のH3レンダリングが1回(直前の最後のフレームから --first-frame) |
任意のフィールドが2つあり、どちらも初期値は on です。
| field | off の意味 |
|---|---|
take_light_lock | 連続性の文(take_light_lock()、「it is still night…」)がビートに追加されません。take.light_lock は "" になり、空のビートは「保持」の文だけで保持されます |
take_retake | 光が TAKE_DRIFT_MAX を超えてずれたパートが、新しいシードでの一度のリテイクではなく、レンダリングされたままで残されます。take.retake は false になります |
take_camera | 任意の自由記述。ショット全体で1つの動き(「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.15〜−0.01 に対して +0.54 / +0.47 と、次のパートの口に声を運べると測定された唯一のアンカー)、セリフの終わりと0.4秒の減衰までの音を残し、その尾(part{k}_tail.wav、amix normalize=0)を次のパートの頭(part{k+1}_lead.mp4)に重ねます。これはJカットで、最後の言葉が最後まで聞こえます。尾の余地を作るため、各パートの最初のビートは無音で始まるように書いてください。各セリフのあとの無音の尾は削られるため、テイクは名目の長さより短くなります。最後のパートは切り詰められません。話している各パートは take_lipsync_score() で採点され、TAKE_LIPSYNC_MIN = 0.20 を下回ると、新しいシード(ids -pNl、-pNl2)で最大 TAKE_LIPSYNC_RETAKES = 2回までリテイクされます。最良のクリップが残され、そのスコアは job["take_lipsync"] に記録されます。take.handoff として記録されます |
ジョブの params.take:{seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}。frames はテイク全体の
フレーム数(LTXでは seconds·24+1)、part_frames は1パート分の全体です。出力の
サイドカーには 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 は、両方のエンジンでのパート数です。分数は、
パート数 × 1パート分の単独クリップの価格で、ほかのすべての見積もりと同じコストモデルによります
(H3:測定済みの15秒のセル。LTX:画質の 10s
のセル、LTX_TIERS、1ビートの末尾は 5s のセル)。このMacに数値がない場合は null です。
needs_q8 は今は常に false です。LTXのテイクは、選んだ画質がレンダリングに使うものの上でそのままレンダリングされます。
GET /status
すべての outputs[] の行には q が入ります。これは、その出力の検索用の単語を小文字にしたもので、すでにサイドカーを読んでいる一覧作成のパスで作られます。内容は、プロンプト、ラベル、モード、画質、エンジン、キャラクター、シード、WxH、Nf、LoRAのファイル名の語幹、モデルのディレクトリ名、temporal mode、windows です。ギャラリーの検索ボックスは name + q に対する部分一致で、入力したすべての単語が一致する必要があり、入力すると古い出力も読み込まれるため、検索はすべてを対象にします。
すべての動画の行には silent も入ります。クリップに音がない場合は true(mp4ヘッダーに音声トラックがない、または −80 dBを超えることのないトラック)、音がある場合は false、まだ不明な間は null です。ヘッダーの読み取りはインラインで行われ、レベルのチェックはファイルごとに一度だけバックグラウンドスレッドで実行され、(mtime, size) ごとに state/output_silence.json にキャッシュされるので、ポーリングで何かがデコードされることはありません。/status.h3.video_to_audio が真のとき、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 }。新規インストールが、スタートのあとにダウンロードするようキューに入れたパックです(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)を保持している間は真です。その間、パネルはそれらのパックのダウンロードを提供せず、リクエストは409app_downloadingで拒否されます。すでに書き込み中のパックフォルダに対して、もう1つscripts/fetch_pack_release.pyを実行すると、何も変更せずに終了コード75で止まります。queue:待機中のジョブ。FIFOの順。history:完了または失敗したジョブ。各エントリにはstatus、elapsed_sec、output_path、raw_path(アップスケール前のネイティブ)、errorがあります。log:ヘルパーの標準出力行のローリングバッファ(直近約50ジョブ分)。
ポーリングのループ: /status に15〜30秒ごとにGETします。ジョブの 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番目のestimate(最初のestimateはまだほぼノイズです)、2段階のHQ経路では2番目のestimate(ステージ2の各ステップでデノイザーを2回評価します)。estimateを数えるクライアントは、どのスケジュールが動いているかを知っている必要があります。
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(パネルで学習したLoRAは train_character、それ以外は null)、adapter_verdict(下記参照)、および判明していればCivitAIのメタデータが含まれます。
adapter_verdict:このファイルに効果があるかどうか
LoRAは、学習を最後まで終え、有効なsafetensorsを書き出し、警告なしで読み込めても、何も変えないことがあります。学習したデルタが数値的に小さすぎて、モデルを動かせないのです。構造上のチェックはすべて通ります。どのチェックも、キーが合っているかどうかを見るだけで、中に何か入っているかどうかは見ていないからです(#61、#62)。
adapter_verdict(_adapter_verdict)は、サイドカーの adapter_strength ブロックから読み取られ、次のいずれかです。
| 値 | 意味 |
|---|---|
ok | 測定済みで、デルタRMSが有効な範囲にあります。 |
weak | 測定済みで、デルタが WEAK_DELTA_RMS(2.0e-4)以下です。ファイルは残されますが、レンダリングはほぼ確実にLoRAなしのように見えます。 |
unknown | 測定しないビルドで学習されたものです。weak の同義語ではありません。 無言は弱さではなく、測定が導入される前のLoRAはすべてこう読み取られます。 |
それ以外は、トレーナーが付けた名前がそのまま渡されます。
呼び出し側は、レンダリングを使って確かめる前に weak を提示するべきです。unknown は装飾してはいけません。
GET /train/list も同じ判定を返し、さらに adapter_advice を返します。これは、どう対処すべきかを示す1文で、判定が ok または unknown の場合は空です。ハードウェアに応じて内容が変わり、64 GB未満のMacでは「ハイでもう一度学習」とは言いません。そのマシンでは検証済みのレシピに届かないからです(下のプロファイルの節を参照)。パネルの学習タブでは、学習済みキャラクターのチップの上にバナーとして、および完了したジョブの履歴の行に表示されます。ユーザーが対処できない判定は、答えではなくただの測定値です(#62)。
GET /hf/loras
CivitAIの隣に並ぶ、閲覧可能なソースとしてのHugging Face。?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1。
Phospheneは特定の組織を指定しません。クエリは、検索(空 = そのレーンの既定の検索語)、作者の一覧、または1つのリポジトリです。結果は、リポジトリ名とタグからレーンごとに振り分けられ、各リポジトリの最大の .safetensors と、そのサンプルクリップが、CivitAIのグリッドが表示するのと同じ形式の1項目になります
(name、creator、likes、size_kb、preview_url / preview_type、download_url、filename、base_model、hf_url、source: "huggingface")。
レーンとクエリごとに10分間キャッシュされます。
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_id を持つインストール済みのLoRAのうち、新しいバージョン
(modelVersions[0].id ≠ サイドカーの civitai_version_id)があるものがないか、CivitAIに問い合わせます。
該当するLoRAごとに1リクエストで、何もダウンロードされません。
{ "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が何をするか、どうプロンプトを書くか、開始に適した強さ、何と相性が悪いか、を1段落のガイドとして書き、
サイドカーの guide に保存します。その後、GET /loras の行には guide が含まれます。レンダリングの実行中は409で拒否されます(プランナーは12Bモデルです)。
{ ok, guide } を返します。
POST /loras/refresh
mlx_models/loras/ を再スキャンします。/loras と同じペイロードを返します。
POST /loras/delete
| フィールド | 型 | 備考 |
|---|---|---|
id | string | /loras のLoRA ID。 |
ファイルを削除します。{"ok": true} を返します。
POST /h3/loras/import
multipart/form-data。すでに持っているHailuo H3のアダプターを、H3専用の
LoRAライブラリ(mlx_models/hailuo-h3/loras/、またはインストールされたパックが保管している場所)にインストールします。
意図的に /upload ではありません。参照メディアはどんな画像や音声でもよいのに対して、H3のアダプターは、
ピッカーに表示される前に、ランナーのレイアウト規約を通過する必要があるためです。
| フィールド | 型 | 備考 |
|---|---|---|
file | file | .safetensors を1つだけ。ファイル名はベース名に縮められてサニタイズされ、ライブラリにすでにあるファイルと重複してはいけません。 |
ボディは、バッファリングされずに、非表示のステージングディレクトリにストリーミングされるので、数ギガバイトの
アダプターでも常駐メモリは約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 のアップロード。学習データセットに画像を1枚追加します。このルートは
1リクエストにつき1ファイルで、バッチではありません。画像はループで送り、最初の呼び出しのあとは毎回、返された
train_job_id を送り返して、全体が1つのディレクトリに入るようにしてください。
| フィールド | 型 | 備考 |
|---|---|---|
job_id | string | 最初の呼び出しでは任意(新しいIDが発行されます)、それ以降は、バッチをまとめるために必須。名前に注意:job_id で、train_job_id ではありません。レスポンスは train_job_id として返します。 |
file | file | PNG/JPG/JPEG/WEBP/BMPのいずれか1つだけ、または .txt のキャプション。 |
リクエストボディの上限は TRAIN_MAX_BYTES_PER_IMAGE(32 MB)です。この上限はリクエスト全体に対するもので、ルートが1ファイルしか取らないため、個々の画像が小さくても、複数ファイルのボディは拒否されます。
データセットの状態(train_job_id、画像数など)を返します。
POST /train/start
キャラクターLoRAの学習を開始します。パネルは lora_lab.train_character をシェル実行し、進捗イベントを STATE['log'] にストリーミングします。
| フィールド | 型 | 備考 |
|---|---|---|
train_job_id | string | /train/upload から。 |
trigger | string | トリガートークン。例:explorertrn。通常の言葉と衝突しないよう、複合語で、めずらしく、文字だけにしてください。数字は、ごくありふれた1文字のトークンに分かれてしまいます(mrz07 → m / rz / 0 / 7)。これまでに本人らしさを保てたトリガーは、すべて文字だけでした。パネルは <3 consonants>trn(mrztrn)を提案し、トリガーに数字が含まれていると注意をログに出します(#62)。キャラクターLoRAは mlx_models/loras/<trigger>_v2.safetensors に保存されます。 |
preset | quick | medium | high | ハイパーパラメータのプリセット。v4.6.1で既定が変わりました:省略すると、train_type=character では high、train_type=style では quick になります(TRAIN_DEFAULT_PRESET)。以前は両方で quick で、これは本人らしさを保てたことのないティアです(#62)。下の表をご覧ください。ステップ数は定数ではなく、64 GB未満のMacでは、ほかのどれも定数ではありません。 |
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に何千ステップものジョブを入れられては困るからです。
64 GB以上のMacの場合(TRAIN_PRESETS、mlx_ltx_panel.py:1558):
preset | エポック | ランク | 解像度 | max_steps | 人物の再現性の評価 |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | なし。 ピルには「人物の再現性は未評価」と表示されます。 |
medium | 60 | 16 | 576 | 12000 | なし。 同じです。 |
high | 100 | 32 | 512 | 20000 | あり。 検証済みのv2レシピ(Aria_v2、Bizarro_v2)。既定で、ピルに「おすすめ」のバッジが付くものです。 |
lora_compat.py で測定すると、本人らしさを保てているランク32のアダプターは delta_rms が5.4e-04〜1.6e-03にあります。2人の別々のユーザーのランク8 quick の実行は1.54e-04と1.98e-04で、どちらも WEAK_DELTA_RMS の下限2.0e-04以下でした(#62)。
つまり、high は50枚で5000ステップ、20枚で2000ステップ、300枚で20000ステップ(上限)です。人の目の前に出して良いと評価されたことがあるのは、ランク32のレシピだけです。
⚠️ 64 GB未満では、すべてのプリセットが、静かに別のプリセットになる
_select_train_profile(mlx_ltx_panel.py:1650)はインポート時に一度実行され、総RAMが 0 < ram < 64 GB の場合、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)。このハードウェアでは、検証済みのレシピを求めても得られません。
これは意図的なトレードオフで、理由もはっきりしています。512 pxのLTX LoRAのフル学習は、devトランスフォーマーの逆伝播のアクティベーションを実体化するため、48 GBのMacではスワップが多発して、終わらなくなります。ただし、その意味は明確にしておきましょう。64 GB未満のMacには、誰かが評価したレシピを学習するプリセットは存在しません。 ランク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)。プリセット名を信じる前に、それらを読んでください。 それらは書き換え後の値であり、上の2つのテーブルを実行時に区別できる唯一の場所です。
adapter_strength トレーナーイベント
分析用のイベントではありません。何もマシンの外には出ません(外に出るものの完全な一覧は、docs/ANALYTICS.mdをご覧ください)。これは、lora_labのサブプロセスのストリーム上の進捗イベントで、トレーナーが書き出したばかりのファイルを測定したあとに一度だけ発行されます(mlx_ltx_panel.py:18005)。パネルは、デルタRMSの中央値、最大値、効いているモジュールの数をログに出し、判定が ok でない場合は、ジョブを単なる done ではなくWARNINGの状態で完了させます。判定は、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/ で見つかった1人のキャラクターを表します。
| フィールド | 型 | 備考 |
|---|---|---|
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> を付けると、/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 が使われ、シート全体を1つの数字から再現できます。各ビューのプロンプトは、衣装を参照画像に固定します(「wearing exactly the same clothes as in the reference image」)。wardrobe は、その上に服装を言葉でもう一度指定します。最初のあとのビューは、最初にレンダリングされたビューも第2の参照としてつなぎます。暗い参照画像で測定したところ、単独の横向きのレンダリングは、シードや言い回しによって髪の色を想像し直しましたが、同じ実行からのきれいな正面が、元の参照では不足している属性を再び固定します。ビューごとのフレーミングは、それでもずれることがあります(あるビューで被写体が中心から外れるなど)。その場合は、再生成するかシードを変えてください。成功すると、bundle.json の preview は、それが null だった場合にのみ sheet.png を指すようになり、手作業で選んだプレビューが上書きされることはありません。
POST /characters/<id>/generate
固定された制作レシピを組み立てて、T2Vのレンダリングをキューに入れます。このエンドポイントは prompt_body、framing、duration、quality、そして任意の整数 seed(-1 はランダム、/queue/add と同じ)を受け付けます。厳密な再現やデバッグの呼び出しでは、呼び出し側は full_prompt と、stage1_steps、stage2_steps、teacache_thresh、cfg_scale、bongmath_max_iter、video_skip_step、audio_skip_step などのHQの上書きフィールドを渡せます。
画像生成(動画とは別)
POST /image/generate
同梱の画像エンジン(mflux、BFL、モックのバックエンド)で静止画を生成します。呼び出しごとに差し替え可能です。
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キーなど)を読み書きします。パスにかかわらず、これは画像エンジンの設定であり、廃止されたチャットエージェントでは「ありません」。
絵コンテ:映画を計画し、撮影する
ボードとは、1本の映画のことです。コンセプト、出演者、ロケーション、そして番号付きのショットリストからなります。ボードが開始するすべてのレンダリングは、/queue/add と同じ make_job → キューの規約を通ります。これらのルートに、独自の実行経路はありません。ボードは state/storyboards/<board_id>/ の下に置かれ、storyboard.json はアトミックに書き込まれます。レンダリングは何時間も続くため、ボードが壊れると実行全体が失われてしまうからです。
読み取り
| ルート | 戻り値 |
|---|---|
GET /storyboard/list | すべてのボード(新しい順)。 |
GET /storyboard/get?id=<bid> | 1つのボードのドキュメント。 |
GET /storyboard/films | ディスク上の組み立て済みの映画:プレイヤー用のパス、再生時間、映像サイズ、ディスク上のサイズ、作成日時。list_outputs は OUTPUT/*.mp4 をglobして下の階層には降りないので、これがないと、この機能が作る唯一のものを、アプリが表示できなくなります。 |
ブリーフのスイッチ(plan で使用)
| フィールド | ボードのキー | 効果 |
|---|---|---|
auto | auto | プランの完成後:すべてのショットをレンダリングし、カットし、組み立てます。もうボタンは不要です |
anchor_stills | anchor_stills | テキスト/キャラクターのショットのレンダリング前に、通常の画像ジョブがその最初のフレームを作り(still_job_id → still。キャラクターのシートがあれば、qwen_edit_inline を通して参照になります)、クリップはそこからi2v · anchorとしてレンダリングされます。失敗した静止画は still_error を設定し、そのショットはアンカーなしで一度だけレンダリングされます |
long_windows | long_windows | 121フレームを超えるLTXのショットを、収まるように切り詰めるのではなく、ボードのスタイルとショットのロケーションを window_invariants として、temporal_mode=windows(Q8のdevトランスフォーマー上のチェーン)でレンダリングします。延長ではウィンドウごとに画像を再注入できないため、アンカー付きの長いショットは、最初のウィンドウだけでアンカーされます |
take_seconds | take_seconds | 1テイク:映画が30 / 45 / 60 / 90 / 120秒の1つのショットになります。プランナーは5秒ごとに1ビートを書き(_sb_take_concept)、ボードは beats 付きの1つのショットを保ち(collapse_take)、カードには編集用にビートが表示され、shot_to_job は take_seconds + beats をPOSTします。これは動画タブのテイクなので、どちらの入口でも同じレンダリングになります。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、スロットの長さ、展開の指示、2つの決まり(すべての説明を動きから始めること、セリフは入れないこと。トラックがすべてのクリップの音を置き換えます)が含まれ、計画された各ショットの duration_s は、そのスロットに1秒のハンドルを足したものになり、ショットには slot: {start, end} が付きます。曲のマップが、頻度を決めます。 song_map()(storyboard_edit)は、同じ小節のグリッド上にセクションを置きます。{start, end, label, energy, brightness} で、ラベルは位置、相対的な音量、明るさから決まる intro / verse / chorus / bridge / outro です。director_pacing() は bars_per_shot をセクションごとのストライドに変えます。コーラスは2倍の頻度で、イントロとアウトロは半分の頻度でカットされます。各スロットは 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です。
| アクション | フィールド | 備考 |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | プランまたは再プラン。レンダラーがメモリを保持している間、またはプランナーの1つの枠が使用中の間は409。 shots は、受け入れられるか拒否されるかのどちらかで、別の数に黙って差し替えられることはありません。再プランは、ロケーションと衣装を上書きせず、パッチします。 |
cancel | id | プランナーの枠を解放します。 |
save | JSON {id, board} | 手で編集したボードを書き込みます。 |
grade | id, n, grade, note | 1つのショットを評価します。 |
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)、元のロケーション、元の出演者が一緒に引き継がれます。どれか1つでも残すと、特定の何かが壊れます。対象の映画がレンダリング中は拒否されます。 |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Finderに表示します(macOS)。 |
delete | id |
ボードのスキーマ:地理のフィールド
ショットは、そのロケーションから構成されます。2026-08-18以降、ロケーションは複数の方向から見ることもできるようになり、これによって、逆アングルが2つ目のロケーションではなく、本当に逆アングルになります。
"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} のリスト。ロケーションにビューがない場合は、[] ではなく存在しません。ビューが導入される前に書かれたすべてのボードにはキーがなく、空のリストは、得るものもないのにバリデーターが意見を持つ新しい形になってしまうからです。IDは、ロケーションのIDと同じ文字セットに従います。 |
shots[].view | ショット | そのショットの location_id に属するビュー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 がショットを画面上の順に調べ、同じロケーションで異なる2人のキャラクターの間をカットする隣り合う2つのショットが、どちらも同じ側を主張している場合、2つ目を反転させ、warnings にその旨を書きます。eyeline は、補集合がちょうど1つしかない離散的なフィールドなので、機械的に修正されます。反転しても、誰の文章も傷つけません。文章レベルの決まりは、その性質がないため、モデルとのやり取りを1往復して対処します。
エディター:タイムライン
エディターは、絵コンテの一段階ではなく、トップレベルのワークフローです。エンジンに依存せず、ボードがレンダリングの途中でなくても開け、そのドキュメントはボードのディレクトリの下の edit.json です。映像トラックは1本、音楽レーンは1つです。クリップごとの音はデフォルトでリンクされており、切り離すこともできます(JカットとLカット)。それは2本目のオーディオトラックではありません。
読み取り
| ルート | 戻り値 |
|---|---|
GET /storyboard/edit?id=<bid> | アレンジメント。ボードへの最初の呼び出しでは、自動編集を一度だけ実行し、自動のレーンに保存して、generated: true を付けて返します。以降のGETはすべてファイルの読み取りです。破損した edit.json は corrupt: true を付けた500 を返し、黙って置き換えられることはありません。それをすると、壊れたコピーの元になっているアレンジメントが捨てられてしまうからです。 |
GET /storyboard/edit/status?id=<bid> | 準備ジョブの状態。 |
GET /storyboard/edit/peaks?id=<bid> | 波形。数百KBあるので、一度だけ取得し、ポーリングでは決して取得しないでください。prepare が実行されるまでは 404 です。 |
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4 | プロキシ動画。レンジ対応で配信されます。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>
| サブ | フィールド | 備考 |
|---|---|---|
prepare | id, music, target_seconds | プロキシと波形のピークを作ります。music がファイルでなければ 400。 |
add-clip | id, from, only, path, title, kind | kind は video | still | slug。これを渡すことで、画像がフレームのない動画として置かれるのを防ぎます。 |
add-sound | id, path | オーディオトラック用の1ファイル:プローブされ({path, title, duration_s, has_video, imported})、音がなければ 400。OUTPUT の外にあるファイルは、まず映画自身の audio/ フォルダにハードリンクされます(ボリュームをまたぐ場合はコピー)。/file は OUTPUT しか配信せず、プレビューが再生できないサウンドは半分のサウンドだからです。ストリップの配置と保存はクライアントが行います。 |
relink | id, only | クリップを、完成した(納品用の)ファイルに付け替えます。完成したリテイクが、そのバッチに含まれることはありません。ペイロードの relink 行で retake: true を付けて、そのクリップに対して提示され、only=<clip id> で1クリップずつ採用されます。 |
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のスケールを1回かけ、拡大のみで、トリミングはなく、カットがすでにその高さならスキップされます。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 を持ち、レンダリングが終わると、エディターはそれをそのクリップと比べる形で提示します(「使う」/「元のままにする」)。クリップがすでにタイムラインにない場合は400です。 |
save の意味。 revision はサーバーのカウンターで、ディスクから取られ、クライアントが覚えていたものからではありません。古いタブがそれを巻き戻してはいけないからです。expect_revision を渡すと、別のタブを黙って上書きするのではなく、追い越されたことが分かります。不一致は 409 と conflict: true と現在のリビジョンを返します。検証エラーはすべて一度に返され(errors: [...]、400)、ディスク上のファイルは変更されないので、クライアントは、もぐらたたきをせずに、1回で不正なクリップをすべて強調できます。
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 | 映画上のスロット。互いに独立ではありません。 クリップは1倍速で再生されるので、LENGTH_TOLERANCE(2 ms)以内で film_end - film_start == end - start です。 |
kind | 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 するので、1つの文字列がすべてのサイズで正しくなります。プレビュー:同じアンカーを中心としたCSSのスケール(近似)。書き出し:FCP7 Basic Motion(スケール + 中心)とAEのスケール + 位置。ニュートラルは省略されます。スラグにはリフレームするものがありません。 |
speed | 再生レート、SPEED_MIN〜SPEED_MAX(0.25〜4.0)、動画のみ。スロットは (end - start) / speed なので、上の1倍速のルールは「その速度で」と読みます。映像は setpts、音はffmpegの0.5〜2.0の範囲を超えて連結された atempo で、音のエンベロープ(afx)はストリップの再生クロックのままです。2秒のキーフレームは、リタイム後もストリップの2秒の位置にあります。省略は1倍速です。 自動では設定されません。 |
audio | スプリットエディット。下記をご覧ください。 |
clip.audio:JカットとLカット
"audio": {"start": 3.5, "end": 7.0, "film_start": 12.25}
動画クリップのみ。映像と同じ3つの数値を、音に対して持ちます。そのため、音は映像より先に始まる(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 はファイル内のイン点とアウト点です(ストリップは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*。
レンダリング: 聞こえるすべてのストリップ(ミュートされておらず、トラックもミュートされておらず、カーブが無音でないもの)は、オーバーレイのあとの1つの -vn -i になり、atrim → volume(そのカーブ、ストリップのクロック上)→ aresample → adelay(サンプル単位)→ apad → 映画に合わせた atrim を通り、そのすべてが、クリップの音とベッドの上で amix(normalize=0、duration=first)され、1つの asoftclip リミッターの下に入ります。映画の情報には sound_strips と mix_peak が入ります。ファイルがないストリップがあると、そのパスとトラックを示してレンダリングが拒否されます。書き出し: 各トラックはそれぞれがFCP7のオーディオトラックになり(イン/アウト付きのクリップアイテム、レベルのキーフレーム、ミュートには <enabled>FALSE</enabled>)、各ストリップは <track> · <title> という名前のAfter Effectsのレイヤーになります。
transitions[]:境界を所有する型付きオブジェクト
"transitions": [{"id": "t1", "after_clip": "<clip id>",
"kind": "dissolve" | "fade_black", "duration": 0.5}]
クロスディゾルブは、同じ秒にある2つのクリップであり、映像レーンの「一度に1クリップだけ」というルール(clips_overlap)は支えとなる前提なので、トランジションはオーバーラップではありません。それは、アウトゴーイングのクリップを指名し、映画の順序でそのクリップと次のクリップの間のカット上に置かれ、境界ごとに1つです。クリップ自身の film_start/film_end は動かず、映画はタイムラインが示す長さのままです。レンダリングは、アウトゴーイングのクリップのアウト点の先から、継続時間の半分の余分な尾を、インカミングのクリップのイン点の前から、半分の余分な頭を(トリムで残されたソースから)引き出し、境界で映像のconcatを分割し、カットを中心にした xfade(fade / fadeblack)で2つの区間をつなぎます。音には新しいものは必要なく、Jカットとまったく同じように、レーンの経路(_sb_split_audio_plan)を通ります。
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 は高さ1080のフレームでのpxで、映画に合わせて拡大縮小されます。x/y はフレームに対する割合でのアンカーで、align は、テキストのどの端が x に乗るかを指定します。overlay_text() は唯一のアクセサで、スタイルは既定値と異なる場合にのみ書き込まれます。フォントはファイルです。LTX_TITLE_FONT、なければマシン上に存在する TITLE_FONT_CANDIDATES の最初のもので、ffmpegが組み立てられる前に検証されます。どれもなければ、穴の空いた映画ではなく、文言付きで render が400を返します。ラスターは、映画の隣(.titles/)にあるフレームサイズのRGBAのPNGで、アップロードされたカードと同じオーバーレイのチェーンに渡されるため、タイトルはレーンのアルファ、フェード、重ね順を引き継ぎます。タイトルは、ステージ上の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 がまだ有効な理由です。フィールドなし、トリムなし、同じフィルターグラフ。トラックの終わり以降のトリムはトリムではなく、normalise_edit が破棄します。ハンドルを完全に元の位置まで戻しても、バイト単位で同一のグラフが残ります。 |
music_window(audio, duration=…) は、これらがffmpegとすべてのエクスポーターが必要とする数値になる唯一の場所です:start = max(trim_start, offset)(頭のトリムと正のオフセットは、2つの方向からの同じ操作で、より多く切るほうが優先されます)、end または「最後まで再生」を意味する None、そして delay/film_start = start - offset。左端をトリムしても、トラックの残りが前にずれることはありません。 それはリップルであり、音楽はリップルしないので、頭のトリムで取り除かれた秒数は、前の無音として戻ってきます。トリムによって完全に閉じられるウィンドウは、ffmpegが拒否する長さゼロの atrim ではなく「音楽なし」を返します。
ドラフト、バックアップ、履歴:3つの異なるもの
ドラフトは、同じ映画の名前付きのバリエーションで、アクティブなものを示す index.json とともに drafts/ にあります。edit.json しかないボードには、ドラフトがちょうど1つあり、以前からずっとそうでしたが、ただ名前がありませんでした。load_draft_index は、書き換えのパスではなく、その場でそれに名前を付けるので、アップグレードが中途半端に終わることはありません。
POST /storyboard/edit/draft は1つのルートに5つの動詞があります。同じアクティブなポインターに対する5つの編集であり、分割すると、そのポインターが間違う場所が5つになってしまうからです。
op | 追加フィールド | 効果 |
|---|---|---|
new | name, from=current | 新しいドラフト。空、または画面にあるものからのコピー。アクティブになります。 |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | まず現在のアクティブなドラフトを退避します。失われることはありません。 |
new、duplicate、delete、activate は、その映画のレンダリング中は busy: true を付けた 409 を返します。レンダリングはこのドキュメントをクリップごとに読んでおり、その下でタイムラインを入れ替えるのは、import-shots と restore が拒否するのと同じ危険だからです。
バックアップは私たちのもので、保存はユーザーのものです。 POST /storyboard/edit/backup は history/backup-<draft>.json に書き込み、それ以外には何も書きません。edit.json も、リビジョンも、競合チェックもありません。ユーザーが最後に保存したドラフトは、そのまま保たれます。それは GET …/drafts によって backup として公開され、提案されるだけで適用はされません。recover が採用し、discard-backup が破棄します。
履歴は、2つのレーンと1つの保持レーンで、ファイルを開かずにファイル名の接頭辞で区別されます。削除するものを決めるために50個のドキュメントを読む必要のあるプルーニングは、最初の破損したドキュメントで途中で失敗するからです。
| 接頭辞 | 内容 | プルーニング? |
|---|---|---|
edit-r* | 自動スナップショット。 | する。EDIT_HISTORY_KEEP(50)が上限。 |
save-r* | ユーザーが押した保存。 | しません。 |
keep-r* | ユーザーが名前を付けたバージョン(version)。 | しません。 |
すべての保存は、新しいドキュメントが置かれる前に、その前のものをアーカイブします(各約5 KB)。履歴の失敗が保存をブロックしてはいけません。パンくずを失うことは、画面上のアレンジメントを保存しないことに比べれば、何でもありません。origin は、1つのファイルだけを読むものがいる場合のために、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
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の再構築も、停止もありません。
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。Hailuo H3のチェックアウトに対して、scripts/pinokio/h3_deps.sh だけを再実行します。
H3のPythonパッケージを、このリリースがテストされたセット(scripts/pinokio/h3_constraints.txt、-c で渡されます。uvは
すでに範囲外にあるものをそこに戻します)で、専用のvenvに再インストールします。ウェイトも、停止もありません。パネルは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)。
| ルート | 内容 |
|---|---|
GET /sw.js | Service Worker。Service-Worker-Allowed: / 付きで、ルートのスコープから配信されます |
GET /push/key | { ok, available, public_key, subscriptions }:ブラウザが購読に使うVAPID公開鍵(利用できない場合は503) |
POST /push/subscribe | フォーム subscription = PushSubscription のJSON。エンドポイントごとに1エントリ |
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
フォームエンコード。Gemmaでプロンプトを事前に書き換えます。パネルの強化ボタン(動画とリップシンク)が使います。
| フィールド | 備考 |
|---|---|
prompt | 必須 |
mode | t2v(既定)、i2v、a2v(リップシンク:i2vのヘルパープロンプトにリップシンクのプロンプトの決まりを加えたもの) |
preserve_tokens | 結果に必ず残す単語のJSONリスト(またはカンマ区切りのリスト)。大文字小文字も厳密に。トリガーワード |
translate | 0 にすると、ラテン文字以外のプロンプトをその言語のまま保ちます。既定では英語に翻訳されます |
loras | 4.18.0:レンダリングに使うインストール済みLoRAのパスのJSONリスト。パネルは、LoRAライブラリから、それぞれの名前、トリガーワード、ガイド(なければ作者の説明)を読み取り(リストにないパスは無視されます)、最大4つまでを、制限付きで、囲んだ参照テキストとしてヘルパーに渡します。トリガーワードがすべて結果から欠けている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 のいずれか)を返し、ヘルパーにそれを読み込むよう求めることはありません。/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
M4 Max 64 GBでの所要時間:1024×576で7秒のクリップ1本あたり約7:06、736×416では約3:24。
実践例:エージェントのドライバー
2つの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。 - アンカーから動画へ:
mode=i2vとimage=<anchor_path>を付けたPOST /queue/add。 - セッションの状態:エージェントが外部で保持します。
外部のエージェントは、このAPIを通して、記載されたワークフローを使えます。
出典:docs/API.md(公開リポジトリ)。公開前にこのウェブサイト向けに確認済みです。英語の原文から翻訳しています。編集を提案する。