문서 / API와 에이전트
에이전트용 HTTP API
이 웹사이트는 지원되는 일부 워크플로와 필드만 설명하고, 내부 API 전체를 다루지는 않아요.
오리지널 캐릭터나 스타일화된 캐릭터, 또는 문서로 동의를 남긴 본인의 모습을 사용하세요. 다른 식별 가능한 사람을 묘사하려면 그 사람의 문서화된 동의가 필요해요. 모든 참조 이미지, 학습 데이터, 오디오, 결과물은 이용 정책을 따라야 해요.
외부 에이전트(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를 쓰는 이유는 이 예제들을 그 패널에서 작성했기 때문이에요. 규칙은 소스의 한 줄이에요 (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가 없어요. - 인증: 없음. 루프백에만 바인딩돼요.
규칙
- 모든 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/아래의 모든 경로는{"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 | 선택. 분류기 없는 가이던스를 쓰는 파이프라인에서만 적용돼요: high, extend, keyframe, a2v. 증류된 quick / balanced / standard 경로에는 가이던스 분기가 없어서 무시해요(예전에는 그 내용을 프롬프트에 합쳤는데, 모델이 그것들을 그려 버렸어요, #81). |
width, height | int | 둘 다 32로 나누어떨어져야 해요. |
frames | int | frames % 8 == 1을 만족해야 해요. 121 = 5초, 169 = 7초, 241 = 10초. |
frame_rate | float | 기본값 24. LTX는 24fps로 학습되었고, 다르게 하면 품질이 떨어져요. |
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 | 분류기 없는 가이던스. 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프레임 윈도 하나를 넘는 렌더링을 SEQUENCE로 만들어요. 먼저 generate 하나, 이후 윈도마다 직전 윈도의 유지된 끝부분에서 extend 하나씩 실행하고(ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), 요청한 길이로 잘라요. Q8 부가 기능과 Extend를 허용하는 등급이 필요하고, 그렇지 않으면 문장과 함께 거부돼요. 작업에는 long_mode로 저장돼요. | |
window_prompts | JSON 배열(또는 줄바꿈으로 구분) 윈도마다 한 줄. 첫 줄이 비어 있으면 = 프롬프트. 이후 빈 줄은 이전 순간을 유지해요. 이후 각 윈도의 프롬프트는 그 줄이 먼저, 그다음 이어가기 절, 그다음 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와 보정은 강제돼요. |
h3_continuity | on | off | 기본값 on: 이어지는 윈도는 이전 윈도의 마지막 17프레임과 그 소리를 이어받아요(--chain-context-frames 17). off = 이미지 한 장만 넘겨주는 방식. |
start_image, end_image, keyframes_json | path / JSON | mode=keyframe. H3에서는 시작 프레임이 선택이에요(끝 프레임만 있으면 MiniMax의 마지막 프레임 작업이에요). keyframes_json의 비트는 24fps 타임라인의 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(24fps)가 길이이고, 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). 오래된 팩은 어댑터 하나만 받고, 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초 동안 한 번 되돌려요(POST /queue/restore에
{"token": "<hex>"}를 보내면 제거된 작업을 원래 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
여러 프롬프트를 한 배치로 제출해요.
| 필드 | 타입 | 설명 |
|---|---|---|
prompts | string | 줄바꿈으로 구분한 프롬프트. |
(그리고 각 행에 적용되는 /queue/add의 모든 표준 필드) |
상태: 작업 상태 폴링
One Shot, 전용 입구: POST /oneshot (2026-09-08)
One Shot은 워크플로 탭이자 일급 API예요. 스크립트는 탭이 보내는 것과 같은 문서, 즉 JSON 객체 하나를 보내고 대기열에 들어간 작업을 돌려받아요.
curl -s -X POST http://127.0.0.1:8198/oneshot -H 'Content-Type: application/json' -d '{
"prompt": "A red vintage tram rolls through a rain-soaked Lisbon street at night; a woman with a yellow umbrella waits at the stop. The bell rings twice; rain on the roof.",
"seconds": 60,
"engine": "ltx",
"quality": "balanced",
"camera": "a slow, steady push in along the street",
"beats": ["the tram comes round the corner", "", "the woman steps to the kerb"],
"handoff": "last"
}'
# → {"ok": true, "id": "j-…", "plan": {"seconds": 60, "parts": 6, "beats": 12, "engine": "ltx", "handoff": "last", "minutes": 28.2, "eta": "~28 min"}}
| 필드 | 타입 | 기본값 | 의미 |
|---|---|---|---|
prompt | str | 필수 | 샷 전체를 한 번에: 누가, 어디서, 시간대와 날씨, 소리. 비트가 없으면 5초마다 이 프롬프트가 쓰여요. |
seconds | int | 60 | 30 / 45 / 60 / 90 / 120 중 하나. 다른 값은 반올림하지 않고 거부해요(예전에는 75가 클립 하나로 렌더링됐어요). |
engine | ltx / h3 | ltx | LTX는 10초 파트(얼굴, 목소리, 대화)로, H3는 15초 파트(움직임, 풍경)로 렌더링해요. H3가 설치되어 있지 않으면 거부돼요. |
quality | str | 엔진 기본값 | LTX: quick / balanced / standard / high. 캐릭터와 함께일 때: draft / pro / high / high_720p. H3: draft / standard / high / native. |
beats | list or newline text | 없음 | 5초마다 한 줄. 빈 줄은 그 순간을 유지해요. 남는 줄은 버려요. 없으면 프롬프트가 모든 비트예요. |
camera | str | "" | 샷 전체에 쓰는 한 가지 움직임, 방향과 속도. 모든 파트에 이어져요(take_camera). |
image | path | 없음 | 이 Mac에 이미 있는 시작 프레임. 먼저 POST /upload(필드 image)로 업로드하고 돌려받은 path를 넘기세요. 첫 파트가 i2v가 돼요. |
character_id | str | 없음 | 학습된 캐릭터(LTX 전용). 품질 기본값은 pro, 내보내기는 720p Sharp, handoff는 speech가 돼요. character_strength는 선택이에요. |
handoff | last / speech | last(캐릭터가 있으면 speech) | 파트가 다음으로 넘기는 방식: 마지막 프레임, 또는 마지막 단어를 다음 파트로 이어 주는 말하는 프레임(아래 테이크 규약을 보세요). |
light_lock / retake | on/off | on | 모든 비트에 붙는 연속성 문장, 파트마다 한 번의 변화 재촬영. |
seed, label, no_music, turbo (H3), upscale, upscale_method | /queue/add와 같아요. |
GET /oneshot/options: 이 Mac이 할 수 있는 것. seconds, engines.{ltx,h3}(available, part_seconds, qualities), character_qualities, characters(id, name, trigger), planner.
GET /oneshot/estimate?engine=&quality=&seconds=: parts, part_seconds, beats, minutes, eta.
POST /oneshot/plan {prompt, seconds, engine}: 스토리보드 플래너가 프롬프트에서 5초마다 비트 하나를 써요(20~40초 블록). {ok, beats:[…]}.
GET /oneshot/status: current(id, label, part, parts, 파트별 lipsync, drift, handoff), queued, recent, 그리고 테이크 자체의 log 줄.
내부적으로 모든 One Shot은 아래의 테이크 규약이에요. POST /oneshot은 문서를 make_job의 폼에 매핑하므로 탭, API, /queue/add는 정확히 같은 작업을 렌더링해요.
한 테이크: POST /queue/add의 take_seconds + beats
두 엔진 모두에서, 한 번의 패스보다 긴 클립을 만들어요. take_seconds는
30 / 45 / 60 / 90 / 120 중 하나예요. beats는 5초마다 프롬프트 하나를 담은 JSON 리스트(또는 줄바꿈 텍스트)이고,
빈 비트는 이전 순간을 유지하며 남는 비트는 버려져요. 비트가 전혀 없으면(필드가 없거나 비었거나 빈 줄뿐이면)
prompt가 모든 비트예요. 즉 샷은 테이크 전체 동안 이어지는 프롬프트예요. 4.12.1 이전에는 이 경우
모든 윈도가 유지 문장으로 렌더링되었어요. 아무것도 아닌 것에 대한 테이크였죠. 테이크는 엔진 자체의 길이 필드보다 우선해요. 두 엔진 모두
마지막 프레임 인계로 이어진 PARTS로 렌더링돼요. run_take_job_inner가 파트마다
일반 렌더링을 하나씩 실행하고, 각 파트는 앞 파트의 마지막 프레임에서 시작하며
(i2v, 앵커), 파트를 갤러리에서 숨기고 <name>_take<seconds>s.mp4로 이어 붙여요.
| 엔진 | 파트 | make_job이 하는 일 | 워커 |
|---|---|---|---|
ltx | 10초 = 비트 2개 = 241프레임(45초 테이크는 비트 1개, 121프레임 파트로 끝나요) | frames = 241, temporal_mode = native(폼이 무엇을 보냈든 테이크는 윈도 체인이 아니에요) | run_job_inner를 통해 파트마다 일반 LTX 렌더링 하나: 파트 1은 t2v이거나, 작업이 i2v로 들어왔으면 작업 자체의 image로 i2v예요. 이후 모든 파트는 앞 파트의 마지막 프레임에서 i2v_reference_mode = anchor로 i2v예요. 품질은 무엇이든 되고, Q8 팩은 단일 클립처럼 HQ 품질에서만 필요해요 |
h3 | 15초 = 비트 3개 | h3_length=15s, h3_chain_prompts = 첫 파트의 비트 | 파트마다 일반 H3 렌더링 하나(이전 마지막 프레임에서 --first-frame) |
선택 필드 두 개가 있고, 기본값은 모두 on이에요.
| 필드 | off의 의미 |
|---|---|
take_light_lock | 연속성 문장(take_light_lock(), “it is still night…”)을 비트에 붙이지 않아요. take.light_lock은 ""이고, 빈 비트는 유지 문장만으로 유지돼요 |
take_retake | 조명이 TAKE_DRIFT_MAX를 넘어 변한 파트를 새 시드로 한 번 다시 찍지 않고 렌더링된 그대로 둬요. take.retake는 false예요 |
take_camera | 선택, 자유 텍스트, 샷 전체에 쓰는 한 가지 움직임(“a slow, steady clockwise arc around the table at eye level, wide to close”). take_camera_lock()은 이것을 파트 1의 프롬프트 맨 앞에(“Camera: …; one steady move at one speed, never stops, never changes direction”) 넣고, 이후 모든 파트에는 카메라가 이미 그렇게 움직이는 중이고 같은 방향, 같은 속도로 계속된다는 문장을 넣어요. 인계는 파트 사이의 화면을 고정할 뿐 움직임은 고정하지 않아서, 이음새마다 카메라가 방향을 바꾸거나 멈췄다 다시 움직이는 모습이 보였어요. 비워 두면 이후 파트에는 일반 연속성 문장이 들어가요. take.camera로 기록돼요 |
take_handoff | last(기본값) 또는 speech. speech이면 러너가 마지막을 제외한 모든 파트를 말하는 프레임에서 잘라요. take_handoff_points()가 대사가 끝나는 지점을 찾고(오디오 RMS), TAKE_TALKING_BACK = 0.2초 전에 화면을 멈추고(입이 단어 중간인 상태가 다음 파트의 입으로 목소리를 옮기는 것이 측정된 유일한 앵커예요: 입을 다문 경우 −0.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 미만이면 새 시드(id -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는 한 파트 전체예요. 결과물의
사이드카에는 take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake}가 있고, parts는 숨겨진 파트 파일이에요.
image는 테이크가 사용자의 앵커로 시작했을 때만 있어요. 파라미터 불러오기는 테이크를 테이크로 복원해요.
GET /take/estimate
?engine=h3|ltx&quality=<engine quality key>&seconds=<take_seconds> →
{ ok, seconds, beats, parts, beats_per_part, part_frames, engine, frames, minutes, eta, needs_q8 }. parts는 두 엔진 모두 파트 수예요. 분 단위 값은
파트 수 × 다른 모든 예상치와 같은 비용 모델의 파트 하나의 단일 클립 가격이에요
(H3: 측정된 15초 셀. LTX: LTX_TIERS에서 해당 품질의 10s
셀, 비트 하나짜리 끝부분은 5s 셀). 이 Mac에 숫자가 없으면 null이에요. needs_q8은 이제 항상 false예요. LTX 테이크는
선택한 품질이 렌더링되는 곳 어디서든 렌더링돼요.
GET /status
모든 outputs[] 행에는 q가 있어요. 결과물의 검색 가능한 단어를 소문자로 만든 것으로, 이미 사이드카를 읽는 목록 패스에서 만들어요. 프롬프트, 라벨, 모드, 품질, 엔진, 캐릭터, 시드, WxH, Nf, LoRA 파일 이름, 모델 디렉터리 이름, 시간 모드, windows가 들어가요. 갤러리의 검색 상자는 name + q에 대한 부분 문자열 검사이고, 입력한 모든 단어가 일치해야 해요. 입력하면 오래된 결과물도 불러와서 모든 결과물을 대상으로 검색해요.
모든 영상 행에는 silent도 있어요. 클립에 소리가 없으면 true(mp4 헤더에 오디오 트랙이 없거나, 트랙이 −80dB 위로 올라간 적이 없는 경우), 소리가 있으면 false, 아직 알 수 없으면 null이에요. 헤더 읽기는 인라인으로 하고, 레벨 검사는 파일마다 한 번 백그라운드 스레드에서 실행해 (mtime, size)별로 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 }. 새로 설치한 뒤 시작 이후로 대기열에 넣어 둔 팩이에요(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예요. 이때 패널은 해당 팩에 다운로드를 제공하지 않고 409app_downloading으로 거부해요. 이미 쓰고 있는 팩 폴더에 대해scripts/fetch_pack_release.py를 한 번 더 실행하면 건드리지 않고 종료 코드 75로 멈춰요.queue: 대기 중인 작업, FIFO 순서.history: 완료되었거나 실패한 작업. 각 항목에status,elapsed_sec,output_path,raw_path(업스케일 전 네이티브),error가 있어요.log: 헬퍼 stdout 줄의 롤링 버퍼(마지막 약 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번째 추정부터예요(처음 몇 개의 추정은 사실상 노이즈예요). 2단계 HQ 경로에서는 2번째 추정부터예요(2단계 스텝마다 디노이저를 두 번 평가해요). 추정 횟수를 세는 클라이언트는 어떤 스케줄이 실행 중인지 알아야 해요.
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를 줘요. 어떻게 해야 하는지 알려 주는 한 문장이고, 판정이 ok나 unknown이면 비어 있어요. 하드웨어를 고려해서, 64GB 미만 Mac에서는 “High로 다시 학습하세요”라고 하지 않아요. 그 Mac은 검증된 레시피에 도달할 수 없기 때문이에요(아래 프로필 섹션을 보세요). 패널의 학습 탭은 이것을 학습된 캐릭터 칩 위의 배너와 끝난 작업의 기록 행에 표시해요. 사용자가 행동할 수 없는 판정은 답이 아니라 측정값일 뿐이에요(#62).
GET /hf/loras
CivitAI 옆에서 둘러볼 수 있는 소스로서의 Hugging Face예요. ?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").
레인과 쿼리별로 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은 다음 256KB 청크에서 멈춰요. 부분 파일은 삭제되고
아무것도 등록되지 않으며, 다운로드 자체의 응답은 { ok: false, cancelled: true, error }예요.
토큰이 없으면 다운로드는 예전과 똑같이 실행돼요.
GET /loras/updates
사이드카에 civitai_id가 있는 설치된 LoRA 중 더 새로운 버전이 있는지
(modelVersions[0].id ≠ 사이드카의 civitai_version_id) CivitAI에 물어봐요. 해당하는 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
| 필드 | 타입 | 설명 |
|---|---|---|
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 정확히 하나. 파일 이름은 기본 이름으로 줄이고 정리해요. 라이브러리에 이미 있는 파일과 겹치면 안 돼요. |
본문은 버퍼링하지 않고 숨겨진 스테이징 디렉터리로 스트리밍해서, 몇 기가바이트짜리
어댑터도 상주 메모리를 약 1MiB만 써요. Content-Length가 필수이고
H3_LORA_UPLOAD_MAX_BYTES(4GiB)로 제한돼요.
파일에 일어나는 일은 순서대로: .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를 적용하고 알파는 쓰지 않으므로, PEFT
alpha/rank가 lora_B에 이미 합쳐져 있지 않은 어댑터는 여기에 그 숫자가 필요해요. 이것은 보고만 하고,
거부의 근거로는 쓰지 않아요.
오류: Content-Length가 없거나 0이면 411, 본문이 제한을 넘으면 413,
잘못된 파일(잘못된 확장자, 비어 있음, 중복 이름, 사용할 수 없는 레이아웃, 잘못된
페이로드, 다른 모델)이면 400, 그 외에는 500이에요. 모든 메시지에 사용자가 고른 파일 이름이 들어가요.
학습
POST /train/upload
multipart/form-data 업로드. 학습 데이터셋에 이미지 한 장을 추가해요. 이 경로는
요청당 파일 하나이고 배치가 아니에요. 이미지를 반복문으로 보내고, 첫 호출 이후의 모든 호출에는 돌려받은
train_job_id를 그대로 보내서 전체 세트가 한 디렉터리에 모이게 하세요.
| 필드 | 타입 | 설명 |
|---|---|---|
job_id | string | 첫 호출에서는 선택(새 id를 만들어요), 이후에는 배치를 묶기 위해 필수예요. 이름에 주의하세요. job_id이고 train_job_id가 아니에요. 응답은 이것을 train_job_id로 돌려줘요. |
file | file | PNG/JPG/JPEG/WEBP/BMP 정확히 하나, 또는 .txt 캡션. |
요청 본문은 TRAIN_MAX_BYTES_PER_IMAGE(32MB)로 제한돼요. 이 제한은
요청 전체에 걸리고 이 경로는 파일 하나만 받으므로, 이미지가 각각 작아도 여러 파일이 든 본문은 거부돼요.
데이터셋 상태(train_job_id, 이미지 수 등)를 돌려줘요.
POST /train/start
캐릭터 LoRA 학습을 시작해요. 패널은 lora_lab.train_character를 셸로 실행하고 진행 이벤트를 STATE['log']로 스트리밍해요.
| 필드 | 타입 | 설명 |
|---|---|---|
train_job_id | string | /train/upload에서 받은 값. |
trigger | string | 트리거 토큰, 예: explorertrn. 일반 언어와 겹치지 않도록 복합적이고 흔치 않은 알파벳만 쓴 단어여야 해요. 숫자는 매우 흔한 단일 토큰으로 토큰화돼요(mrz07 → m / rz / 0 / 7). 여기서 얼굴 특징을 담아낸 트리거는 모두 알파벳만 썼어요. 패널은 <3 consonants>trn(mrztrn)을 추천하고, 트리거에 숫자가 있으면 로그에 알림을 남겨요(#62). 캐릭터 LoRA는 mlx_models/loras/<trigger>_v2.safetensors에 저장돼요. |
preset | quick | medium | high | 하이퍼파라미터 프리셋. v4.6.1에서 기본값이 바뀌었어요. 생략하면 이제 train_type=character에서는 high, train_type=style에서는 quick이에요(TRAIN_DEFAULT_PRESET). 예전에는 둘 다 quick이었고, 이 등급은 얼굴 특징을 담아낸 적이 한 번도 없어요(#62). 아래 표를 보세요. 스텝 수는 상수가 아니고, 64GB 미만 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에 수천 스텝짜리 실행을 넣을 수 없어야 하기 때문이에요.
메모리 64GB 이상 Mac에서 (TRAIN_PRESETS, mlx_ltx_panel.py:1558):
preset | 에포크 | 랭크 | 해상도 | max_steps | 얼굴 유지 검증? |
|---|---|---|---|---|---|
quick | 30 | 8 | 512 | 8000 | 아니요. 알약에 “identity ungraded”라고 표시돼요. |
medium | 60 | 16 | 576 | 12000 | 아니요. 같아요. |
high | 100 | 32 | 512 | 20000 | 예. 검증된 v2 레시피(Aria_v2, Bizarro_v2)예요. 기본값이고, 알약에 “Recommended”로 표시되는 것이에요. |
lora_compat.py로 측정했어요. 얼굴 특징을 담은 랭크 32 어댑터는 delta_rms가 5.4e-04에서 1.6e-03 사이에 있어요. 서로 다른 두 사용자의 랭크 8 quick 실행은 1.54e-04와 1.98e-04로 측정되어, 둘 다 WEAK_DELTA_RMS 하한인 2.0e-04 이하였어요(#62).
그래서 이미지 50장의 high는 5000스텝, 20장이면 2000스텝, 300장이면 20000스텝(제한 적용)이에요. 사람이 직접 눈으로 보고 좋다고 한 것은 랭크 32 레시피뿐이에요.
⚠️ 64GB 미만에서는 모든 프리셋이 조용히 다른 프리셋이에요
_select_train_profile(mlx_ltx_panel.py:1650)은 import 시 한 번 실행되고, 전체 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). 이 하드웨어에서는 검증된 레시피를 요청해도 얻을 수 없어요.
이것은 의도적인 절충이고 이유도 분명해요. 512px 전체 LTX LoRA 학습은 dev 트랜스포머의 역전파 활성화를 메모리에 올려서, 48GB Mac은 스왑 스래싱에 빠져 끝나지 않아요. 하지만 이것이 무슨 뜻인지는 분명히 해 두세요. 64GB 미만 Mac에는 누군가 검증한 레시피로 학습하는 프리셋이 없어요. 500스텝 이하의 랭크 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이 아니라 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/에서 찾은 캐릭터 하나를 설명해요.
| 필드 | 타입 | 설명 |
|---|---|---|
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를 써서 시트 전체가 숫자 하나로 재현돼요. 모든 뷰 프롬프트는 의상을 참조에 고정해요(“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와 함께 stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step, audio_skip_step 같은 HQ 재정의 필드를 넘길 수 있어요.
이미지 생성 (영상과 별개)
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은 원자적으로 기록돼요. 렌더링은 몇 시간씩 돌아가고, 보드가 깨지면 전체 실행을 잃기 때문이에요.
읽기
| 경로 | 돌려주는 것 |
|---|---|
GET /storyboard/list | 모든 보드, 최신순. |
GET /storyboard/get?id=<bid> | 보드 문서 하나. |
GET /storyboard/films | 디스크에 있는 완성된 영화: 플레이어 경로, 러닝타임, 화면 크기, 디스크 크기, 만든 시각. list_outputs는 OUTPUT/*.mp4를 글로빙하고 하위로 내려가지 않기 때문에, 이것이 없으면 이 기능이 만드는 유일한 결과물을 앱이 보여 줄 수 없어요. |
브리프 스위치 (plan에서)
| 필드 | 보드 키 | 효과 |
|---|---|---|
auto | auto | 계획이 끝난 뒤: 모든 샷을 렌더링하고, 자르고, 조립해요. 버튼을 더 누를 필요가 없어요 |
anchor_stills | anchor_stills | 텍스트/캐릭터 샷을 렌더링하기 전에 일반 이미지 작업이 첫 프레임을 만들고(still_job_id → still. 캐릭터의 시트가 있으면 qwen_edit_inline을 통해 참조가 돼요), 클립은 그것으로 i2v · anchor로 렌더링돼요. 스틸이 실패하면 still_error가 설정되고 샷은 앵커 없이 한 번 렌더링돼요 |
long_windows | long_windows | 121프레임보다 긴 LTX 샷을 맞춰 자르는 대신, 보드의 스타일과 샷의 장소를 window_invariants로 써서 temporal_mode=windows(Q8 dev 트랜스포머 위의 체인)로 렌더링해요. Extend는 윈도마다 이미지를 다시 주입할 수 없으므로, 앵커가 있는 긴 샷은 첫 윈도에서만 앵커돼요 |
take_seconds | take_seconds | 한 테이크: 영화가 30 / 45 / 60 / 90 / 120초짜리 샷 하나예요. 플래너가 5초마다 비트 하나를 쓰고(_sb_take_concept), 보드는 beats가 있는 샷 하나만 유지하며(collapse_take), 카드에 편집할 수 있는 비트가 표시되고, shot_to_job이 take_seconds + beats를 보내요. 영상 탭의 테이크와 같으므로 두 입구에서 렌더링이 같아요. 0이면 꺼져요 |
각 필드는 보낼 때만 패치돼요. 빠진 필드는 보드의 값을 유지해요.
POST /storyboard/restill: 폼 id, n, 선택적 pass. 샷 n의
스틸과 그 스틸로 렌더링된 클립을 지우고, anchor_stills가 꺼져 있었다면 켜고,
그 샷만 렌더링해요(스틸이 먼저, 그다음 그 스틸로 클립). render와
같은 거부 조건(계획 중, 이미 렌더링 중)이 적용돼요.
쓰기: POST /storyboard/<action>
디렉터. plan은 soundtrack(이 Mac의 오디오 파일)과 bars_per_shot(1/2/4, 기본값 2)을 받아요. 트랙이 있으면 계획은 뮤직비디오가 돼요. 편집기의 준비가 실행하는 것과 같은 맞춤인 beat_map()이 다운비트를 bars_per_shot 마디짜리 슬롯으로 바꾸고, 샷 수는 슬롯 수가 되며(shots 칩은 물러나요. STORYBOARD_MAX_SHOTS로 제한되고 메모가 남아요), 플래너의 브리프에는 bpm, 슬롯 길이, 아크 지시, 두 가지 규칙(모든 설명을 움직임으로 시작할 것. 대사는 없음, 트랙이 모든 클립의 소리를 대신해요)이 담기고, 계획된 각 샷의 duration_s는 슬롯에 1초의 핸들을 더한 값이며 샷에는 slot: {start, end}가 붙어요. 곡 지도가 얼마나 자주 자를지 정해요. song_map()(storyboard_edit)은 같은 마디 격자 위에 SECTIONS를 놓고({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예요.
| 액션 | 필드 | 설명 |
|---|---|---|
plan | concept, id, notes, shots, must, engine, character_id, style, locations, wardrobe | 계획 또는 재계획. 렌더러가 메모리를 쥐고 있거나 플래너 슬롯 하나가 사용 중이면 409. shots는 그대로 지켜지거나 거부돼요. 다른 개수로 조용히 바뀌지 않아요. 재계획은 장소와 의상을 덮어쓰지 않고 패치해요. |
cancel | id | 플래너 슬롯을 해제해요. |
save | JSON {id, board} | 직접 편집한 보드를 기록해요. |
grade | id, n, grade, note | 샷 하나를 평가해요. |
estimate | id, pass, only | 비용을 쓰기 전에 비용/소요 시간을 예상해요. |
render | id, pass, only, out, music, music_mode | 보드를 촬영해요. |
stop | id | 실행 중인 보드 렌더링을 중지해요. |
replan-shots | id, ns | 지정한 샷을 다시 뽑아요. 규칙을 깨는 수정은 거부돼요. 다시 뽑은 샷은 원래 계획이 아니라 현재 계획에 끼워 넣어요. |
add-shot | id, path | |
import-shots | id, from, only | 다른 보드의 참조 클립. 출처(imported_from), 원본 장소, 원본 출연진이 함께 따라와요. 하나라도 빠뜨리면 특정한 무언가가 깨져요. 대상 영화가 렌더링 중이면 거부돼요. |
export | id, auto_edit, music, target_seconds, music_mode | |
reveal | id, name, what | Finder에서 보여 줘요(macOS). |
delete | id |
보드 스키마: 지리 필드
샷은 장소를 바탕으로 구성돼요. 2026-08-18부터 장소는 한 방향 이상에서 바라볼 수 있고, 덕분에 리버스 앵글이 두 번째 장소가 아니라 진짜 리버스 앵글이 돼요.
"locations": [
{"id": "carwash", "name": "The car wash", "description": "…",
"views": [ // ABSENT, never [], when there are none
{"id": "establishing", "name": "…",
"light": "camera left", // flips with the camera
"description": "…"}, // self-contained: readable without the floor plan
{"id": "reverse", "name": "…",
"light": "camera right",
"description": "… no car in frame …"} // says what it does NOT hold, in those words
]}
],
"shots": [
{"n": 1, "location_id": "carwash",
"view": "reverse", // must be a view id OF that location
"eyeline": "right", // "left" | "right" | "lens"
…}
]
| 필드 | 위치 | 규칙 |
|---|---|---|
locations[].views | 장소 | {id, name, light, description}의 리스트. 장소에 뷰가 없으면 []가 아니라 없어요. 뷰가 생기기 전에 기록된 모든 보드에는 이 키가 없고, 빈 리스트는 검증기가 아무 이득 없이 의견을 가져야 하는 새 모양이 되기 때문이에요. id는 장소 id와 같은 문자 집합을 따라요. |
shots[].view | 샷 | 그 샷의 location_id에 속한 뷰 id. 장소가 없는 샷에 뷰가 있거나, 그 장소의 뷰가 아닌 뷰이면 검증 오류(unknown_view)이고, 알 수 없는 장소와 똑같이 실패해요. 조용히 버려진 뷰는 리버스 앵글을 establishing 설명으로 구성하고, 뷰가 화면 밖으로 빼기 위해 존재하던 자동차가 아무 말 없이 다시 프레임 안에 들어와요. |
shots[].eyeline | 샷 | left, right, lens 중 하나. 방이 아니라 FRAME에 관한 사실이에요. right = 시선이 오른쪽 가장자리 너머로 향해요. 그 밖의 값은 검증 오류(bad_eyeline)예요. |
서버가 이것으로 하는 일. shot_scene_text는 샷이 뷰를 지정하면 그 VIEW의 설명을 넣고, 아니면 장소의 설명으로 돌아가요. 그래서 뷰가 없는 보드나 뷰를 지정하지 않은 샷은 예전과 똑같이 렌더링돼요. eyeline_clause는 렌더링 시점에 "his eyes fixed past the right edge of frame"을 구성해요. lens는 의도적으로 아무것도 만들지 않아요(이 모델들에게 렌즈를 똑바로 보라고 하면 아무 말 안 한 것보다 어색한 연기가 나와요). 이것이 있는 이유는 샷이 렌즈를 향한다는 것을 말할 수 있게 하기 위해서이고, 그래서 180도 검사가 “카메라를 본다”와 “아무도 쓰지 않았다”를 구별할 수 있어요.
180도 규칙은 제안이 아니라 강제돼요. 계획 후에 _enforce_eyelines가 샷을 화면 순서로 훑으면서, 같은 장소에서 서로 다른 두 캐릭터 사이를 오가고 둘 다 같은 쪽을 가리키는 인접한 두 샷 중 두 번째를 뒤집고, warnings에 그렇게 알려요. eyeline은 보수가 정확히 하나인 이산 필드라서 기계적으로 고칠 수 있고, 뒤집어도 누구의 문장도 해치지 않아요. 문장 수준의 규칙은 바로 그 성질이 없기 때문에 모델 왕복으로 처리해요.
편집기: 타임라인
편집기는 스토리보드의 한 단계가 아니라 최상위 워크플로예요. 엔진과 무관하고, 보드가 렌더링 중이 아니어도 열리며, 문서는 보드 디렉터리 아래의 edit.json이에요. 영상 트랙 하나와 음악 레인 하나가 있어요. 클립별 소리는 기본적으로 연결되어 있고 분리할 수 있어요(J/L 컷). 그것은 두 번째 오디오 트랙이 아니에요.
읽기
| 경로 | 돌려주는 것 |
|---|---|
GET /storyboard/edit?id=<bid> | 배열. 보드에 대한 첫 호출에서는 자동 편집을 한 번 실행하고, 자동 레인에 저장하고, generated: true와 함께 돌려줘요. 이후의 GET은 모두 파일 읽기예요. 손상된 edit.json은 corrupt: true와 함께 500을 돌려주고 조용히 교체되지 않아요. 교체하면 그것이 깨진 사본인 배열 자체를 버리게 되기 때문이에요. |
GET /storyboard/edit/status?id=<bid> | prepare 작업의 상태. |
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>
| 하위 경로 | 필드 | 설명 |
|---|---|---|
prepare | id, music, target_seconds | 프록시와 피크를 만들어요. music이 파일이 아니면 400. |
add-clip | id, from, only, path, title, kind | kind는 video | still | slug예요. 이것을 넘겨야 이미지가 프레임 없는 영상으로 들어가는 일이 없어요. |
add-sound | id, path | 오디오 트랙용 파일 하나. 프로빙해서({path, title, duration_s, has_video, imported}) 소리가 없으면 400. OUTPUT 밖의 파일은 먼저 영화 자체의 audio/ 폴더에 하드링크(볼륨이 다르면 복사)돼요. /file은 OUTPUT만 제공하고, 미리보기가 재생할 수 없는 소리는 반쪽짜리이기 때문이에요. 스트립은 클라이언트가 배치하고 저장해요. |
relink | id, only | 클립을 완성된(최종본) 파일로 다시 연결해요. 완성된 RETAKE는 그 묶음에 포함되지 않아요. 페이로드의 relink 행에서 retake: true로 해당 클립에 대해 제안되고, only=<clip id>로 클립 하나씩 채택돼요. |
cancel | id | prepare 작업을 취소해요. |
auto | id, music, target_seconds, min_shot, max_shot | 기계의 컷을 다시 실행해요. 자동 레인에 저장돼요. |
save | JSON {id, edit, expect_revision?} | 아래를 보세요. |
draft | id, op, slug, name, from | 초안을 보세요. |
backup | JSON {id, edit} | 조용한 레인. 초안을 보세요. |
recover | id | 대기 중인 백업을 채택해요. |
discard-backup | id | 백업을 버려요. |
version | id, label | 버전에 이름을 붙여요. 이름 붙이기는 저장이 아니에요. 리비전이 오르지 않고, edit.json에 쓰지 않으며, 타임라인은 아무것도 바뀌지 않아요. 그래서 언제 눌러도 안전해요. |
restore | id, file | 기록 항목을 복원해요. 영화가 렌더링되는 동안에는 거부돼요. |
render | id, out, music, music_mode, format, size | 영화를 조립해요. music_mode는 replace | under예요. 내보내기 형식: format은 h264(기본값, 패널의 프리셋) | hevc(VideoToolbox, hvc1, 용량이 약 절반) | prores(422 HQ, 10비트 4:2:2, PCM 사운드, 브라우저에서 미리볼 수 없는 .mov)예요. size는 native(컷 그대로) | 1080p | 2160p로, 오버레이 후에 Lanczos 스케일을 한 번 적용하고, 키우기만 하며 크롭은 하지 않고, 컷이 이미 그 높이이면 건너뛰어요. finish는 none | grain | heavy_grain이에요. 움직이는 필름 그레인(noise t+u, 강도 9 / 18)을 크기 조정 이후에 더하기 때문에 4K 결과물에는 4K 그레인이 들어가요. 이것은 내보낼 때만 적용되는 처리이고, 문서나 미리보기나 내보내기 파일에는 들어가지 않아요. 내보내기 설정이 다르면 파일도 달라져요: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. 결과 정보에 deliver: {format, size, finish, label}이 들어 있어요. |
export-nle | id | FCP7 XML + After Effects JSX + 연결된 미디어. |
reveal | id, what | Finder에서 보여 줘요. |
generate | id, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_of | 새 클립을 슬롯에 바로 촬영해요. retake_of=<clip id>를 주면 리테이크예요. 그 클립 자체의 샷이 복제되고(캐릭터, 참조, 장소, 엔진) 프롬프트, 길이, 시드만 바뀌어요. 새 샷에는 edit_slot.retake_of가 붙고, 렌더링이 끝나면 편집기가 그 클립에 대해 제안해요(“Use it” / “Keep the old one”). 클립이 타임라인에 더는 없으면 400이에요. |
save의 의미. revision은 클라이언트가 기억하는 값이 아니라 디스크에서 가져온 서버의 카운터이고, 오래된 탭이 그것을 되돌릴 수 없어야 해요. expect_revision을 넘기면 다른 탭을 조용히 덮어쓰는 대신 내가 추월당했다는 것을 알 수 있어요. 불일치하면 409와 conflict: true 그리고 현재 리비전이 돌아와요. 검증 오류는 한꺼번에 모두(errors: [...], 400) 돌아오고 디스크의 파일은 건드리지 않으므로, 클라이언트가 두더지 잡기를 하지 않고 한 번에 잘못된 클립을 모두 표시할 수 있어요.
edit.json 스키마
version은 2예요(EDIT_VERSION). 버전 1은 READ 시에만 업그레이드돼요(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배속으로 재생되므로 film_end - film_start == end - start가 LENGTH_TOLERANCE(2ms) 이내에서 성립해요. |
kind | video(없으면 영상이에요. 400개의 클립에 이것을 찍으면 기기의 모든 edit.json을 없다는 사실이 이미 말해 주는 것을 적도록 다시 쓰게 돼요), still(슬롯 길이만큼 유지돼요. start/end는 슬롯에서 합성되고 duration: null), slug(검은 화면, 파일 없음). |
source | auto | human. |
locked | bool. |
adjust | {brightness}, ±BRIGHTNESS_LIMIT(0.5)로 제한되는 ffmpeg eq=brightness 가산 오프셋. 중립은 없음으로 표현해요. 슬라이더를 0으로 되돌리면 슬라이더가 없던 문서와 똑같아져요. |
frame | {zoom, x, y}, 리프레임. 화면을 zoom배(1~3)로 확대하고 창이 소스의 비율(x, y) 위치를 중심으로 놓여요. 렌더링: 맞추기 전에 소스 자체 픽셀을 crop하므로 문자열 하나가 모든 크기에서 맞아요. 미리보기: 같은 앵커를 기준으로 한 CSS 스케일(근사치). 내보내기: FCP7 Basic Motion(스케일 + 중심)과 AE 스케일 + 위치. 중립은 없음이고, 슬러그에는 리프레임할 것이 없어요. |
speed | 재생 속도, SPEED_MINSPEED_MAX(0.25(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}
영상 클립에만 있어요. 화면과 같은 세 숫자를 소리에 적용한 것이라서, 소리가 화면보다 먼저 시작하거나(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*.
렌더링: 들리는 모든 스트립(음소거되지 않았고, 트랙도 음소거되지 않았고, 곡선이 무음이 아닌)은 오버레이 이후의 -vn -i 하나이고, atrim → volume(스트립 시계 기준의 곡선) → aresample → adelay(샘플 단위) → apad → 영화에 맞춘 atrim을 거쳐, 모두 하나의 asoftclip 리미터 아래에서 클립의 소리와 베드 위로 amix돼요(normalize=0, duration=first). 영화 정보에는 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는 움직이지 않고 영화는 타임라인이 말하는 길이 그대로예요. 렌더링은 나가는 클립의 아웃 지점 뒤에서 지속 시간의 절반만큼의 꼬리를, 들어오는 클립의 인 지점 앞에서 절반만큼의 머리를(트림으로 남겨진 소스에서) 더 가져오고, 경계에서 화면 concat을 나눈 뒤 컷을 중심으로 xfade(fade / fadeblack)로 두 구간을 이어요. 소리는 새로 필요한 것이 없어요. J컷과 똑같이 레인 경로(_sb_split_audio_plan)를 따라요.
duration은 읽을 때마다 min(asked, half the shorter neighbour, 2.0 s)로 제한되고(transition_duration) 짝수 프레임으로 맞춰지며, 문서는 입력한 숫자를 유지해요. 여유 소스가 없는 쪽이 있으면 거부돼요. 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이고 업로드한 카드와 같은 오버레이 체인을 거치므로, 타이틀은 레인의 알파, 페이드, z-순서를 그대로 물려받아요. 타이틀은 스테이지의 DOM에 같은 앵커와 크기로 그려져요. 경로가 없으므로 NLE 내보내기에는 포함되지 않아요.
audio: 타임라인 위의 객체로서의 사운드트랙
"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
"offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
| 필드 | 의미 |
|---|---|
offset | 영화 시각 0에 재생되는 TRACK의 초. 편집기가 생기기 전부터 이런 의미였기 때문에 디스크의 모든 문서가 계속 작동해요. 이제 음수일 수 있어요. 트랙이 영화 안 -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가 거부하는 길이 0의 atrim 대신 “음악 없음”을 돌려줘요.
초안, 백업, 기록: 서로 다른 세 가지
초안은 같은 영화의 이름 붙은 변형이고, 활성 초안을 가리키는 index.json과 함께 drafts/에 있어요. edit.json만 있는 보드에는 초안이 정확히 하나 있고 항상 그랬어요. 그저 이름이 없었을 뿐이에요. load_draft_index는 다시 쓰기 과정에서가 아니라 읽어 내보내는 중에 이름을 붙여서 업그레이드가 중간에 끊기지 않게 해요.
POST /storyboard/edit/draft는 다섯 개의 동사가 있는 하나의 경로예요. 이것들은 같은 활성 포인터에 대한 다섯 가지 편집이고, 나누면 그 포인터가 틀릴 수 있는 곳이 다섯 군데가 돼요.
op | 추가 필드 | 효과 |
|---|---|---|
new | name, from=current | 비어 있거나 화면에 있는 것을 복사한 새 초안. 활성이 돼요. |
duplicate | slug, name | |
rename | slug, name | |
delete | slug | |
activate | slug | 현재 활성 초안을 먼저 보관해요. 잃어버리는 일이 없어요. |
new, duplicate, delete, activate는 그 영화가 렌더링되는 동안 busy: true와 함께 409를 돌려줘요. 렌더링이 이 문서를 클립 단위로 읽고 있고, 그 아래에서 타임라인을 바꾸는 것은 import-shots와 restore가 거부하는 것과 같은 위험이기 때문이에요.
백업은 우리 몫이고, 저장은 사용자의 몫이에요. POST /storyboard/edit/backup은 history/backup-<draft>.json을 쓰고 그 밖에는 아무것도 쓰지 않아요. edit.json도, 리비전도, 충돌 검사도 없어요. 사용자가 저장한 초안은 마지막으로 저장한 그대로 유지돼요. GET …/drafts가 backup으로 보여 주고 제안만 하며 적용하지 않아요. recover가 채택하고 discard-backup이 버려요.
기록은 두 레인과 보관 레인이고, 파일을 열어 보지 않고 파일 이름의 접두사로 구분해요. 어느 문서를 지울지 정하려고 쉰 개의 문서를 읽어야 하는 정리 작업은 처음으로 손상된 문서에서 중간에 실패해요.
| 접두사 | 내용 | 정리되나요? |
|---|---|---|
edit-r* | 자동 스냅샷. | 예, EDIT_HISTORY_KEEP(50)로 제한돼요. |
save-r* | 사용자가 누른 저장. | 절대 안 돼요. |
keep-r* | 사용자가 이름을 붙인 버전(version). | 절대 안 돼요. |
모든 저장은 새 문서가 들어가기 전에 이전 문서를 보관해요(각각 약 5KB). 기록이 실패해도 저장을 막아서는 안 돼요. 빵 부스러기 하나를 잃는 것은 화면에 있는 배열을 저장하지 않는 것에 비하면 아무것도 아니에요. origin은 JSON 안에도 찍혀서 파일 하나만 읽는 쪽에서도 알 수 있어요.
출력물 관리
POST /output/delete
| 필드 | 타입 | 설명 |
|---|---|---|
path | string | mlx_outputs/ 아래여야 해요. |
POST /output/hide, POST /output/show, POST /output/show_all
파일을 삭제하지 않고 갤러리에서 결과물을 숨기거나 다시 표시해요.
POST /output/open_folder
Finder에서 결과물이 들어 있는 폴더를 열어요(Mac).
모델 라이선스 (4.19.8)
GET /licences
패널이 묻는 모든 라이선스와 이 Mac의 동의 상태:
{"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. 키: h3, ideogram4, yue2,
flux1_dev, fibo. H3 항목에는 territory_notice, excluded_territories, report_line,
report_url, credit_line도 있어요.
POST /licences/accept
폼 필드 key=<licence key>와 accept=1(사용자가 체크한 상자). 라이선스의 현재 version에 대한 동의를
state/model_licences.json에 기록하고(H3 설치기가 읽는 마커 파일도 함께) {"ok": true, "key": ..., "record": {...}, "licence": {...}}를
돌려줘요. 라이선스 버전이 바뀌면 다시 물어봐요. 누군가를 대신해 동의하는 것은 그 사람을 위해 동의하는 것이에요. 에이전트는 먼저 GET /licences의 약관을 사용자에게 보여 줘야 해요.
헬퍼 / 시스템
POST /helper/restart
워밍업된 헬퍼 서브프로세스를 다시 시작해요(새 프로세스가 필요한 설정 변경 후에 사용해요).
POST /stop_comfy
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 패키지를 H3 자체 venv에, 이 릴리스를 테스트한 세트
(scripts/pinokio/h3_constraints.txt, -c로 전달돼요. uv가
그 세트를 벗어난 것을 되돌려요)로 다시 설치해요. 가중치도, 중지도 없어요. 패널은 H3 venv를
import하지 않아요. 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를 import할 수 있을 때만 제공돼요(GET /settings → push_available).
| 경로 | 내용 |
|---|---|
GET /sw.js | 서비스 워커. Service-Worker-Allowed: /와 함께 루트 스코프에서 제공돼요 |
GET /push/key | { ok, available, public_key, subscriptions }, 브라우저가 구독할 때 쓰는 VAPID 공개 키(사용할 수 없으면 503) |
POST /push/subscribe | 폼 subscription = PushSubscription JSON. 엔드포인트마다 항목 하나 |
POST /push/unsubscribe | 폼 endpoint |
POST /push/test | 모든 구독자에게 “This is what a finished render will say.”를 보내요. { ok, sent } |
done 또는 failed로 끝나는 모든 작업은 작업의 라벨(없으면 프롬프트의 첫 60자)과 함께
Phosphene — render done /
— a render failed를 푸시해요. 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 64GB 기준 소요 시간: 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에 제거되었어요. 제거 직전 스냅샷은 GitHub에 태그 pre-agent-removal-2026-05-15로 영구 보존되어 있어요.
채팅이 하던 모든 일, 즉 여러 샷 계획하기, 후보 앵커 이미지 생성하기, 그 앵커에 맞춘 I2V 렌더링하기, 세션 관리하기는 위에 문서화된 API로 외부 에이전트가 할 수 있어요. 구체적으로는 다음과 같아요.
- 샷 계획: 에이전트 쪽의 텍스트 추론이고 패널은 관여하지 않아요.
- 앵커 생성:
POST /image/generate. - 앵커에서 영상으로:
mode=i2v와image=<anchor_path>를 쓴POST /queue/add. - 세션 상태: 에이전트가 외부에서 유지해요.
외부 에이전트는 이 API로 문서화된 워크플로를 사용할 수 있어요.
출처: docs/API.md (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.