Pro
ES
Iniciar sesiónCuenta Descargar para Mac
Descargar para Mac

Ayuda / API y agentes

API HTTP para agentes

Este sitio documenta flujos de trabajo y campos seleccionados y compatibles, no la API interna completa.

Usa personajes originales o estilizados, o tu propia imagen con consentimiento documentado. Cualquier representación de otra persona identificable requiere su consentimiento documentado. Cumple la política de uso aceptable en todas las imágenes de referencia, datos de entrenamiento, audio y resultados.

Los agentes externos (Claude Code, Codex, OSS o cualquier cosa que hable HTTP) controlan Phosphene a través de esta API. El chat integrado en el panel se eliminó el 2026-05-15: ya no hay ningún agente incrustado en el panel. Todo lo que hacía el chat lo puede hacer un agente externo mediante estos endpoints.

Herramientas listas para usar sobre esta API: el comando phosphene y un servidor MCP para Claude Code, Codex o cualquier cliente MCP, en agents/. Consulta Herramientas para agentes.

Servidor

  • URL base: http://127.0.0.1:8198 en una instalación normal. 8199 es el puerto del perfil DEV, y todos los ejemplos de esta página lo usan porque es el panel con el que se escribieron. La regla es una línea en el código fuente (mlx_ltx_panel.py:275): DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, que se puede sobrescribir con LTX_PORT. Si una petición de aquí no devuelve nada, casi seguro estás hablando con un puerto en el que no hay ningún panel: prueba con el otro.
  • Proceso: mlx_ltx_panel.py (en la raíz del repositorio)
  • Formato de transmisión: cuerpos POST codificados como formulario; las excepciones con JSON se indican en cada endpoint. Las respuestas son HTTP/1.0 (el valor por defecto de BaseHTTPRequestHandler, nunca sobrescrito), así que la conexión se cierra después de cada petición y no hay keep-alive con el que encadenar peticiones.
  • Autenticación: ninguna; solo escucha en el loopback.

Convenciones

  • Toda respuesta JSON es Content-Type: application/json.
  • Los errores devuelven {"error": "<message>"} con un estado HTTP distinto de 2xx.
  • 451 licence_required (4.19.8). Una petición que descargaría o ejecutaría un modelo cuya licencia pide un «acepto» explícito (Hailuo H3 con la MiniMax H3 Community License, y los modelos no comerciales Ideogram 4, YuE2, FLUX.1 Krea [dev] y Bria FIBO) responde HTTP 451 con {"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"} hasta que esa licencia se acepta una vez en este Mac. Se aplica a /queue/add, /queue/retry, /queue/batch, /image/generate, /h3/turbo/install, /h3/tristep/install, /music/install, /music/cover/install y /music/lora/fetch; un trabajo que llegue de cualquier otra forma falla con la misma frase. Lee los términos con GET /licences y acéptalos con POST /licences/accept (más abajo), o una sola vez en el panel, que muestra la pantalla por sí mismo.
  • El espacio de nombres /agent/* está reservado y eliminado: cualquier ruta bajo /agent/ salvo /agent/image/config devuelve 410 Gone con {"error": "agentic flows removed; see docs/API.md"}. No deben añadirse endpoints nuevos bajo /agent/.

Generación: enviar y gestionar trabajos

POST /queue/add: poner en cola un render de video

Añade un trabajo a la cola del panel. Devuelve de inmediato; el helper lo renderiza de forma asíncrona.

Campos del formulario (todos obligatorios salvo que se indique lo contrario):

CampoTipoNota
modet2v | i2v | extend | keyframe | a2v | v2a | imageTipo de trabajo. v2a (Añadir sonido) es solo de Hailuo H3.
promptstringTexto completo del prompt. Aquí van las palabras de activación de los LoRA.
negative_promptstringOpcional. Solo se respeta donde la pipeline ejecuta guía sin clasificador: high, extend, keyframe, a2v. Las rutas destiladas quick / balanced / standard no tienen rama de guía y lo ignoran (antes incorporaban los términos al prompt, lo que hacía que el modelo los dibujara, #81).
width, heightintAmbos divisibles por 32.
framesintDebe cumplir frames % 8 == 1. 121 = 5 s, 169 = 7 s, 241 = 10 s.
frame_ratefloatPor defecto 24. LTX está entrenado a 24 fps; desviarse degrada la calidad.
character_strengthfloatPor defecto 1.0. La intensidad del LoRA de personaje, de 0 a 2.
seedint o -1-1 = aleatoria.
qualityquick | balanced | standard | highPara trabajo con LoRA de personaje, usa high. balanced envía en silencio los clips de más de 121 fotogramas al transformador destilado Q4, donde los LoRA actuales pierden la identidad.
stage1_steps, stage2_stepsintPipeline HQ de dos etapas. Valores validados por defecto: 10 / 3.
teacache_threshfloatMeseta de aceleración validada en 1.8–2.0. Por debajo de 1.6 no hay aceleración. Más alto = caché más agresiva.
cfg_scalefloatGuía sin clasificador. 3.0 es el valor por defecto validado.
bongmath_max_iterintLímite del bucle interno del sampler. 100 es el máximo de origen.
upscaleoff | fit_720p | fit_1080pPosproceso opcional.
upscale_methodlanczos | pipersrSi upscale != off.
acceloff | (otros modos: consulta el código fuente del panel)Parámetro de aceleración.
enhancetrue | falseSi es true, Gemma reescribe el prompt antes de codificarlo. Pon false cuando el prompt contenga palabras de activación de LoRA: el reescritor puede quitarlas.
hdrtrue | falsePasada HDR con ic-lora.
imagepathSolo I2V. Ruta absoluta a un PNG/JPG de referencia. Obligatorio: desde la v4.6.1, un image omitido o vacío en i2v / i2v_clean_audio se rechaza al iniciar el trabajo con un error legible, en lugar de usar por defecto examples/reference.png, un archivo de demostración que ninguna instalación ha incluido jamás (ese valor por defecto era el fallo de render más extendido de la flota: image not found: <path>, 35 eventos en 22 personas en 14 días). LTX_DEFAULT_IMAGE sigue dando un valor por defecto cuando apunta a un archivo que existe de verdad.
audiopathReferencia de audio opcional.
labelstringEtiqueta opcional de la interfaz para la tarjeta de la cola.
temporal_modenative | fps12_interp24 | windows. windows renderiza más allá de una ventana de 121 fotogramas como una SECUENCIA: un generate y luego un extend por cada ventana posterior, sobre la cola conservada de la anterior (ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), recortada a la duración pedida. Necesita el complemento Q8 y un nivel que permita Extender; si no, se rechaza con una frase. Se guarda en el trabajo como long_mode.
window_promptsArray JSON (o texto separado por saltos de línea) con una línea por ventana; la línea 1 en blanco = el prompt; una línea en blanco posterior mantiene el momento anterior. El prompt de cada ventana posterior es primero su línea, luego la cláusula de continuación y luego Throughout: <window_invariants>.: el contrato de la cadena de H3 y la regla de empezar por el movimiento.
window_invariantsLo que no debe cambiar entre ventanas (quién, dónde, luz, objetivo). Se reinyecta en cada ventana posterior.
lorasarray codificado en JSONConsulta la carga útil de LoRA más abajo.

Hailuo H3 (engine=h3), campos de la 4.19. H3 renderiza t2v, i2v, keyframe, extend, a2v y v2a; cada modo posterior a i2v necesita un indicador en el runner INSTALADO (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), y un trabajo de un modo que el runner no tiene se renderiza en LTX con una frase (Añadir sonido no tiene vía en LTX y se rechaza con la frase de actualización).

CampoTipoNota
h3_quality, h3_lengthstringLa celda. h3_quality=fast_hd = la pasada Rápido de 640×384 + Aumentar resolución y corregir rostro a 1280×768, puestas en cola juntas; Rápido y la corrección son obligatorios.
h3_continuityon | offPor defecto on: una ventana encadenada lleva los últimos 17 fotogramas de la anterior y su sonido (--chain-context-frames 17). off = el traspaso de una sola imagen fija.
start_image, end_image, keyframes_jsonpath / JSONmode=keyframe. En H3 el fotograma inicial es opcional (un fotograma final solo es la tarea de último fotograma de MiniMax); los hitos de keyframes_json caen en su frame_index en la línea de tiempo de 24 fps.
video_path, h3_extend_secondspath / floatmode=extend: cualquier clip, continuado desde sus últimos 17 fotogramas y su sonido; se añaden de 0,5 a 15 s después.
audio, image, frames, audio_start_time, audio_stem_automode=a2v con engine=h3: la pista se mantiene tal cual y la imagen se renderiza sobre ella; frames (24 fps) es la duración, limitada por el audio restante tras audio_start_time y a 30 s; audio_stem_auto=on condiciona con la voz separada y entrega el original.
video_pathpathmode=v2a (Añadir sonido, solo H3): la imagen del clip se mantiene tal cual y solo se genera su sonido; hasta 60 s.
h3_prompt_guards"" | off | all | lista separada por comasQué protecciones del prompt se aplican al texto que codifica el runner (h3_prompt_guards.py): ellipsis, spoken, hands, nouns. Vacío = el conjunto por defecto (ellipsis, spoken, hands; nouns es opcional); off envía el prompt tal cual. Las protecciones aplicadas se registran como h3_prompt_guards_applied; prompt conserva lo que se escribió.

Carga útil de LoRA: el campo loras es un array codificado en JSON de objetos {path, strength}. Apila todos los que necesites: en Hailuo H3, apilar necesita el --lora repetible del motor (/status.h3.loras.max_stack > 1); un paquete más antiguo admite un solo adaptador y el campo h3_lora_slot decide si va a Turbo o al LoRA.

[
  {"path": "<panel-root>/mlx_models/loras/explorertrn_v2.safetensors", "strength": 1.0}
]

Devuelve: {"ok": true, "id": "j-<...>"}: el ID del trabajo para consultar su estado.

Ejemplo:

curl -s -X POST http://127.0.0.1:8199/queue/add \
  --data-urlencode "mode=t2v" \
  --data-urlencode "prompt=Cinematic close-up of bizarrotrn man in a wood-paneled study, golden hour, photorealistic." \
  --data-urlencode "width=1024" --data-urlencode "height=576" \
  --data-urlencode "frames=169" --data-urlencode "steps=8" \
  --data-urlencode "quality=high" --data-urlencode "temporal_mode=native" \
  --data-urlencode "stage1_steps=10" --data-urlencode "stage2_steps=3" \
  --data-urlencode "teacache_thresh=2.0" --data-urlencode "cfg_scale=3.0" \
  --data-urlencode "bongmath_max_iter=100" --data-urlencode "accel=off" \
  --data-urlencode "enhance=false" --data-urlencode "upscale=fit_720p" \
  --data-urlencode "upscale_method=lanczos" --data-urlencode "seed=-1" \

POST /run: alias de /queue/add (comportamiento idéntico).

POST /queue/retry

Vuelve a poner en cola un trabajo del historial con los mismos parámetros. params.open_when_done se fuerza a false (los reintentos se hacen en segundo plano).

CampoTipoNota
idstringID del trabajo de origen.

Devuelve {"ok": true, "id": "<new-id>", "source_id": "<old-id>"}.

POST /queue/remove

Quita un trabajo en cola. (Un trabajo en ejecución no se puede quitar: usa /stop.)

CampoTipoNota
idstringID del trabajo.

Devuelve {"ok": true}.

POST /queue/clear

Vacía la cola. Devuelve {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}. El token deshace ESTE vaciado una vez, durante 60 s (POST /queue/restore con {"token": "<hex>"} devuelve exactamente los trabajos quitados, con sus ids originales, por delante de todo lo que se haya puesto en cola después). Un vaciado posterior lo sustituye; un token caducado o ya usado responde 410.

POST /queue/pause, POST /queue/resume

Pausa o reanuda el despachador de la cola (no afecta a un trabajo que ya se esté ejecutando).

POST /stop

Pide al trabajo en ejecución que se detenga. Devuelve {"ok": true}. Opcional ?id=<job id> (lo que envía el panel): se detiene solo si ese trabajo sigue siendo el que se ejecuta; si no, 409 {"stale": true} y no se detiene nada. /stop/after_part acepta el mismo id.

POST /queue/batch

Envía varios prompts como un lote.

CampoTipoNota
promptsstringPrompts separados por saltos de línea.
(más todos los campos estándar de /queue/add, aplicados a cada fila)

Estado: consultar el estado de los trabajos

One Shot: su propia puerta, POST /oneshot (2026-09-08)

One Shot es una pestaña de flujo de trabajo y también una API de primera clase. Un script envía el mismo documento que envía la pestaña (un único objeto JSON) y recibe de vuelta el trabajo en cola:

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"}}
CampoTipoPor defectoSignificado
promptstrobligatorioLa toma entera, una sola vez: quién, dónde, la hora del día y el tiempo, el sonido. Sin beats, lo lleva cada cinco segundos.
secondsint60Uno de 30 / 45 / 60 / 90 / 120. Cualquier otro valor se rechaza, nunca se redondea (un 75 se renderizaba antes como un solo clip).
engineltx / h3ltxLTX renderiza partes de 10 s (rostros, voces, diálogo); H3 renderiza partes de 15 s (movimiento, paisajes). H3 se rechaza si no está instalado.
qualitystrel del motor por defectoLTX: quick / balanced / standard / high; con un personaje: draft / pro / high / high_720p; H3: draft / standard / high / native.
beatslista o texto con saltos de líneaningunoUna línea por cada cinco segundos. Una línea en blanco mantiene ese momento; las líneas de más se descartan. Ausente = el prompt es cada beat.
camerastr""Un movimiento para toda la toma, con su dirección y velocidad; se aplica a todas las partes (take_camera).
imagepathningunoUn fotograma inicial que ya esté en este Mac: súbelo antes con POST /upload (campo image) y pasa el path devuelto. Hace que la primera parte sea i2v.
character_idstrningunoUn personaje entrenado (solo LTX). Pone la calidad en pro por defecto, la exportación en 720p Sharp y handoff en speech. character_strength es opcional.
handofflast / speechlast (speech con un personaje)Dónde traspasa una parte: su último fotograma, o un fotograma hablando con la última palabra pasada a la parte siguiente (consulta el contrato de la toma más abajo).
light_lock / retakeon/offonLa frase de continuidad en cada beat; una repetición de toma por deriva en cada parte.
seed, label, no_music, turbo (H3), upscale, upscale_methodIgual que en /queue/add.

GET /oneshot/options: lo que puede hacer este 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}: el planificador de Storyboard escribe un beat por cada cinco segundos a partir del prompt (bloques de 20 a 40 s): {ok, beats:[…]}. GET /oneshot/status: current (id, label, part, parts, lipsync por parte, drift, handoff), queued, recent y las propias líneas de log de la toma.

Por debajo, cada One Shot es el contrato de toma que sigue: POST /oneshot traslada el documento al formulario de make_job, así que la pestaña, la API y /queue/add renderizan exactamente el mismo trabajo.

Una toma: take_seconds + beats en POST /queue/add

Un clip más largo que una sola pasada, en cualquiera de los dos motores. take_seconds es uno de 30 / 45 / 60 / 90 / 120; beats es una lista JSON (o texto con saltos de línea) con un prompt por cada cinco segundos: un beat en blanco mantiene el momento anterior y los sobrantes se descartan. Ningún beat (el campo ausente, vacío o con solo líneas en blanco) significa que el prompt es cada beat: la toma es el prompt sostenido durante toda la toma. Antes de la 4.12.1 ese caso renderizaba cada ventana como la frase de mantenimiento: una toma sobre nada. La toma prevalece sobre el propio campo de duración del motor. En AMBOS motores se renderiza como PARTES encadenadas por traspaso del último fotograma: run_take_job_inner ejecuta un render ordinario por parte, cada uno empezando desde el último fotograma del anterior (i2v, anclado), oculta las partes de la galería y las une en <name>_take<seconds>s.mp4:

motorpartequé hace make_jobworker
ltx10 s = dos beats = 241 fotogramas (una toma de 45 s termina en una parte de un beat de 121 fotogramas)frames = 241, temporal_mode = native (una toma nunca es la cadena de ventanas, sea lo que sea lo que envíe el formulario)un render LTX ordinario por parte a través de run_job_inner: la parte 1 es t2v, o i2v desde el propio image del trabajo cuando entró como i2v; cada parte posterior es i2v desde el último fotograma de la anterior con i2v_reference_mode = anchor. Cualquier calidad; el paquete Q8 solo hace falta con una calidad HQ, igual que en un clip suelto
h315 s = tres beatsh3_length=15s, h3_chain_prompts = los beats de la primera parteun render H3 ordinario por parte (--first-frame desde el último fotograma anterior)

Dos campos opcionales, ambos on por defecto:

campooff significa
take_light_lockla frase de continuidad (take_light_lock(): “it is still night…”) NO se añade a los beats; take.light_lock es "" y un beat en blanco se mantiene solo con la frase de mantenimiento
take_retakeuna parte cuya luz se desvía más allá de TAKE_DRIFT_MAX se conserva tal como se renderizó en lugar de repetirse una vez con una semilla nueva; take.retake es false
take_cameraopcional, texto libre, un movimiento para TODA la toma (“a slow, steady clockwise arc around the table at eye level, wide to close”). take_camera_lock() lo pone primero en el prompt de la parte 1 (“Camera: …; one steady move at one speed, never stops, never changes direction”) y, en cada parte posterior, una frase que dice que la cámara ya se mueve así y continúa en la misma dirección a la misma velocidad: el traspaso ancla la imagen entre partes, no el movimiento, y la costura se veía como una cámara que cambiaba de dirección o se paraba y volvía a arrancar en cada unión. Si se deja en blanco, las partes posteriores siguen recibiendo la frase genérica de continuidad. Se registra como take.camera
take_handofflast (por defecto) o speech. Con speech el runner corta todas las partes menos la última en un fotograma HABLANDO: take_handoff_points() encuentra dónde termina la frase (RMS del audio), detiene la imagen TAKE_TALKING_BACK = 0.2 s antes (la boca aún en mitad de la palabra: el único ancla medido que lleva la voz a la boca de la parte siguiente: +0.54 / +0.47 frente a −0.15…−0.01 con la boca cerrada), conserva el sonido hasta el final de la frase más su caída de 0.4 s, y mezcla esa cola (part{k}_tail.wav, amix normalize=0) sobre el inicio de la parte siguiente (part{k+1}_lead.mp4): un corte en J, para que la última palabra se oiga entera. Escribe el primer beat de cada parte para ABRIR EN SILENCIO y que la cola tenga espacio. La cola silenciosa tras cada frase se descarta, así que la toma dura menos que su duración nominal; la última parte no se recorta. Cada parte hablada se puntúa con take_lipsync_score() y se repite hasta TAKE_LIPSYNC_RETAKES = 2 veces con semillas nuevas (ids -pNl, -pNl2) cuando queda por debajo de TAKE_LIPSYNC_MIN = 0.20; se conserva el mejor clip y su puntuación se registra en job["take_lipsync"]. Se registra como take.handoff

params.take en el trabajo: {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}; frames es la toma entera (seconds·24+1 en LTX), part_frames una parte completa. El sidecar del resultado lleva take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake} con parts los archivos de parte ocultos, y image solo cuando la toma se abrió con el propio ancla del usuario. Cargar parámetros restaura una toma como una toma.

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 es el número de partes en ambos motores. Los minutos son partes × el precio de un clip suelto de una parte según el mismo modelo de coste que cualquier otra estimación (H3: la celda medida de 15 s; LTX: la celda 10s de la calidad en LTX_TIERS, y la cola de un beat en su celda 5s); null donde este Mac no tiene cifra. needs_q8 es siempre false ahora: una toma LTX se renderiza en lo que sea que renderice la calidad elegida.

GET /status

Cada fila de outputs[] lleva q: las palabras de búsqueda del resultado, en minúsculas, construidas a partir de su sidecar en la pasada de listado que ya lo lee: prompt, etiqueta, modo, calidad, motor, personaje, semilla, WxH, Nf, nombres de archivo de los LoRA, el nombre del directorio del modelo, el modo temporal y windows. El cuadro de búsqueda de la galería es una prueba de subcadena sobre name + q; cada palabra escrita tiene que coincidir, y al escribir se cargan los resultados más antiguos para que la búsqueda abarque todo.

Cada fila de video lleva además silent: true cuando el clip no tiene sonido (ninguna pista de audio en la cabecera del mp4, o una pista que nunca supera −80 dB), false con sonido, null mientras aún no se sabe. La lectura de la cabecera es en línea; la comprobación de nivel se ejecuta una vez por archivo en un hilo en segundo plano y se guarda en caché por (mtime, size) en state/output_silence.json, así que una consulta nunca decodifica nada. La tarjeta de la galería y el reproductor ofrecen Añadir sonido en un clip silent cuando /status.h3.video_to_audio es verdadero.

Devuelve el estado completo del panel.

{
  "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...", ... ]
}

Semántica de los campos:

  • deferred_downloads (4.20): { active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. Los paquetes que una instalación nueva puso en cola para después de Start (state/install_deferred.json, escrito por install.js; required_files.json -> install.after_start). state es idle, starting, downloading, waiting (otra descarga ocupa el hueco), waiting_disk (el panel mantiene install.background_floor_gb libres; message dice cuánto liberar), retry_wait, failed o done. Vacío e idle en cualquier instalación que install.js nunca puso en cola: una instalación actualizada no descarga nada. download lleva background: true mientras el descargador ocupa el hueco.
  • current: el trabajo que se está ejecutando (null cuando está inactivo).
  • gpu (4.19.10): { busy, holder, since, outside_queue }: la única puerta de la GPU del panel. holder es "queue" para el trabajo de current, o lo que ocupa la GPU fuera de la cola: "image" (un render de Image Studio), "character_sheet", "enhance" (Mejorar prompt), "lyrics", "update" (el script posterior a la actualización). Un cliente que no deba interrumpir el trabajo (detener o actualizar el panel) espera a que current sea null, a que la cola esté en pausa o vacía, Y a que gpu.busy sea false.
  • app_models (solo la app para Mac): la descarga de modelos propia de la app: { state, packs, active, locked, done_bytes, total_bytes }. locked (4.19.10) es verdadero mientras la app mantiene su bloqueo de descarga (<Phosphene home>/.locks/models.lock); entonces el panel no ofrece Download para esos paquetes y rechaza uno con 409 app_downloading. Un segundo scripts/fetch_pack_release.py sobre una carpeta de paquete que ya se está escribiendo se detiene sin tocar nada con código de salida 75.
  • queue: los trabajos en espera, en orden FIFO.
  • history: trabajos completados o fallidos. Cada entrada tiene status, elapsed_sec, output_path, raw_path (nativo antes de aumentar resolución), error.
  • log: búfer rotativo de líneas de stdout del helper (últimos ~50 trabajos).

Bucle de consulta: haz GET a /status cada 15 a 30 s. Un trabajo es terminal cuando su status es uno de done, failed, cancelled, stopped, error. Hasta entonces es queued o running.

stopped significa que el usuario detuvo el render a propósito (consulta POST /stop?mode=early). No es un fallo: no se guardó nada porque el clip nunca se terminó, pero no salió nada mal. stopped_reason lleva la propia frase del runner.

current.progress

Presente mientras un trabajo se ejecuta.

{
  "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 está ausente salvo que la vista previa en vivo esté activada (Configuración → Memoria / velocidad) y el decodificador diminuto esté instalado. meaningful se calcula en el servidor y no debe volver a derivarse: la regla difiere según la pipeline (estimación 6 de 8 en el calendario destilado, cuyas primeras estimaciones siguen siendo esencialmente ruido; estimación 2 en la ruta HQ de dos etapas, que evalúa el denoiser dos veces por paso de la etapa 2). Un cliente que contara estimaciones tendría que saber qué calendario se está ejecutando.

POST /stop?mode=early

Pide al render en ejecución que se detenga en el siguiente límite de avance tocando un centinela ABORT. El runner termina con 75, un código distinto que significa “el usuario detuvo esto”, no un fallo, y el trabajo se resuelve con status: "stopped" sin archivo de salida. Devuelve 404 cuando no se está renderizando nada y 409 cuando el render no tiene vista previa en vivo a través de la cual detenerlo (usa el POST /stop duro, que mata al helper).

Advertencia de codificación: el búfer del registro puede contener caracteres de control literales de prompts con saltos de línea incrustados. Quítalos antes de analizar el JSON:

import re, json
raw = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f]', ' ', raw)
data = json.loads(raw, strict=False)

LoRA

GET /loras

Devuelve {"user": [...], "curated": [...], "loras_dir": "...", ...}. Cada entrada tiene id, name, path, filename, size_bytes, recommended_strength, kind (train_character para los LoRA entrenados mediante el panel; null en otro caso), adapter_verdict (ver más abajo) y metadatos de CivitAI si se conocen.

adapter_verdict: si este archivo puede hacer algo

Un LoRA puede entrenarse hasta el final, escribir un safetensors válido, cargarse sin un aviso y no cambiar nada: los deltas que aprendió son numéricamente demasiado pequeños para mover el modelo. Todas las comprobaciones estructurales pasan, porque todas preguntan si las CLAVES encajan y ninguna pregunta si hay algo dentro (#61, #62).

adapter_verdict (_adapter_verdict) se lee del bloque adapter_strength del sidecar y es uno de:

ValorSignificado
okMedido, y el RMS del delta está en la banda de trabajo.
weakMedido, y los deltas están en WEAK_DELTA_RMS (2.0e-4) o por debajo. El archivo se conserva; el render muy probablemente se verá sin LoRA.
unknownEntrenado por una versión que no medía. No es sinónimo de weak: el silencio no es debilidad, y todo LoRA anterior a la medición se lee así.

Cualquier otra cosa es lo que el entrenador haya llamado, pasado tal cual.

Quien llame debería mostrar weak antes de gastar un render para descubrirlo, y no debería decorar unknown.

GET /train/list lleva el mismo veredicto más adapter_advice: una frase que dice qué hacer al respecto, vacía cuando el veredicto es ok o unknown. Tiene en cuenta el hardware: en un Mac de menos de 64 GB no dice “entrena de nuevo en Alta”, porque esa máquina no puede alcanzar la receta evaluada (consulta la sección de perfiles más abajo). La pestaña Entrenar del panel la muestra como un aviso sobre los chips de personajes entrenados y en la fila del historial del trabajo terminado; un veredicto sobre el que el usuario no puede actuar es una medición, no una respuesta (#62).

GET /hf/loras

Hugging Face como fuente explorable junto a CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1. Phosphene no nombra ninguna organización: la consulta es una búsqueda (vacía = el término de búsqueda por defecto de la vía), un listado de autor, o un repositorio; los resultados se filtran por vía a partir del nombre y las etiquetas del repositorio, y el .safetensors más grande de cada repositorio con su clip de ejemplo pasan a ser un elemento con la misma forma que renderiza la cuadrícula de CivitAI (name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface"). Se guarda en caché diez minutos por vía y consulta.

POST /hf/loras/download

Formulario repo, filename, meta (el JSON del elemento). Descarga mediante huggingface_hub (con el token de HF guardado cuando existe) en el directorio de LoRA de la vía, ejecuta la sonda de formato de H3 y escribe el mismo sidecar que escribe una instalación de CivitAI más source, hf_repo, hf_url. Devuelve { ok, skipped, name, path, sidecar_path, lane, layout, converted }.

GET /civitai/download/state · POST /civitai/download/cancel (4.18.0)

POST /civitai/download acepta un campo de formulario opcional token (8 a 64 caracteres, A-Z a-z 0-9 _ -) elegido por quien llama. Mientras esa descarga se ejecuta, GET /civitai/download/state?token=… devuelve { ok, state: "running"|"cancelled", bytes, total, name } (404 una vez terminada), y POST /civitai/download/cancel con token la detiene en el siguiente bloque de 256 KB: el archivo parcial se elimina, no se registra nada y la propia respuesta de la descarga es { ok: false, cancelled: true, error }. Sin token, una descarga se ejecuta exactamente como antes.

GET /loras/updates

Pregunta a CivitAI si algún LoRA instalado con un civitai_id en su sidecar tiene una versión más reciente (modelVersions[0].id ≠ el civitai_version_id del sidecar). Una petición por cada LoRA así; no se descarga nada.

{ "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": "..." } ] }

Instalar la actualización es el POST /civitai/download normal con ese download_url + meta; el archivo nuevo queda junto al antiguo, que se queda hasta que se elimine.

POST /loras/guide

Formulario: path (un LoRA instalado de GET /loras). El modelo planificador escribe una guía de un párrafo (qué hace el LoRA, cómo usarlo en el prompt, una intensidad de partida, con qué choca) a partir del propio nombre / descripción / palabras de activación del sidecar, y la guarda en el sidecar bajo guide; las filas de GET /loras pasan entonces a llevar guide. Se rechaza con 409 mientras se ejecuta un render (el planificador es un modelo de 12B). Devuelve { ok, guide }.

POST /loras/refresh

Vuelve a escanear mlx_models/loras/. Devuelve la misma carga que /loras.

POST /loras/delete

CampoTipoNota
idstringID del LoRA de /loras.

Elimina el archivo. Devuelve {"ok": true}.

POST /h3/loras/import

multipart/form-data. Instala un adaptador de Hailuo H3 que ya tengas en la propia biblioteca de LoRA de H3 (mlx_models/hailuo-h3/loras/, o donde lo guarde el paquete instalado). A propósito NO es /upload: el material de referencia puede ser cualquier imagen o audio, mientras que un adaptador de H3 tiene que superar el contrato de formato del runner antes de poder aparecer en el selector.

CampoTipoNota
filefileExactamente un .safetensors. El nombre de archivo se reduce a su nombre base y se sanea; no puede coincidir con un archivo que ya esté en la biblioteca.

El cuerpo se transmite en flujo a un directorio temporal oculto, sin almacenarlo en búfer, así que un adaptador de varios gigabytes cuesta alrededor de 1 MiB de memoria residente. Content-Length es obligatorio y está limitado a H3_LORA_UPLOAD_MAX_BYTES (4 GiB).

Qué pasa con el archivo, en orden: se prepara en .import.<pid>.<tid>/<name> → _h3_lora_prepare (a un reempaquetado de ComfyUI se le quita su espacio de nombres diffusion_model. en el sitio, una reescritura solo de la cabecera) → las comprobaciones exclusivas de importación de la carga y de los módulos de destino → os.replace en la biblioteca → JSON sidecar. Un rechazo en cualquier paso no deja nada.

Devuelve:

{
  "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 se escribe en el sidecar y lo recoge el control de intensidad por LoRA del selector. El cargador de H3 aplica B @ A y ningún alpha, así que un adaptador cuyo PEFT alpha/rank no esté ya incorporado a lora_B necesita ese número aquí: se informa de ello, nunca se usa como motivo de rechazo.

Errores: 411 cuando Content-Length falta o es cero, 413 cuando el cuerpo supera el límite, 400 para un archivo incorrecto (extensión equivocada, vacío, nombre duplicado, formato inutilizable, carga malformada, modelo equivocado), 500 en otro caso. Cada mensaje nombra el archivo que eligió el usuario.


Entrenamiento

POST /train/upload

Subida multipart/form-data. Añade una imagen a un conjunto de datos de entrenamiento: esta ruta es de un archivo por petición, no por lotes. Envía las imágenes en un bucle, devolviendo el train_job_id recibido en cada llamada después de la primera para que todo el conjunto acabe en un mismo directorio.

CampoTipoNota
job_idstringOpcional en la PRIMERA llamada (se genera un id nuevo), obligatorio después, para mantener el lote junto. Fíjate en el nombre: job_id, no train_job_id; la respuesta lo devuelve como train_job_id.
filefileExactamente UN PNG/JPG/JPEG/WEBP/BMP, o una descripción .txt.

El cuerpo de la petición está limitado a TRAIN_MAX_BYTES_PER_IMAGE (32 MB). Como ese límite se aplica a la petición completa y la ruta toma un archivo, se rechaza un cuerpo de varios archivos aunque cada imagen individual sea pequeña.

Devuelve el estado del conjunto de datos (train_job_id, número de imágenes, etc.).

POST /train/start

Inicia un entrenamiento de LoRA de personaje. El panel llama a lora_lab.train_character y devuelve los eventos de progreso a STATE['log'].

CampoTipoNota
train_job_idstringDe /train/upload.
triggerstringToken de activación, p. ej. explorertrn. Debe ser compuesto, raro y solo con letras para no chocar con el lenguaje normal: los dígitos se tokenizan como tokens sueltos y muy comunes (mrz07 → m / rz / 0 / 7), y todo activador que ha llevado una identidad aquí era solo de letras; el panel sugiere <3 consonants>trn (mrztrn) y escribe una nota en el registro cuando un activador lleva dígitos (#62). El LoRA del personaje queda en mlx_models/loras/<trigger>_v2.safetensors.
presetquick | medium | highAjuste de hiperparámetros. Valor por defecto cambiado en la v4.6.1: omitirlo ahora da high para train_type=character y quick para train_type=style (TRAIN_DEFAULT_PRESET); antes daba quick para ambos, que es el nivel que nunca ha llevado una identidad (#62). Consulta la tabla de abajo: el número de pasos no es una constante, y en un Mac de menos de 64 GB tampoco lo es nada más.
image_countintConfirmado por el panel a partir de las imágenes subidas.

Anulaciones avanzadas (todas opcionales, recurren a los valores del ajuste):

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

Devuelve {"ok": true, "id": "j-<...>"}. Sigue el progreso con /status (el trabajo de entrenamiento aparece en current y luego en history).

Qué son en realidad los ajustes

Los pasos son derivados, no fijos: steps = epochs × image_count, con un mínimo de 1 y limitados por el max_steps del ajuste (_preset_steps_for, mlx_ltx_panel.py:1629). El límite forma parte del contrato del servidor: una llamada a la API escrita a mano no debe poder poner en cola una ejecución de miles de pasos en un Mac con poca memoria.

En un Mac con 64 GB o más (TRAIN_PRESETS, mlx_ltx_panel.py:1558):

presetepochsrankresolutionmax_steps¿Evaluado en identidad?
quick3085128000No. La etiqueta dice “identidad sin evaluar”.
medium601657612000No. Igual.
high1003251220000Sí: la receta v2 validada (Aria_v2, Bizarro_v2). El valor por defecto, y el que la etiqueta marca como “Recomendado”.

Medido con lora_compat.py: los adaptadores de rango 32 que llevan una identidad están entre 5.4e-04 y 1.6e-03 de delta_rms; dos ejecuciones quick de rango 8 de dos usuarios independientes midieron 1.54e-04 y 1.98e-04, ambas en el umbral WEAK_DELTA_RMS de 2.0e-04 o por debajo (#62).

Así, high con 50 imágenes son 5000 pasos, con 20 imágenes 2000, con 300 imágenes 20000 (limitado). Solo la receta de rango 32 se ha puesto alguna vez ante un ojo humano y se ha calificado de buena.

⚠️ Con menos de 64 GB, cada ajuste es en silencio otro ajuste distinto

_select_train_profile (mlx_ltx_panel.py:1650) se ejecuta una vez al importar y, cuando la RAM total es 0 < ram < 64 GB, modifica TRAIN_PRESETS y TRAIN_STYLE_PRESETS en el sitio. Los nombres no cambian. Los números cambian todos:

presetepochsrankresolutionmax_stepstarget modules
quick24384120conjunto compacto
medium58384300conjunto compacto
high108448500conjunto compacto

make_job replica los mismos límites en el servidor, así que rank / steps / resolution pasados como anulaciones avanzadas también quedan limitados (max_rank 8, max_resolution 448, max_steps 500): no puedes pedir la receta evaluada en este hardware y obtenerla.

Es un compromiso deliberado y su razón es real: el entrenamiento completo de LoRA de LTX a 512 px materializa las activaciones de retropropagación del transformador dev y un Mac de 48 GB cae en swap y nunca termina. Pero hay que tener claro lo que significa: en un Mac de menos de 64 GB no hay ningún ajuste que entrene la receta que alguien haya evaluado. El rango 8 con ≤500 pasos es exactamente el régimen para el que se construyó adapter_verdict, así que espera weak con más frecuencia aquí, y léelo como “este hardware, esta receta” y no como “este conjunto de datos”.

GET /status expone el perfil activo como train_profile (key: compact_training | full_training, más label, ram_gb, max_rank, max_resolution, max_steps, note) y las propias tablas efectivas como train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Léelas antes de fiarte del nombre de un ajuste: son los valores posteriores a la modificación, así que son el único lugar donde se distinguen en tiempo de ejecución las dos tablas anteriores.

El evento de entrenador adapter_strength

No es un evento de analítica: nada de él sale del equipo (consulta docs/ANALYTICS.md para la lista completa de lo que sí sale). Es un evento de progreso en el flujo del subproceso de lora_lab, emitido una vez cuando el entrenador mide el archivo que acaba de escribir (mlx_ltx_panel.py:18005). El panel registra el RMS mediano del delta, el máximo y cuántos módulos aportan, y luego termina el trabajo en estado de ADVERTENCIA en lugar de un simple done cuando el veredicto no es ok. El veredicto se escribe en el sidecar del LoRA como adapter_strength: {"verdict": …} y se lee de vuelta como adapter_verdict en /loras y /characters.

POST /train/install

Cuando el entrenamiento termina bien, el LoRA se copia automáticamente a mlx_models/loras/. Este endpoint sirve para reinstalar de forma explícita o refrescar los metadatos.

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

Eliminan conjuntos de datos de entrenamiento o imágenes de entrenamiento individuales.


Personajes

Descubre y maneja LoRA de personajes entrenados como paquetes.

GET /characters

Devuelve {"characters": [...]}. Cada entrada describe un personaje descubierto en mlx_models/loras/:

CampoTipoNota
id, triggerstringEl mismo valor: el token de activación raro.
name, pronoun, subject_nounstringDel mlx_models/characters/<trigger>/bundle.json opcional.
face_lora_pathstringRuta absoluta a <trigger>_v2.safetensors. Siempre presente.
sample_image_urlstring | nullURL de una imagen de vista previa del conjunto de datos de entrenamiento.
sheet_image_path, sheet_image_urlstring | nullLa hoja de personaje multivista generada (mlx_models/characters/<trigger>/sheet.png), cuando existe. La crea POST /characters/<id>/sheet/generate y la sirve GET /characters/<id>/sheet.

Regla de descubrimiento: <trigger>_v2.safetensors es obligatorio; todo lo demás es opcional.

GET /characters/<id>/preview

Sirve la imagen de muestra de entrenamiento del personaje (PNG/JPEG).

GET /characters/<id>/sheet

Sirve el PNG de la hoja de personaje generada. ?w=<px> devuelve una miniatura en caché (JPEG) por la misma vía de redimensionado que /image?w=. 404 hasta que se genera una hoja.

POST /characters/<id>/sheet/generate

Renderiza una hoja de giro multivista a partir de la imagen de referencia del personaje (primero el avatar del paquete, con la muestra de entrenamiento como alternativa) y la compone en mlx_models/characters/<id>/sheet.png + un sidecar sheet.json (phosphene/character_sheet@1). Síncrono, como /image/generate: quien llama se bloquea durante todo el render; 429 cuando la GPU ya está ocupada por un trabajo de render, entrenamiento o imagen (nunca se pone en cola).

Content-Type: application/json. Todos los campos son opcionales (un cuerpo vacío renderiza la hoja de 3 vistas por defecto):

{
  "engine_override": "qwen_edit_inline",
  "views": ["front", "profile_left", "three_quarter"],
  "wardrobe": "a red flight jacket",
  "seed": -1
}

Solo se aceptan motores que respetan referencias (hidream_*_inline, qwen_edit_*_inline, mock_inline): un motor solo de texto renderizaría a un desconocido. seed >= 0 da a la vista i seed + i, de modo que una hoja entera se reproduce desde un solo número. Cada prompt de vista fija el vestuario a la referencia (“wearing exactly the same clothes as in the reference image”); wardrobe vuelve a indicar el atuendo con palabras además de eso. Las vistas posteriores a la primera también encadenan la primera vista renderizada como segunda referencia: medido sobre una imagen de referencia oscura, los renders laterales en solitario reinventaban el color del pelo según la semilla y la redacción, y un frontal limpio de la misma ejecución vuelve a anclar los atributos que la referencia en bruto no especifica bien. El encuadre de cada vista aún puede desviarse (un sujeto descentrado en una vista): regenera o cambia la semilla. Si tiene éxito, el preview de bundle.json apunta a sheet.png solo si era null: una vista previa curada nunca se pisa.

POST /characters/<id>/generate

Ensambla la receta de producción bloqueada y pone en cola un render T2V. El endpoint acepta prompt_body, framing, duration, quality y un seed entero opcional (-1 significa aleatoria, igual que en /queue/add). Para repeticiones exactas o depuración, quien llama puede pasar full_prompt junto con campos de anulación HQ como stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step y audio_skip_step.


Generación de imágenes (separada del video)

POST /image/generate

Genera imágenes fijas con el motor de imágenes incluido (mflux, BFL, backend de prueba). Se puede elegir por llamada.

Content-Type: application/json. Carga útil:

{
  "prompt": "...",
  "n": 4,
  "engine_override": "mflux",
  "aspect": "1:1",
  "refs": ["/path/to/ref.png"],
  "loras": [{"path": "...", "strength": 1.0}]
}

Consulta image_engine.py para ver las opciones específicas de cada backend.

GET /agent/image/config, POST /agent/image/config

Se mantiene bajo la ruta heredada /agent/ por compatibilidad con el frontend de Image Studio. Lee y escribe la configuración del motor de imágenes (backend por defecto, familia mflux, clave de BFL, etc.). A pesar de la ruta, esta es la configuración del motor de imágenes, NO el agente de chat eliminado.


Storyboard: planificar una película y luego rodarla

Un tablero es una película: un concepto, un reparto, localizaciones y una lista numerada de planos. Cada render que inicia pasa por el mismo contrato make_job → cola que /queue/add; ninguna de estas rutas tiene una vía de ejecución propia. Los tableros viven en state/storyboards/<board_id>/, con storyboard.json escrito de forma atómica: los renders duran horas y un tablero corrupto haría perder toda la ejecución.

Lectura

RutaDevuelve
GET /storyboard/listTodos los tableros, el más reciente primero.
GET /storyboard/get?id=<bid>Un documento de tablero.
GET /storyboard/filmsLas películas ensambladas en el disco: ruta del reproductor, duración, tamaño de imagen, tamaño en disco y cuándo se hizo. list_outputs busca OUTPUT/*.mp4 y nunca desciende, así que sin esto lo único que produce la función es lo único que la app no puede mostrarte.

Interruptores del encargo (en plan)

CampoClave del tableroEfecto
autoautotras el plan: renderiza cada plano, corta y ensambla; no hacen falta más botones
anchor_stillsanchor_stillsantes de renderizar un plano de texto o de personaje, un trabajo de imagen ordinario crea su primer fotograma (still_job_id → still; la hoja del personaje es la referencia mediante qwen_edit_inline cuando existe) y el clip se renderiza como i2v · ancla desde él. Si una imagen fija falla, se establece still_error y el plano se renderiza sin ancla, una vez
long_windowslong_windowsun plano LTX de más de 121 fotogramas se renderiza como temporal_mode=windows (una cadena sobre el transformador dev Q8) con el estilo del tablero y la localización del plano como window_invariants, en lugar de recortarse para que quepa. Extender no puede reinyectar una imagen por ventana, así que un plano largo con ancla está anclado solo por su primera ventana
take_secondstake_secondsuna toma: la película es un solo plano de 30 / 45 / 60 / 90 / 120 s. El planificador escribe un beat por cada 5 s (_sb_take_concept), el tablero conserva UN plano con beats (collapse_take), la tarjeta muestra los beats para editarlos y shot_to_job envía take_seconds + beats: la toma de la pestaña Video, de modo que el render es el mismo por ambas puertas. 0 lo desactiva

Cada campo se modifica solo cuando se envía; un campo ausente conserva el valor del tablero.

POST /storyboard/restill: formulario id, n, pass opcional: olvida la imagen fija del plano n y el clip renderizado a partir de ella, activa anchor_stills si estaba desactivado y renderiza ese plano solo (primero la imagen fija, luego el clip a partir de ella). Los mismos rechazos que render (planificando, ya renderizando).

Escritura: POST /storyboard/<action>

El Director. plan acepta soundtrack (un archivo de audio de este Mac) y bars_per_shot (1/2/4, por defecto 2). Con una pista, el plan es un VIDEO MUSICAL: beat_map() (el mismo ajuste que ejecuta Preparar en el Editor) convierte los tiempos fuertes en huecos de bars_per_shot compases, el número de planos es el número de huecos (los chips de shots ceden el paso; limitado a STORYBOARD_MAX_SHOTS con una nota), el encargo del planificador lleva el bpm, la duración del hueco, una instrucción de arco y dos leyes (empezar cada descripción con el movimiento; sin diálogo, la pista sustituye el sonido de cada clip), y la duration_s de cada plano planificado es su hueco más un margen de un segundo, con slot: {start, end} en el plano. El mapa de la canción decide la frecuencia. song_map() (storyboard_edit) coloca SECCIONES sobre la misma cuadrícula de compases ({start, end, label, energy, brightness} con las etiquetas intro / verse / chorus / bridge / outro según posición, volumen relativo y brillo), y director_pacing() convierte bars_per_shot en un paso por sección: el estribillo corta el doble de a menudo, la intro y el final la mitad. Cada hueco lleva su section; el encargo le dice al planificador qué planos caen en qué sección y lo intensa que es; una pista que el mapa no puede leer se corta con el paso base y el registro lo dice. El tablero registra soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections}, el primer corte automático del Editor usa esa pista cuando Preparar no ha guardado otra en caché (así la película se abre ya cortada al ritmo), y GET /storyboard/edit devuelve sections para que la regla pueda pintar el arco. Una ruta incorrecta da 400 antes de que se ejecute el planificador; se informa de la etapa grid del planificador mientras se lee el ritmo.

Auto. plan acepta auto=1: cuando llega el plan, el render en borrador de cada plano empieza solo (_sb_auto_after_plan, una vez que el planificador ha devuelto la memoria), y cuando el hilo de render termina con todos los planos renderizados se corta la película (_sbe_auto_edit, al ritmo cuando hay pista) y se ensambla con el mismo ensamblador que usa Render (_sb_auto_film); el tablero registra auto_film. Un plano que no se renderizó deja la película en espera y el registro dice cuántos. Detener sigue deteniendo el render; el corte y la película son los normales y pueden volver a cortarse después.

Codificado como formulario salvo que se indique. id es el id del tablero en todos los casos.

AcciónCamposNota
planconcept, id, notes, shots, must, engine, character_id, style, locations, wardrobePlanificar o volver a planificar. 409 mientras el renderizador retiene memoria o el único hueco del planificador está ocupado. shots se respeta o se rechaza, nunca se cambia en silencio por otro número. Una nueva planificación MODIFICA las localizaciones y el vestuario en lugar de sobrescribirlos.
cancelidLibera un hueco del planificador.
saveJSON {id, board}Escribe un tablero editado a mano.
gradeid, n, grade, noteCalifica un plano.
estimateid, pass, onlyEstimación de coste y de tiempo antes de gastar.
renderid, pass, only, out, music, music_modeRueda el tablero.
stopidDetiene el render del tablero en curso.
replan-shotsid, nsVuelve a tirar los planos indicados. Una reparación que rompa una ley se rechaza; las nuevas tiradas se insertan en el plan ACTUAL, no en el original.
add-shotid, path
import-shotsid, from, onlyClips de REFERENCIA de otro tablero. La procedencia (imported_from), las LOCALIZACIONES de origen y el REPARTO de origen viajan con ellos: dejar atrás cualquiera de ellos rompe algo concreto. Se rechaza mientras se renderiza la película de destino.
exportid, auto_edit, music, target_seconds, music_mode
revealid, name, whatMostrar en Finder (macOS).
deleteid

Esquema del tablero: los campos de geografía

Un plano se compone a partir de su localización. Desde el 2026-08-18 una localización también puede mirarse desde más de una dirección, que es lo que hace que un contraplano sea un contraplano y no una segunda localización.

"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"
   …}
]
CampoDóndeReglas
locations[].viewslocalizaciónLista de {id, name, light, description}. Ausente, no [], cuando una localización no tiene ninguna: todos los tableros escritos antes de que existieran las vistas no tienen la clave, y una lista vacía sería una forma nueva sobre la que el validador tendría opiniones sin ningún beneficio. Los ids siguen el mismo juego de caracteres que los ids de localización.
shots[].viewplanoUn id de vista que pertenezca al location_id de ese plano. Una vista en un plano sin localización, o una vista que no es una de las de esa localización, es un error de validación (unknown_view) y falla exactamente igual que una localización desconocida: una vista descartada en silencio compone el contraplano a partir de la descripción de establecimiento, y el coche que la vista existía para sacar del encuadre vuelve a estar en él sin que nadie lo diga.
shots[].eyelineplanoUno de left, right, lens: un hecho sobre el ENCUADRE, no sobre la sala. right = los ojos miran más allá del borde derecho. Cualquier otra cosa es un error de validación (bad_eyeline).

Qué hace el servidor con ellos. shot_scene_text inyecta la descripción de la VISTA cuando un plano nombra una y recurre a la de la localización en otro caso: así que un tablero sin vistas, o un plano que no nombra ninguna, se renderiza exactamente como siempre. eyeline_clause compone "his eyes fixed past the right edge of frame" en el momento del render; lens deliberadamente no produce nada (decirles a estos modelos que miren por el cañón da una interpretación más rígida que el silencio), y existe para que un plano pueda decir que mantiene la mirada a cámara, que es lo que permite a la comprobación de los 180 grados distinguir “mira a cámara” de “nadie escribió nada”.

La regla de los 180 grados se aplica, no se sugiere. Tras planificar, _enforce_eyelines recorre los planos en orden de pantalla y da la vuelta al segundo de cualquier par adyacente que corte entre dos personajes distintos en la misma localización y ambos reclamen el mismo lado, y lo indica en warnings. Lo repara de forma mecánica porque eyeline es un campo discreto con exactamente un complementario: darle la vuelta no puede dañar la prosa de nadie. Las leyes a nivel de prosa reciben en cambio una vuelta al modelo, precisamente porque carecen de esa propiedad.


Editor: la línea de tiempo

El Editor es un flujo de trabajo de primer nivel, no una etapa del storyboard: independiente del motor, se abre sin que un tablero esté renderizándose, y su documento es edit.json bajo el directorio del tablero. Una pista de video, un carril de música. El sonido de cada clip va enlazado por defecto y puede separarse (cortes J/L): eso no es una segunda pista de audio.

Lectura

RutaDevuelve
GET /storyboard/edit?id=<bid>La disposición. En la primera llamada para un tablero ejecuta la edición automática UNA vez, la guarda en el carril automático y la devuelve con generated: true. Todos los GET posteriores son una lectura de archivo. Un edit.json corrupto devuelve 500 con corrupt: true y nunca se sustituye en silencio: eso tiraría la disposición de la que es una copia rota.
GET /storyboard/edit/status?id=<bid>El estado del trabajo de preparación.
GET /storyboard/edit/peaks?id=<bid>La forma de onda. Cientos de KB: pídela una vez, nunca en una consulta periódica. 404 hasta que se ha ejecutado prepare.
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4Un video proxy, servido con soporte de rangos. Safari no permite buscar en un <video> cuyo servidor responde con un 200 normal, lo que anularía toda la razón de ser de los proxies. name debe coincidir con [A-Za-z0-9._-]{1,120}\.mp4: es un nombre base que generó el servidor, así que cualquier otra cosa es un sondeo.
GET /storyboard/edit/uploadsLos videos que el usuario ha traído (panel_uploads/timeline/, el más reciente primero, con un máximo de 200). Se mantienen fuera de OUTPUT a propósito, y por eso necesitan una ruta; las imágenes no, porque van a la biblioteca que la galería ya recorre.
GET /storyboard/edit/sounds?id=<bid>La fuente Sound del panel de medios: {sounds: [{path, name, where, mtime}], dir}: primero la propia carpeta audio/ de la película (where: "film"), luego los archivos de sonido (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) en la raíz de OUTPUT, el más reciente primero, con un máximo de 300. Sin sondeo; la duración se lee cuando se añade un sonido.
GET /storyboard/edit/drafts?id=<bid>{active, drafts: [...], backup}: consulta Borradores más abajo.
GET /storyboard/edit/versions?id=<bid>Solo metadatos: nombre, revisión, cuándo se guardó, número de clips, duración, más keep (= EDIT_HISTORY_KEEP, 50). Los documentos en sí los lee una sola vez restore, bajo petición del usuario. Abrir el panel no debe ser una descarga.

Escritura: POST /storyboard/edit/<sub>

SubCamposNota
prepareid, music, target_secondsCrea proxies y picos. 400 si music no es un archivo.
add-clipid, from, only, path, title, kindkind es video | still | slug: pasarlo es lo que evita que una imagen entre como un video sin fotogramas.
add-soundid, pathUn archivo para una pista de audio: se sondea ({path, title, duration_s, has_video, imported}), 400 cuando no lleva sonido. Un archivo fuera de OUTPUT se enlaza con un enlace duro (se copia entre volúmenes) a la propia carpeta audio/ de la película antes, porque /file solo sirve OUTPUT y un sonido que la vista previa no puede reproducir es medio sonido. El cliente coloca y guarda la tira.
relinkid, onlyVuelve a apuntar los clips a sus archivos terminados (de entrega). Una REPETICIÓN DE TOMA terminada nunca forma parte de ese lote: se ofrece frente a su clip con retake: true en las filas relink de la carga y se adopta clip a clip con only=<clip id>.
cancelidCancela el trabajo de preparación.
autoid, music, target_seconds, min_shot, max_shotVuelve a ejecutar el corte de la máquina. Cae en el carril automático.
saveJSON {id, edit, expect_revision?}Ver más abajo.
draftid, op, slug, name, fromConsulta Borradores.
backupJSON {id, edit}El carril silencioso. Consulta Borradores.
recoveridAdopta la copia de seguridad pendiente.
discard-backupidLa descarta.
versionid, labelPone nombre a una versión. Nombrar no es guardar: ni sube la revisión, ni escribe en edit.json, ni cambia nada de la línea de tiempo, que es justo por lo que es seguro pulsarlo en cualquier momento.
restoreid, fileRestaura una entrada del historial. Se rechaza mientras se renderiza la película.
renderid, out, music, music_mode, format, sizeEnsambla la película. music_mode es replace | under. Entregar como: format es h264 (por defecto, el ajuste del panel) | hevc (VideoToolbox, hvc1, aproximadamente la mitad de bytes) | prores (422 HQ, 10 bits 4:2:2, sonido PCM, un .mov que ningún navegador previsualiza); size es native (como se cortó) | 1080p | 2160p: un solo escalado Lanczos después de las superposiciones, solo hacia arriba, nunca un recorte, omitido cuando el corte ya tiene esa altura. finish es none | grain | heavy_grain: grano de película en movimiento (noise t+u, intensidad 9 / 18) añadido DESPUÉS del tamaño, de modo que una entrega en 4K tenga grano en 4K; un tratamiento de entrega, nunca en el documento, nunca en la vista previa ni en la exportación. Una entrega distinta es un archivo distinto: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. Los hechos llevan deliver: {format, size, finish, label}.
export-nleidXML de FCP7 + JSX de After Effects + medios enlazados.
revealid, whatMostrar en Finder.
generateid, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_ofRueda un clip nuevo directamente en un hueco. Con retake_of=<clip id> es una repetición de toma: el propio plano del clip se CLONA (personaje, referencias, localización, motor) y solo cambian el prompt, la duración y la semilla; el plano nuevo lleva edit_slot.retake_of, y cuando se renderiza el Editor lo ofrece frente a ese clip (“Usarlo” / “Conservar el anterior”). 400 si el clip ya no está en la línea de tiempo.

Semántica de save. revision es el contador del servidor, tomado del disco, nunca de lo que recordó el cliente: una pestaña obsoleta no debe poder hacerlo retroceder. Pasa expect_revision para enterarte de que te adelantaron en lugar de sobrescribir en silencio la otra pestaña: una discrepancia devuelve 409 con conflict: true y la revisión actual. Los errores de validación vuelven todos a la vez (errors: [...], 400) con el archivo del disco intacto, para que un cliente pueda resaltar cada clip erróneo de una pasada en lugar de jugar al topo.

Esquema de edit.json

version es 2 (EDIT_VERSION). La versión 1 se actualiza solo al LEER (migrate_edit): subir la versión sin una actualización en la ruta de lectura no rechazaría las compilaciones antiguas, rechazaría todas las líneas de tiempo que alguien ya tuviera. Una versión del futuro se deja tal cual para que el validador pueda decir lo honesto.

{
  "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[]

CampoNota
id, path, proxypath/proxy son null en un slug.
start, endLa ventana DENTRO del origen.
film_start, film_endEl hueco en la película. Nunca independientes: un clip se reproduce a 1x, así que film_end - film_start == end - start dentro de LENGTH_TOLERANCE (2 ms).
kindvideo (ausente significa video: estamparlo en 400 clips reescribiría todos los edit.json de la máquina para decir lo que su ausencia ya dice), still (se mantiene durante la duración de su hueco; start/end se sintetizan a partir del hueco, duration: null), slug (negro, sin archivo).
sourceauto | human.
lockedbool.
adjust{brightness}, un desfase aditivo eq=brightness de ffmpeg limitado a ±BRIGHTNESS_LIMIT (0.5). Lo neutro es ausente: devolver el control deslizante a cero deja un documento idéntico al de uno que nunca tuvo control deslizante.
frame{zoom, x, y}: un reencuadre. La imagen se amplía zoom veces (1 a 3) y la ventana se centra en la fracción (x, y) del origen. Render: un crop de los propios píxeles del origen antes del ajuste, de modo que una sola cadena es correcta a cualquier tamaño; vista previa: una escala CSS alrededor del mismo ancla (aproximada); exportación: Basic Motion de FCP7 (escala + centro) y escala + posición de AE. Lo neutro es ausente; un slug no tiene nada que reencuadrar.
speedVelocidad de reproducción, SPEED_MIN a SPEED_MAX (0.25 a 4.0), solo video. El hueco es (end - start) / speed, así que la regla de 1x anterior se lee “a su velocidad”. La imagen es setpts, el sonido es atempo encadenado más allá de la ventana de 0.5 a 2.0 de ffmpeg, y la envolvente del sonido (afx) permanece en el reloj REPRODUCIDO de la tira: un fotograma clave a los 2 s sigue estando a los 2 s de la tira tras un cambio de velocidad. Ausente es 1x. Nunca se establece automáticamente.
audioLa edición dividida. Ver más abajo.

clip.audio: el corte J y el corte L

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

Solo clips de video. Los mismos tres números que la imagen, para el SONIDO, de modo que el sonido pueda empezar antes que su imagen (J) o continuar más allá de ella (L), que es como un corte deja de ser una unión a tope.

Ausente significa enlazado, y esa es toda la migración: todo clip escrito alguna vez no tiene clave audio y cada uno de ellos reproduce su propio sonido bajo su propia imagen. EDIT_VERSION no se movió por ello y no se reescribió ningún documento.

La PRESENCIA del campo es el interruptor, no los valores que contiene. No derives “enlazado” de que audio sea igual a la ventana de la imagen: desenlazar escribe la ventana que el clip ya tiene, así que un clip que el usuario acaba de desenlazar se leería como enlazado y se negaría a arrastrarse. El interruptor añade el objeto o lo elimina; nada más decide. normalise_edit redondea el campo pero nunca lo elimina por la misma razón, y lo quita por completo de una imagen fija o un slug.

Las ventanas de audio no pueden solaparse entre sí, igual que las imágenes. Una edición dividida es una unión a tope que cae en otro sitio, no una mezcla: la mezcla es para lo que sirve audio_tracks.

audio_tracks[]: A3, A4, … bajo la música

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

Cualquier número de pistas, cada una con cualquier número de tiras. start/end son los puntos de entrada y salida dentro del archivo (una tira se reproduce a 1x, así que dura end - start en la película); film_start es un segundo de la línea de tiempo, colocado con adelay exactamente igual que el lecho. afx es el mismo objeto de envolvente que llevan el sonido de un clip y el lecho, leído por audio_gain_points; el gain de la tira y el gain de la pista (lineal 0 a 1) lo multiplican: track_strip_gain_points es la única curva que leen la vista previa, el render y la exportación. Ausente es ninguna y lo neutro es ausente: una edición sin pistas no tiene clave, así que se carga, se guarda y se renderiza byte por byte igual; una pista vacía se conserva.

Las tiras de la misma pista no pueden solaparse (audio_track_strips_overlap, un error, TOUCH_TOLERANCE para una unión a tope); las tiras de pistas distintas se solapan y se mezclan. Errores de forma: 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*.

Render: cada tira audible (no silenciada, pista no silenciada, curva no silenciosa) es un -vn -i tras las superposiciones, atrim → volume (su curva, en el reloj de la tira) → aresample → adelay (en muestras) → apad → atrim a la película, y todas se mezclan con amix (normalize=0, duration=first) sobre el sonido de los clips y el lecho bajo el único limitador asoftclip; los hechos de la película llevan sound_strips y mix_peak. Una tira cuyo archivo ya no existe rechaza el render con su ruta y su pista. Exportación: cada pista es su propia pista de audio de FCP7 (clipitems con entrada y salida, fotogramas clave de nivel, <enabled>FALSE</enabled> para un silencio) y cada tira una capa de After Effects llamada <track> · <title>.

transitions[]: un objeto tipado que posee un LÍMITE

"transitions": [{"id": "t1", "after_clip": "<clip id>",
                 "kind": "dissolve" | "fade_black", "duration": 0.5}]

Un fundido encadenado son dos clips en el mismo segundo, y la regla de un clip a la vez del carril de imagen (clips_overlap) es esencial, así que una transición no es un solape. Nombra el clip SALIENTE y se sitúa en el corte entre él y su sucesor en orden de película; una por límite. Los propios film_start/film_end de los clips no se mueven y la película dura exactamente lo que dice la línea de tiempo. El render toma la mitad de la duración como cola extra de más allá del punto de salida del clip saliente y la mitad como cabeza extra de antes del punto de entrada del clip entrante (material de origen que los recortes dejaron atrás), divide la concatenación de imagen en el límite y une las dos tandas con xfade (fade / fadeblack) centrado en el corte. El sonido no necesita nada nuevo: sigue la ruta del carril (_sb_split_audio_plan) exactamente como un corte J.

duration se limita en cada lectura (transition_duration) a min(asked, half the shorter neighbour, 2.0 s) y se ajusta a un número par de fotogramas; el documento conserva el número escrito. Un lado sin material de sobra se rechaza: transition_no_handles nombra el lado y el déficit (“clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there”). Todos los códigos de transición (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) son un error; ninguno está en WARNING_CODES. render rechaza con la misma frase. Una imagen fija y un slug tienen todo el margen que se les pueda pedir.

overlays[]: tarjetas, máscaras y títulos

kind es still | video | text. Un kind explícito prevalece; sin él, decide el sufijo de la ruta (.png/.webp/.tif son imágenes fijas), así que toda superposición escrita antes de que existieran los títulos se lee como antes. Un título es una superposición cuyos píxeles dibuja el render:

{"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 son px en un fotograma de 1080 de alto y escala con la película; x/y son el ancla como fracciones del fotograma; align dice qué borde del texto se sitúa en x. overlay_text() es el único accesor y el estilo se escribe solo donde difiere de los valores por defecto. La fuente es un ARCHIVO (LTX_TITLE_FONT, o si no la primera de TITLE_FONT_CANDIDATES presente en la máquina), verificado antes de construir ffmpeg; si no hay ninguna, render responde 400 con una frase en lugar de una película con un agujero. El ráster es un PNG RGBA del tamaño del fotograma junto a la película (.titles/) que pasa por la misma cadena de superposiciones que una tarjeta subida, así que un título hereda el alfa, los fundidos y el orden z del carril. Los títulos se dibujan en el escenario del DOM en la misma ancla y tamaño; no viajan en la exportación NLE (no tienen ruta).

audio: la banda sonora, como objeto en la línea de tiempo

"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
          "offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
CampoSignificado
offsetEl segundo de la PISTA que suena en el instante 0 de la película. Significa eso desde antes de que existiera el editor, así que todo documento en disco sigue funcionando. Ahora puede ser negativo: la pista empieza -offset segundos dentro de la película, con silencio por delante.
trim_start / trim_endPuntos de entrada y salida DENTRO de la pista, en segundos de pista. Ausente significa sin recortar, que es por lo que un edit.json escrito antes de esto sigue siendo válido: sin campo, sin recorte, el mismo grafo de filtros. Un recorte en el final de la pista o más allá no es un recorte, y normalise_edit lo descarta: un tirador arrastrado de vuelta hasta el final deja un grafo idéntico byte por byte.

music_window(audio, duration=…) es el único lugar donde esto se convierte en los números que necesitan ffmpeg y todos los exportadores: start = max(trim_start, offset) (un recorte de cabeza y un desfase positivo son el mismo gesto desde dos direcciones; gana el que corta más), end o None para “reproducir hasta el final”, y delay/film_start = start - offset. Recortar el borde izquierdo no adelanta el resto de la pista: eso sería un ripple, y la música no hace ripple, así que los segundos que quita un recorte de cabeza vuelven como silencio por delante. Una ventana que los recortes cierran del todo devuelve “sin música” en lugar de un atrim de longitud cero que ffmpeg rechaza.

Borradores, copias de seguridad e historial: tres cosas distintas

Los borradores son variaciones con nombre de la misma película, en drafts/ con un index.json que nombra el activo. Un tablero que solo tiene edit.json tiene exactamente un borrador y siempre lo tuvo; simplemente no tenía nombre para él. load_draft_index lo nombra al salir en lugar de en una pasada de reescritura, para que la actualización no pueda quedarse a medias.

POST /storyboard/edit/draft es una ruta con cinco verbos: son cinco ediciones del mismo puntero activo, y dividirlos serían cinco sitios donde ese puntero podría quedar mal:

opCampos adicionalesEfecto
newname, from=currentBorrador nuevo, vacío o copiado de lo que hay en pantalla. Pasa a ser el activo.
duplicateslug, name
renameslug, name
deleteslug
activateslugGuarda primero el borrador activo actual; nunca lo pierde.

new, duplicate, delete y activate devuelven 409 con busy: true mientras se renderiza esa película: el render está leyendo este documento clip a clip, y cambiar la línea de tiempo debajo de él es el mismo peligro que rechazan import-shots y restore.

La copia de seguridad es nuestra, el guardado es del usuario. POST /storyboard/edit/backup escribe history/backup-<draft>.json y nada más: ni edit.json, ni revisión, ni comprobación de conflicto. El borrador guardado del usuario sigue siendo exactamente lo que guardó por última vez. GET …/drafts la expone como backup y se ofrece, nunca se aplica: recover la adopta, discard-backup la tira.

El historial son dos carriles más un carril de conservación, que se distinguen por el prefijo del nombre de archivo y no abriendo los archivos: una poda que tiene que leer cincuenta documentos para decidir qué borrar falla a mitad con el primero corrupto:

PrefijoQué¿Se poda?
edit-r*Una instantánea automática.Sí, limitada a EDIT_HISTORY_KEEP (50).
save-r*Un guardado que el usuario pulsó.Nunca.
keep-r*Una versión a la que el usuario puso nombre (version).Nunca.

Cada guardado archiva a su predecesor antes de que llegue el documento nuevo (~5 KB cada uno). Que el historial falle nunca debe bloquear un guardado: perder una miga de pan no es nada frente a negarse a conservar la disposición que está en pantalla. origin también se estampa dentro del JSON, para cualquier cosa que lea un archivo por separado.


Gestión de resultados

POST /output/delete

CampoTipoNota
pathstringDebe estar bajo mlx_outputs/.

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

Ocultan o muestran resultados en la galería sin eliminar el archivo.

POST /output/open_folder

Abre en Finder la carpeta que contiene el resultado (Mac).


Licencias de modelos (4.19.8)

GET /licences

Todas las licencias sobre las que pregunta el panel, con el estado de aceptación de este Mac: {"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Claves: h3, ideogram4, yue2, flux1_dev, fibo. La entrada de H3 lleva además territory_notice, excluded_territories, report_line, report_url y credit_line.

POST /licences/accept

Campos de formulario key=<licence key> y accept=1 (la casilla que marcó el usuario). Registra la aceptación de la version actual de la licencia en state/model_licences.json (más un archivo marcador que lee el instalador de H3) y devuelve {"ok": true, "key": ..., "record": {...}, "licence": {...}}. Una versión de licencia modificada vuelve a preguntar. Aceptar en nombre de alguien es aceptar por él: un agente debe mostrar primero al usuario los términos de GET /licences.

Helper y sistema

POST /helper/restart

Reinicia el subproceso helper caliente (se usa tras cambios de ajustes que necesitan un proceso nuevo).

POST /stop_comfy

Apaga un proceso de ComfyUI si Phosphene inició uno.

GET /version/check, POST /version/pull

Autoactualización contra el repositorio de GitHub. /version/pull es solo un git pull: no ejecuta scripts/post_update.sh, así que nada de lo que instala una actualización (paquetes nuevos, modelos) lo instala. Desde la 4.17.4 el panel instala por sí mismo un separador de voz de sincronización labial que falte en el siguiente arranque (consulta /a2v/separator).

POST /engine/repair

Vuelve a ejecutar solo el paso del entorno del motor (scripts/pinokio/ltx_engine_env.sh, el mismo paso que ejecuta Install): reinstala los paquetes de Python del motor de render en su venv, en segundo plano. Sin descargas, sin reconstruir el venv, sin Stop. Responde 202 (iniciado), 200 {nothing_to_do} (el motor está bien) o 409 (hay una reparación en curso, o installing: true: el propio Install de Pinokio todavía está escribiendo el venv). El progreso y el resultado van en GET /status -> engine_env (ok, fault, installing, repair.{state, active, log, error}).

POST /h3/repair

4.19.5. Vuelve a ejecutar solo scripts/pinokio/h3_deps.sh sobre la copia de Hailuo H3: reinstala los paquetes de Python de H3 en su propio venv con el conjunto con el que se probó esta versión (scripts/pinokio/h3_constraints.txt, pasado con -c; uv devuelve al conjunto todo lo que ya estuviera fuera). Sin modelos, sin Stop: el panel nunca importa el venv de H3. Responde 202 (iniciado) o 409 (H3 no está instalado, hay un render de H3 en curso, o ya hay una reparación en curso). El progreso y el resultado van en GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Un render de H3 en un venv fuera del conjunto se rechaza al empezar con H3 cannot start: the Hailuo H3 venv ... y esta reparación en la tarjeta.

Alertas push: el aviso de finalización para una pestaña cerrada

El aviso sonoro y la alerta del navegador en la pestaña (Configuración → Avisos de finalización) necesitan la página abierta. Web Push no: el navegador conserva una suscripción para este origen, el panel firma cada mensaje con un par de claves VAPID que genera una sola vez (state/vapid.json), y el servicio push del navegador despierta /sw.js para mostrar la notificación. Sin relé: el panel envía directamente al proveedor del navegador. Solo se ofrece cuando pywebpush se importa (GET /settings → push_available).

RutaQué
GET /sw.jsel service worker, servido desde el ámbito raíz con Service-Worker-Allowed: /
GET /push/key{ ok, available, public_key, subscriptions }: la clave pública VAPID con la que se suscribe el navegador (503 cuando no está disponible)
POST /push/subscribeformulario subscription = el JSON de PushSubscription; una entrada por endpoint
POST /push/unsubscribeformulario endpoint
POST /push/testenvía “This is what a finished render will say.” a todos los suscriptores; { ok, sent }

Cada trabajo que termina en done o failed envía Phosphene — render done / — a render failed con la etiqueta del trabajo (o los primeros 60 caracteres de su prompt), fuera del bloqueo de la GPU, solo mientras notify_done está activado. Una suscripción que el proveedor informa como desaparecida (404 / 410) se descarta.

POST /settings

CampoTipoNota
(any setting key)stringConsulta state/panel_settings.json para ver el conjunto canónico.
notify_done1/0Avisos de finalización: un aviso sonoro en la pestaña cuando un render termina o falla, y una notificación del navegador cuando la pestaña está en segundo plano y la persona las ha permitido. Activado por defecto; GET /settings lo devuelve.

POST /prompt/enhance

Codificado como formulario. Reescribe un prompt de antemano con Gemma. Lo usan los botones Mejorar del panel (Video y Sincronización labial).

CampoNota
promptobligatorio
modet2v (por defecto), i2v o a2v (Sincronización labial: el prompt auxiliar de i2v más la ley de prompts de sincronización labial)
preserve_tokensLista JSON (o lista separada por comas) de palabras que el resultado debe conservar, con mayúsculas y minúsculas exactas: palabras de activación
translate0 mantiene un prompt en alfabeto no latino en su propio idioma; por defecto se traduce al inglés
loras4.18.0: lista JSON de rutas de LoRA instalados en el render. El panel lee el nombre, las palabras de activación y la guía de cada uno (o, si no, la descripción del creador) de la biblioteca de LoRA (las rutas que no figuran en ella se ignoran) y entrega como mucho 4, acotados, al helper como texto de referencia delimitado. A un LoRA cuyas palabras de activación faltan todas en el resultado se le devuelve su primera palabra de activación al principio.

Devuelve { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] }; { error } con 409 mientras un render ocupa la GPU.

409 needs_pack (4.20). Mejorar se ejecuta sobre Gemma 3, que una instalación nueva descarga en segundo plano después del primer arranque (consulta deferred_downloads en GET /status). Hasta que está en disco, la ruta responde 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state } con pack_state uno de downloading, queued, waiting_disk, missing, y nunca pide al helper que lo cargue. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan y /train/auto-caption responden con la misma forma por la misma razón. POST /models/download repo_key=<needs_pack> lo descarga ahora: mientras el descargador en segundo plano ocupa el hueco de descarga, eso responde 202 { queued: true } y mueve el paquete al principio de la cola ({ already: true } cuando es el que se está descargando).

POST /upload

multipart/form-data. Sube una imagen de referencia para los modos I2V o de fotogramas clave. Devuelve {"path": "<absolute path under panel_uploads/>"}.


Formato JSON del sidecar

Cada clip completado escribe un sidecar en <output>.mp4.json junto al MP4. Esquema (simplificado):

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

Lee los sidecars para comparar ejecuciones sin volver a consultar el panel.


Receta de producción (validada el 2026-05-15)

Para el trabajo de video con LoRA de personaje, la receta fija validada:

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

Tiempo en un M4 Max de 64 GB: ~7:06 por clip de 7 s a 1024×576, ~3:24 a 736×416.


Ejemplo práctico: un agente que lo maneja todo

Envía un clip con dos LoRA, consulta hasta que termine e imprime la ruta del resultado. Solo biblioteca estándar.

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')}")

Ese es el patrón completo: enviar → consultar → leer la ruta del resultado.


Qué se eliminó (y qué lo sustituyó)

La función de flujos con agente dentro del panel (un planificador de planos dirigido por chat) se eliminó el 2026-05-15. La instantánea anterior a la eliminación se conserva en GitHub con la etiqueta pre-agent-removal-2026-05-15.

Todo lo que hacía el chat (planificar varios planos, generar imágenes ancla candidatas, renderizar I2V condicionado a esas anclas, gestionar sesiones) se puede lograr con un agente externo mediante la API documentada arriba. En concreto:

  • Planificación de planos: razonamiento de texto del lado del agente, sin intervención del panel.
  • Generación de anclas: POST /image/generate.
  • De ancla a video: POST /queue/add con mode=i2v e image=<anchor_path>.
  • Estado de la sesión: lo mantiene el agente de forma externa.

Los agentes externos pueden usar los flujos de trabajo documentados mediante esta API.

Fuente: docs/API.md en el repositorio público. Revisado para este sitio web antes de publicarse. Traducido del original en inglés. Sugerir un cambio.