Pro
PT
EntrarConta Baixar para Mac
Baixar para Mac

Docs / API e agentes

API HTTP para agentes

Este site documenta fluxos de trabalho e campos selecionados e compatíveis, não a API interna completa.

Use personagens originais ou estilizados, ou a sua própria imagem com consentimento documentado. Qualquer representação de outra pessoa identificável exige o consentimento documentado dela. Siga a Política de Uso Aceitável para todas as imagens de referência, dados de treinamento, áudio e resultados.

Agentes externos (Claude Code, Codex, OSS ou qualquer coisa que fale HTTP) controlam o Phosphene por esta API. O chat dentro do painel foi removido em 2026-05-15: não há mais nenhum agente embutido no painel. Tudo o que o chat fazia pode ser feito por um agente externo através destes endpoints.

Ferramentas prontas em cima desta API: o comando phosphene e um servidor MCP para o Claude Code, o Codex ou qualquer cliente MCP, em agents/. Veja Agent tools.

Servidor

  • URL base: http://127.0.0.1:8198 em uma instalação normal. 8199 é a porta do perfil DEV, e todos os exemplos desta página a usam porque é o painel em que foram escritos. A regra é uma linha no código-fonte (mlx_ltx_panel.py:275): DEFAULT_PORT = 8199 if PROFILE == "dev" else 8198, que pode ser substituída por LTX_PORT. Se uma requisição daqui não retornar nada, você quase certamente está falando com uma porta onde não há painel: tente a outra.
  • Processo: mlx_ltx_panel.py (na raiz do repositório)
  • Formato de transmissão: corpos de POST codificados como formulário; as exceções em JSON são indicadas em cada endpoint. As respostas são HTTP/1.0 (o padrão do BaseHTTPRequestHandler, nunca alterado), então a conexão fecha após cada requisição e não há keep-alive para encadear requisições.
  • Autenticação: nenhuma, o servidor escuta apenas no loopback.

Convenções

  • Toda resposta JSON tem Content-Type: application/json.
  • Os erros retornam {"error": "<message>"} mais um status HTTP diferente de 2xx.
  • 451 licence_required (4.19.8). Uma requisição que baixaria ou executaria um modelo cuja licença pede um “Aceito” explícito (Hailuo H3 (MiniMax H3 Community License) e os modelos não comerciais Ideogram 4, YuE2, FLUX.1 Krea [dev] e Bria FIBO) recebe HTTP 451 com {"ok": false, "code": "licence_required", "licence": "<key>", "error": "...", "url": "<licence>"} até que essa licença seja aceita uma vez neste Mac. Vale para /queue/add, /queue/retry, /queue/batch, /image/generate, /h3/turbo/install, /h3/tristep/install, /music/install, /music/cover/install e /music/lora/fetch; um job que chega por qualquer outro caminho falha com a mesma frase. Leia os termos com GET /licences e aceite com POST /licences/accept (abaixo), ou uma vez no painel, que mostra a tela sozinho.
  • O namespace /agent/* está reservado e removido: qualquer caminho em /agent/, exceto /agent/image/config, retorna 410 Gone com {"error": "agentic flows removed; see docs/API.md"}. Novos endpoints não devem ser adicionados em /agent/.

Geração: enviar e gerenciar jobs

POST /queue/add: colocar uma renderização de vídeo na fila

Adiciona um job à fila do painel. Retorna imediatamente; o auxiliar o renderiza de forma assíncrona.

Campos do formulário (todos obrigatórios, salvo indicação de opcional):

CampoTipoObservação
modet2v | i2v | extend | keyframe | a2v | v2a | imageTipo de job. v2a (Adicionar som) é só do Hailuo H3.
promptstringTexto completo do prompt. As palavras-gatilho dos LoRAs vão aqui.
negative_promptstringOpcional. Respeitado apenas onde o pipeline usa classifier-free guidance: high, extend, keyframe, a2v. Os caminhos destilados quick / balanced / standard não têm ramo de guidance e o ignoram (antes eles incorporavam os termos ao prompt, o que fazia o modelo desenhá-los, #81).
width, heightintAmbos divisíveis por 32.
framesintDeve satisfazer frames % 8 == 1. 121 = 5 s, 169 = 7 s, 241 = 10 s.
frame_ratefloatPadrão 24. O LTX é treinado a 24 fps; qualquer desvio piora a qualidade.
character_strengthfloatPadrão 1.0. A intensidade do LoRA do personagem, de 0 a 2.
seedint or -1-1 = aleatória.
qualityquick | balanced | standard | highPara trabalho com LoRA de personagem, use high. O balanced envia em silêncio clipes com mais de 121 quadros ao transformer destilado Q4, em que os LoRAs atuais perdem a identidade.
stage1_steps, stage2_stepsintPipeline HQ de dois estágios. Padrões validados: 10 / 3.
teacache_threshfloatO platô de ganho de velocidade validado fica em 1.8–2.0. Abaixo de 1.6 não há ganho. Mais alto = cache mais agressivo.
cfg_scalefloatClassifier-free guidance. 3.0 é o padrão validado.
bongmath_max_iterintLimite do laço interno do sampler. 100 é o máximo do upstream.
upscaleoff | fit_720p | fit_1080pPós-processamento opcional.
upscale_methodlanczos | pipersrSe upscale != off.
acceloff | (outros modos: veja o código-fonte do painel)Parâmetro de aceleração.
enhancetrue | falseSe true, o Gemma reescreve o prompt antes de codificar. Use false quando o prompt tiver palavras-gatilho de LoRA, porque o reescritor pode removê-las.
hdrtrue | falsePassagem de ic-lora HDR.
imagepathSó I2V. Caminho absoluto de um PNG/JPG de referência. Obrigatório: desde a v4.6.1, um image omitido ou vazio em i2v / i2v_clean_audio é recusado no início do job com um erro legível, em vez de usar examples/reference.png, um arquivo de demonstração que nenhuma instalação jamais incluiu (esse padrão era a falha de renderização mais comum na frota: image not found: <path>, 35 eventos em 22 pessoas em 14 dias). LTX_DEFAULT_IMAGE ainda fornece um padrão quando aponta para um arquivo que realmente existe.
audiopathReferência de áudio opcional.
labelstringRótulo opcional da interface para o cartão da fila.
temporal_modenative | fps12_interp24 | windows. windows renderiza além de uma janela de 121 quadros como uma SEQUÊNCIA: um generate, depois um extend por janela seguinte sobre a cauda mantida da anterior (ltx_windows.py: stride = window - discard - overlap, count = 1 + ceil((total - window + discard) / stride)), cortada para a duração pedida. Precisa do complemento Q8 e de um nível que permita Estender; do contrário é recusado com uma frase. Guardado no job como long_mode.
window_promptsArray JSON (ou texto separado por quebras de linha) com uma linha por janela; linha 1 em branco = o prompt; uma linha em branco posterior mantém o momento anterior. O prompt de cada janela seguinte é a sua linha PRIMEIRO, depois a cláusula de continuação, depois Throughout: <window_invariants>.: o contrato da cadeia do H3 e a regra de começar pelo movimento.
window_invariantsO que não pode mudar entre janelas (quem, onde, luz, lente). Reinjetado em cada janela seguinte.
lorasarray codificado em JSONVeja o payload de LoRA abaixo.

Hailuo H3 (engine=h3), campos do 4.19. O H3 renderiza t2v, i2v, keyframe, extend, a2v e v2a; cada modo além de i2v precisa de uma flag no runner INSTALADO (/status.h3.keyframes / .extend / .audio_drive / .video_to_audio), e um job para um modo que o runner não tem é renderizado no LTX, com uma frase explicando (Adicionar som não tem faixa no LTX e é recusado com a frase de atualização).

CampoTipoObservação
h3_quality, h3_lengthstringA célula. h3_quality=fast_hd = a passagem Fast de 640×384 + Aumentar resolução e Corrigir rosto até 1280×768, na fila juntas; Fast e a correção são forçados.
h3_continuityon | offPadrão on: uma janela encadeada leva os últimos 17 quadros da anterior e o som deles (--chain-context-frames 17). off = a passagem de uma única imagem.
start_image, end_image, keyframes_jsonpath / JSONmode=keyframe. No H3 o quadro inicial é opcional (um quadro final sozinho é a tarefa de último quadro do MiniMax); os marcos de keyframes_json caem no seu frame_index na linha do tempo de 24 fps.
video_path, h3_extend_secondspath / floatmode=extend: qualquer clipe, continuado a partir dos últimos 17 quadros e do som deles; de 0,5 a 15 s acrescentados depois.
audio, image, frames, audio_start_time, audio_stem_automode=a2v com engine=h3: a faixa é mantida exatamente e a imagem é renderizada sobre ela; frames (24 fps) é a duração, limitada ao áudio restante depois de audio_start_time e a 30 s; audio_stem_auto=on condiciona a partir do vocal separado e entrega o original.
video_pathpathmode=v2a (Adicionar som, só H3): a imagem do clipe é mantida exatamente e apenas o som dele é gerado; até 60 s.
h3_prompt_guards"" | off | all | comma listQuais proteções de prompt atuam sobre o texto que o runner codifica (h3_prompt_guards.py): ellipsis, spoken, hands, nouns. Vazio = o conjunto padrão (ellipsis, spoken, hands; nouns é opcional); off envia o prompt sem alterações. As proteções aplicadas são registradas como h3_prompt_guards_applied; prompt guarda o que foi digitado.

Payload de LoRA: o campo loras é um array codificado em JSON de objetos {path, strength}. Empilhe quantos forem necessários: no Hailuo H3, empilhar exige o --lora repetível do motor (/status.h3.loras.max_stack > 1); um pacote mais antigo aceita um adaptador, e o campo h3_lora_slot decide se ele vai para o Turbo ou para o LoRA.

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

Retorno: {"ok": true, "id": "j-<...>"}, o ID do job para consulta.

Exemplo:

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 (comportamento idêntico).

POST /queue/retry

Recoloca na fila um job do histórico com os mesmos parâmetros. params.open_when_done é forçado a false (as novas tentativas rodam em segundo plano).

CampoTipoObservação
idstringID do job de origem.

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

POST /queue/remove

Remove um job da fila. (Um job em execução não pode ser removido: use /stop.)

CampoTipoObservação
idstringID do job.

Retorna {"ok": true}.

POST /queue/clear

Esvazia a fila. Retorna {"cleared": <count>, "ids": [...], "undo_token": "<hex>"|null}. O token desfaz ESTA limpeza uma vez, por 60 s (POST /queue/restore com {"token": "<hex>"} recoloca exatamente os jobs removidos, com os ids originais, à frente de qualquer coisa colocada na fila desde então). Uma nova limpeza o substitui; um token expirado ou já usado responde 410.

POST /queue/pause, POST /queue/resume

Pausa/retoma o despachante da fila (não afeta um job que já está em execução).

POST /stop

Pede que o job em execução pare. Retorna {"ok": true}. Opcional ?id=<job id> (o que o painel envia): só para se esse job ainda for o que está rodando; caso contrário 409 {"stale": true} e nada é interrompido. /stop/after_part aceita o mesmo id.

POST /queue/batch

Envia vários prompts como um lote.

CampoTipoObservação
promptsstringPrompts separados por quebras de linha.
(plus all the standard /queue/add fields, applied to each row)

Status: consultar o estado dos jobs

One Shot: sua própria porta, POST /oneshot (2026-09-08)

O One Shot é uma aba de fluxo de trabalho e também uma API de primeira classe. Um script envia o mesmo documento que a aba envia (um único objeto JSON) e recebe de volta o job na fila:

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"}}
CampoTipoPadrãoSignificado
promptstrrequiredO plano inteiro, uma vez: quem, onde, a hora do dia e o clima, o som. Sem beats, ele cobre cada cinco segundos.
secondsint60Um entre 30 / 45 / 60 / 90 / 120. Qualquer outro valor é recusado, nunca arredondado (um 75 antes virava um único clipe).
engineltx / h3ltxO LTX renderiza partes de 10 s (rostos, vozes, diálogo); o H3 renderiza partes de 15 s (movimento, paisagens). O H3 é recusado quando não está instalado.
qualitystrpadrão do motorLTX: quick / balanced / standard / high; com um personagem: draft / pro / high / high_720p; H3: draft / standard / high / native.
beatslist or newline textnenhumUma linha a cada cinco segundos. Uma linha em branco mantém aquele momento; linhas extras são descartadas. Ausente = o prompt vale para cada beat.
camerastr""Um movimento para o plano inteiro, com direção e velocidade; levado a cada parte (take_camera).
imagepathnenhumUm quadro inicial que já esteja neste Mac: envie antes com POST /upload (campo image) e passe o path retornado. Faz da primeira parte uma i2v.
character_idstrnenhumUm personagem treinado (só LTX). Define a qualidade como pro, a exportação como 720p nítida e o handoff como speech. character_strength é opcional.
handofflast / speechlast (speech com personagem)Onde uma parte passa o bastão: o último quadro, ou um quadro falando com a última palavra levada para a parte seguinte (veja o contrato do take abaixo).
light_lock / retakeon/offonA frase de continuidade em cada beat; um novo take por desvio em cada parte.
seed, label, no_music, turbo (H3), upscale, upscale_methodComo em /queue/add.

GET /oneshot/options: o que este Mac consegue fazer: 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}: o planejador do Storyboard escreve um beat a cada cinco segundos a partir do prompt (bloqueia por 20 a 40 s): {ok, beats:[…]}. GET /oneshot/status: current (id, label, part, parts, lipsync por parte, drift, handoff), queued, recent e as próprias linhas de log do take.

Por baixo, todo One Shot é o contrato do take abaixo: POST /oneshot mapeia o documento para o formulário do make_job, então a aba, a API e /queue/add renderizam exatamente o mesmo job.

Um take: take_seconds + beats em POST /queue/add

Um clipe mais longo que uma única passagem, em qualquer motor. take_seconds é um entre 30 / 45 / 60 / 90 / 120; beats é uma lista JSON (ou texto com quebras de linha) com um prompt a cada cinco segundos: um beat em branco mantém o momento anterior, os extras são descartados. Nenhum beat (o campo ausente, vazio ou só com linhas em branco) significa que o prompt vale para cada beat: o plano é o prompt sustentado pelo take inteiro. Antes da 4.12.1 esse caso renderizava cada janela como a frase de espera: um take sobre nada. O take se sobrepõe ao campo de duração do próprio motor. Em AMBOS os motores ele é renderizado em PARTES encadeadas por passagem do último quadro: o run_take_job_inner executa uma renderização comum por parte, cada uma começando do último quadro da anterior (i2v, ancorada), esconde as partes da galeria e as junta em <name>_take<seconds>s.mp4:

motorparteo que o make_job fazexecutor
ltx10 s = dois beats = 241 quadros (um take de 45 s termina em uma parte de um beat com 121 quadros)frames = 241, temporal_mode = native (um take nunca é a cadeia de janelas, seja qual for o formulário enviado)uma renderização LTX comum por parte, via run_job_inner: a parte 1 é t2v, ou i2v a partir do image do próprio job quando ele chegou como i2v; cada parte seguinte é i2v a partir do último quadro da anterior com i2v_reference_mode = anchor. Qualquer qualidade; o pacote Q8 só é necessário para uma qualidade HQ, como em um clipe avulso
h315 s = três beatsh3_length=15s, h3_chain_prompts = os beats da primeira parteuma renderização H3 comum por parte (--first-frame a partir do último quadro anterior)

Dois campos opcionais, ambos com padrão on:

campooff significa
take_light_locka frase de continuidade (take_light_lock(): “it is still night…”) NÃO é acrescentada aos beats; take.light_lock fica "" e um beat em branco se mantém só com a frase de espera
take_retakeuma parte cuja luz passa de TAKE_DRIFT_MAX é mantida como renderizada, em vez de ser refeita uma vez com uma seed nova; take.retake é false
take_cameraopcional, texto livre, um movimento para o plano INTEIRO (“a slow, steady clockwise arc around the table at eye level, wide to close”). O take_camera_lock() o coloca no início do prompt da parte 1 (“Camera: …; one steady move at one speed, never stops, never changes direction”) e, em cada parte seguinte, uma frase dizendo que a câmera já se move assim e continua na mesma direção e na mesma velocidade: a passagem ancora a imagem entre as partes, não o movimento, e a emenda aparecia como uma câmera que mudava de direção ou parava e recomeçava a cada junção. Se ficar em branco, as partes seguintes ainda recebem a frase genérica de continuidade. Registrado como take.camera
take_handofflast (padrão) ou speech. Com speech, o runner corta todas as partes, menos a última, em um quadro FALANDO: o take_handoff_points() encontra onde a fala termina (RMS do áudio), para a imagem TAKE_TALKING_BACK = 0,2 s antes (a boca ainda no meio da palavra, a única âncora medida que leva a voz para a boca da parte seguinte: +0,54 / +0,47 contra −0,15…−0,01 com a boca fechada), mantém o som até o fim da fala mais o decaimento de 0,4 s, e mistura essa cauda (part{k}_tail.wav, amix normalize=0) sobre o início da parte seguinte (part{k+1}_lead.mp4), um J-cut, para que a última palavra seja ouvida inteira. Escreva o primeiro beat de cada parte para ABRIR EM SILÊNCIO, de modo que a cauda tenha espaço. A cauda silenciosa depois de cada fala é descartada, então o take fica mais curto que a duração nominal; a última parte não é cortada. Cada parte falada recebe uma nota de take_lipsync_score() e é refeita até TAKE_LIPSYNC_RETAKES = 2 vezes com seeds novas (ids -pNl, -pNl2) quando fica abaixo de TAKE_LIPSYNC_MIN = 0,20; o melhor clipe é mantido e a nota fica registrada em job["take_lipsync"]. Registrado como take.handoff

params.take no job: {seconds, beats, parts, frames, part_frames, beats_per_part, engine, beat_prompts, light_lock, retake}: frames é o take inteiro (seconds·24+1 no LTX), part_frames é uma parte completa. O sidecar do resultado traz take.{seconds, beats, parts, engine, beats_per_part, part_frames, light_lock, retake}, com parts sendo os arquivos das partes ocultas, e image somente quando o take abriu com a âncora do próprio usuário. Carregar parâmetros restaura um take como take.

GET /take/estimate

?engine=h3|ltx&quality=<engine quality key>&seconds=<take_seconds> → { ok, seconds, beats, parts, beats_per_part, part_frames, engine, frames, minutes, eta, needs_q8 }. parts é o número de partes nos dois motores. Os minutos são partes × o preço de clipe avulso de uma parte, do mesmo modelo de custo de todas as outras estimativas (H3: a célula medida de 15 s; LTX: a célula 10s da qualidade em LTX_TIERS, e a cauda de um beat na sua célula 5s); null onde este Mac não tem número. needs_q8 agora é sempre false: um take LTX é renderizado em o que quer que a qualidade escolhida renderize.

GET /status

Toda linha de outputs[] traz q: as palavras pesquisáveis do resultado, em minúsculas, montadas a partir do sidecar na passagem de listagem que já o lê: prompt, label, modo, qualidade, motor, personagem, seed, WxH, Nf, nomes dos arquivos de LoRA, o nome da pasta do modelo, o modo temporal e windows. A caixa de busca da galeria é um teste de substring sobre name + q; todas as palavras digitadas precisam coincidir, e digitar traz os resultados mais antigos, de modo que a busca vale para tudo.

Toda linha de vídeo também traz silent: true quando o clipe não tem som (sem faixa de áudio no cabeçalho do mp4, ou uma faixa que nunca passa de −80 dB), false com som, null enquanto ainda não se sabe. A leitura do cabeçalho é direta; a verificação de nível roda uma vez por arquivo em uma thread em segundo plano e fica em cache por (mtime, size) em state/output_silence.json, então uma consulta nunca decodifica nada. O cartão da galeria e o player oferecem Adicionar som em um clipe silent quando /status.h3.video_to_audio é verdadeiro.

Retorna o estado completo do painel.

{
  "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 dos campos:

  • deferred_downloads (4.20): { active, state, key, message, pending: [{key, name, size_gb, left_gb}], left_gb, finished }. Os pacotes que uma instalação nova deixou para depois do Start (state/install_deferred.json, escrito pelo install.js; required_files.json -> install.after_start). state é idle, starting, downloading, waiting (outro download ocupa a vaga), waiting_disk (o painel mantém install.background_floor_gb livres; message diz quanto liberar), retry_wait, failed ou done. Vazio e idle em qualquer instalação que o install.js nunca colocou na fila: uma instalação atualizada não baixa nada. download traz background: true enquanto o fetcher ocupa a vaga.
  • current: o job em execução no momento (null quando ocioso).
  • gpu (4.19.10): { busy, holder, since, outside_queue }: a única porta de acesso à GPU do painel. holder é "queue" para o job em current, ou o que segura a GPU fora da fila: "image" (uma renderização do Image Studio), "character_sheet", "enhance" (Aprimorar prompt), "lyrics", "update" (o script pós-atualização). Um cliente que não deve interromper o trabalho (parar ou atualizar o painel) espera current ser null, a fila estar pausada ou vazia E gpu.busy ser false.
  • app_models (só no app para Mac): o download de modelos do próprio app: { state, packs, active, locked, done_bytes, total_bytes }. locked (4.19.10) é verdadeiro enquanto o app mantém o bloqueio de download (<Phosphene home>/.locks/models.lock); o painel então não oferece Baixar para esses pacotes e recusa um com 409 app_downloading. Um segundo scripts/fetch_pack_release.py em uma pasta de pacote que já está sendo escrita para sem tocar em nada, com código de saída 75.
  • queue: jobs esperando, em ordem FIFO.
  • history: jobs concluídos/com falha. Cada entrada tem status, elapsed_sec, output_path, raw_path (nativo, antes do upscale), error.
  • log: buffer rotativo das linhas de stdout do auxiliar (últimos ~50 jobs).

Laço de consulta: faça GET em /status a cada 15 a 30 s. Um job é terminal quando o seu status é done, failed, cancelled, stopped ou error. Até lá, ele é queued ou running.

stopped significa que o usuário parou a renderização de propósito (veja POST /stop?mode=early). Não é uma falha: nada foi salvo porque o clipe nunca foi concluído, mas nada deu errado. stopped_reason traz a frase do próprio runner.

current.progress

Presente enquanto um job roda.

{
  "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 fica ausente a menos que a prévia ao vivo esteja ativada (Ajustes → Memória / velocidade) e o decodificador pequeno esteja instalado. meaningful é calculado no servidor e não deve ser rederivado: a regra difere por pipeline (estimativa 6 de 8 no cronograma destilado, cujas primeiras estimativas ainda são essencialmente ruído; estimativa 2 no caminho HQ de dois estágios, que avalia o denoiser duas vezes por passo do estágio 2). Um cliente que contasse estimativas teria de saber qual cronograma está rodando.

POST /stop?mode=early

Pede que a renderização em execução pare na próxima fronteira de forward, criando um arquivo sentinela ABORT. O runner sai com 75, um código distinto que significa “o usuário parou isto”, não uma falha, e o job resolve status: "stopped" sem arquivo de saída. Retorna 404 quando nada está sendo renderizado e 409 quando a renderização não tem prévia ao vivo pela qual parar (use o POST /stop forçado, que mata o auxiliar).

Ressalva de codificação: o buffer de log pode conter caracteres de controle literais vindos de prompts com quebras de linha embutidas. Remova-os antes de interpretar o JSON:

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

LoRAs

GET /loras

Retorna {"user": [...], "curated": [...], "loras_dir": "...", ...}. Cada entrada tem id, name, path, filename, size_bytes, recommended_strength, kind (train_character para LoRAs treinados pelo painel; null nos demais), adapter_verdict (veja abaixo) e metadados do CivitAI, se conhecidos.

adapter_verdict: se este arquivo consegue fazer alguma coisa

Um LoRA pode terminar o treino, gravar um safetensors válido, carregar sem aviso e mudar nada: os deltas que aprendeu são numericamente pequenos demais para mover o modelo. Todas as verificações estruturais passam, porque todas perguntam se as CHAVES encaixam e nenhuma pergunta se há algo dentro delas (#61, #62).

adapter_verdict (_adapter_verdict) é lido do bloco adapter_strength do sidecar e é um destes:

ValorSignificado
okMedido, e o RMS do delta está na faixa de trabalho.
weakMedido, e os deltas estão iguais ou abaixo de WEAK_DELTA_RMS (2.0e-4). O arquivo é mantido; a renderização muito provavelmente vai parecer sem LoRA.
unknownTreinado por uma versão que não media. Não é sinônimo de weak: silêncio não é fraqueza, e todo LoRA anterior à medição aparece assim.

Qualquer outro valor é o que o treinador chamou, repassado sem alterações.

Quem consome deve mostrar weak antes de gastar uma renderização para descobrir isso, e não deve decorar unknown.

GET /train/list traz o mesmo veredito mais adapter_advice: uma frase dizendo o que fazer a respeito, vazia quando o veredito é ok ou unknown. Ela leva o hardware em conta: em um Mac com menos de 64 GB ela não diz “treine de novo em Alta”, porque essa máquina não alcança a receita avaliada (veja a seção de perfil abaixo). A aba Treinar do painel a mostra como um banner acima dos chips de personagens treinados e na linha do histórico do job concluído; um veredito que o usuário não pode agir sobre é uma medição, não uma resposta (#62).

GET /hf/loras

O Hugging Face como fonte navegável ao lado do CivitAI. ?lane=h3|ltx&q=<a name, author:someone, or owner/repo>&refresh=1. O Phosphene não cita nenhuma organização: a consulta é uma busca (vazia = o termo de busca padrão da faixa), uma listagem de autor ou um repositório; os resultados são separados por faixa a partir do nome e das tags do repositório, e o maior .safetensors de cada repositório mais o clipe de exemplo viram um item no mesmo formato que a grade do CivitAI mostra (name, creator, likes, size_kb, preview_url / preview_type, download_url, filename, base_model, hf_url, source: "huggingface"). Guardado em cache por dez minutos por faixa e consulta.

POST /hf/loras/download

Formulário repo, filename, meta (o JSON do item). Baixa pelo huggingface_hub (com o token do HF salvo, quando houver) para o diretório de LoRAs da faixa, executa a sondagem de layout do H3 e grava o mesmo sidecar que uma instalação do CivitAI grava, mais source, hf_repo, hf_url. Retorna { ok, skipped, name, path, sidecar_path, lane, layout, converted }.

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

POST /civitai/download aceita um campo de formulário opcional token (8 a 64 caracteres, A-Z a-z 0-9 _ -) escolhido por quem chama. Enquanto esse download roda, GET /civitai/download/state?token=… retorna { ok, state: "running"|"cancelled", bytes, total, name } (404 depois de concluído), e POST /civitai/download/cancel com token o interrompe no próximo bloco de 256 KB: o arquivo parcial é removido, nada é registrado, e a resposta do próprio download é { ok: false, cancelled: true, error }. Sem um token, o download roda exatamente como antes.

GET /loras/updates

Pergunta ao CivitAI se algum LoRA instalado com civitai_id no sidecar tem uma versão mais nova (modelVersions[0].id ≠ o civitai_version_id do sidecar). Uma requisição por LoRA assim; nada é baixado.

{ "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 a atualização é o POST /civitai/download comum com esse download_url + meta; o novo arquivo fica ao lado do antigo, que permanece até ser excluído.

POST /loras/guide

Formulário: path (um LoRA instalado de GET /loras). O modelo planejador escreve um guia de um parágrafo (o que o LoRA faz, como escrever o prompt, uma intensidade para começar, com o que ele briga) a partir do nome / descrição / palavras-gatilho do próprio sidecar, e o salva no sidecar em guide; as linhas de GET /loras passam então a trazer guide. Recusado com 409 enquanto uma renderização roda (o planejador é um modelo de 12B). Retorna { ok, guide }.

POST /loras/refresh

Reexamina mlx_models/loras/. Retorna o mesmo payload de /loras.

POST /loras/delete

CampoTipoObservação
idstringID do LoRA em /loras.

Exclui o arquivo. Retorna {"ok": true}.

POST /h3/loras/import

multipart/form-data. Instala na biblioteca de LoRAs própria do H3 (mlx_models/hailuo-h3/loras/, ou onde o pacote instalado a guardar) um adaptador do Hailuo H3 que você já tem. De propósito NÃO é /upload: a mídia de referência pode ser qualquer imagem ou áudio, ao passo que um adaptador do H3 precisa passar pelo contrato de layout do runner antes de poder aparecer no seletor.

CampoTipoObservação
filefileExatamente um .safetensors. O nome do arquivo é reduzido ao nome base e higienizado; não pode colidir com um arquivo que já esteja na biblioteca.

O corpo é transmitido em fluxo para um diretório de preparação oculto, sem ser armazenado em buffer, então um adaptador de vários gigabytes custa cerca de 1 MiB de memória residente. Content-Length é obrigatório e limitado a H3_LORA_UPLOAD_MAX_BYTES (4 GiB).

O que acontece com o arquivo, em ordem: preparado em .import.<pid>.<tid>/<name> → _h3_lora_prepare (um repack do ComfyUI tem o namespace diffusion_model. removido no próprio arquivo, uma reescrita só do cabeçalho) → as verificações de payload e de módulos de destino exclusivas da importação → os.replace para a biblioteca → JSON sidecar. Uma recusa em qualquer etapa não deixa nada para trás.

Retorna:

{
  "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 é gravado no sidecar e usado pelo controle de intensidade por LoRA do seletor. O carregador do H3 aplica B @ A e nenhum alpha, então um adaptador cujo PEFT alpha/rank ainda não está incorporado em lora_B precisa desse número aqui; isso é informado, nunca usado como motivo de recusa.

Erros: 411 quando Content-Length está ausente ou é zero, 413 quando o corpo excede o limite, 400 para um arquivo inválido (extensão errada, vazio, nome duplicado, layout inutilizável, payload malformado, modelo errado) e 500 nos demais casos. Toda mensagem cita o arquivo que o usuário escolheu.


Treinamento

POST /train/upload

Envio multipart/form-data. Adiciona uma imagem a um conjunto de treinamento: esta rota é de um arquivo por requisição, não em lote. Envie as imagens em um laço, devolvendo o train_job_id retornado em cada chamada depois da primeira, para que o conjunto inteiro caia em um único diretório.

CampoTipoObservação
job_idstringOpcional na PRIMEIRA chamada (um id novo é gerado), obrigatório depois, para manter o lote unido. Atenção ao nome: job_id, não train_job_id; a resposta o devolve como train_job_id.
filefileExatamente UM PNG/JPG/JPEG/WEBP/BMP, ou uma legenda .txt.

O corpo da requisição é limitado a TRAIN_MAX_BYTES_PER_IMAGE (32 MB). Como esse limite vale para a requisição inteira e a rota recebe um arquivo, um corpo com vários arquivos é recusado mesmo quando cada imagem é pequena.

Retorna o estado do conjunto (train_job_id, número de imagens etc.).

POST /train/start

Inicia o treinamento de um LoRA de personagem. O painel chama o lora_lab.train_character por shell e transmite os eventos de progresso para STATE['log'].

CampoTipoObservação
train_job_idstringVindo de /train/upload.
triggerstringToken gatilho, por exemplo explorertrn. Deve ser composto, raro e só de letras, para não colidir com a linguagem normal: dígitos viram tokens isolados e muito comuns (mrz07 → m / rz / 0 / 7), e todo gatilho que carregou uma identidade aqui tinha só letras; o painel sugere <3 consonants>trn (mrztrn) e registra uma nota quando um gatilho tem dígitos (#62). O LoRA do personagem fica em mlx_models/loras/<trigger>_v2.safetensors.
presetquick | medium | highPredefinição de hiperparâmetros. Padrão alterado na v4.6.1: omiti-la agora dá high para train_type=character e quick para train_type=style (TRAIN_DEFAULT_PRESET); antes dava quick para ambos, que é o nível que nunca carregou uma identidade (#62). Veja a tabela abaixo: o número de passos não é constante, e em um Mac com menos de 64 GB nada mais é.
image_countintConfirmado pelo painel a partir das imagens enviadas.

Substituições avançadas (todas opcionais, voltam aos padrões da predefinição):

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

Retorna {"ok": true, "id": "j-<...>"}. Acompanhe o progresso por /status (o job de treinamento aparece em current e depois em history).

O que as predefinições realmente são

Os passos são derivados, não fixos: steps = epochs × image_count, com piso de 1 e limitado pelo max_steps da predefinição (_preset_steps_for, mlx_ltx_panel.py:1629). O limite faz parte do contrato do servidor: uma chamada de API escrita à mão não pode conseguir colocar na fila uma execução de milhares de passos em um Mac com pouca memória.

Em um Mac com 64 GB ou mais (TRAIN_PRESETS, mlx_ltx_panel.py:1558):

presetépocasrankresoluçãomax_stepsAvaliado para identidade?
quick3085128000Não. A etiqueta diz “identity ungraded”.
medium601657612000Não. Igual.
high1003251220000Sim: a receita v2 validada (Aria_v2, Bizarro_v2). O padrão, e a que a etiqueta marca como “Recommended”.

Medido com lora_compat.py: adaptadores de rank 32 que carregam uma identidade ficam entre 5,4e-04 e 1,6e-03 de delta_rms; as execuções quick de rank 8 de dois usuários independentes mediram 1,54e-04 e 1,98e-04, ambas no piso WEAK_DELTA_RMS de 2,0e-04 ou abaixo dele (#62).

Assim, high com 50 imagens dá 5000 passos, com 20 imagens 2000, com 300 imagens 20000 (limitado). Só a receita de rank 32 já foi posta diante de olhos humanos e considerada boa.

⚠️ Abaixo de 64 GB, toda predefinição vira, em silêncio, outra predefinição

O _select_train_profile (mlx_ltx_panel.py:1650) roda uma vez na importação e, quando a RAM total é 0 < ram < 64 GB, ele modifica TRAIN_PRESETS e TRAIN_STYLE_PRESETS no lugar. Os nomes não mudam. Os números mudam todos:

presetépocasrankresoluçãomax_stepsmódulos-alvo
quick24384120conjunto compacto
medium58384300conjunto compacto
high108448500conjunto compacto

O make_job aplica os mesmos limites no servidor, então rank / steps / resolution passados como substituições avançadas também são limitados (max_rank 8, max_resolution 448, max_steps 500): você não consegue pedir a receita avaliada neste hardware e recebê-la.

É uma troca deliberada e o motivo é real: o treinamento completo de LoRA do LTX a 512 px materializa as ativações de retropropagação do transformer dev e um Mac de 48 GB cai em swap thrash e nunca termina. Mas fique claro o que isso significa: em um Mac com menos de 64 GB não existe predefinição que treine a receita que alguém já avaliou. Rank 8 com ≤500 passos é exatamente o regime que o adapter_verdict foi criado para detectar, então espere weak com mais frequência aqui e leia isso como “este hardware, esta receita” e não como “este conjunto de imagens”.

GET /status expõe o perfil ativo como train_profile (key: compact_training | full_training, mais label, ram_gb, max_rank, max_resolution, max_steps, note) e as próprias tabelas efetivas como train_presets / train_style_presets (mlx_ltx_panel.py:21842-21844). Leia esses campos antes de confiar no nome de uma predefinição: eles são os valores depois da modificação, então são o único lugar onde as duas tabelas acima se distinguem em tempo de execução.

O evento de treinador adapter_strength

Não é um evento de análise de uso: nada sobre ele sai da máquina (veja docs/ANALYTICS.md para a lista completa do que sai). É um evento de progresso no fluxo do subprocesso do lora_lab, emitido uma vez depois que o treinador mede o arquivo que acabou de gravar (mlx_ltx_panel.py:18005). O painel registra a mediana do delta RMS, o máximo e quantos módulos estão carregando, e então termina o job em estado de AVISO, e não num simples done, quando o veredito não é ok. O veredito é gravado no sidecar do LoRA como adapter_strength: {"verdict": …} e lido de volta como adapter_verdict em /loras e /characters.

POST /train/install

Depois de um treinamento bem-sucedido, o LoRA é copiado automaticamente para mlx_models/loras/. Este endpoint serve para reinstalar explicitamente / atualizar os metadados.

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

Excluem conjuntos de treinamento / imagens individuais de treinamento.


Personagens

Descubra e controle LoRAs de personagens treinados como pacotes.

GET /characters

Retorna {"characters": [...]}. Cada entrada descreve um personagem descoberto em mlx_models/loras/:

CampoTipoObservação
id, triggerstringO mesmo valor: o token gatilho raro.
name, pronoun, subject_nounstringDo mlx_models/characters/<trigger>/bundle.json opcional.
face_lora_pathstringCaminho absoluto de <trigger>_v2.safetensors. Sempre presente.
sample_image_urlstring | nullURL de uma imagem de prévia do conjunto de treinamento.
sheet_image_path, sheet_image_urlstring | nullA folha de personagem com várias vistas gerada (mlx_models/characters/<trigger>/sheet.png), quando existe. Feita por POST /characters/<id>/sheet/generate, servida por GET /characters/<id>/sheet.

Regra de descoberta: <trigger>_v2.safetensors é obrigatório; todo o resto é opcional.

GET /characters/<id>/preview

Serve a imagem de amostra do treinamento do personagem (PNG/JPEG).

GET /characters/<id>/sheet

Serve o PNG da folha de personagem gerada. ?w=<px> retorna uma miniatura em cache (JPEG) pela mesma faixa de redimensionamento de /image?w=. 404 até que uma folha tenha sido gerada.

POST /characters/<id>/sheet/generate

Renderiza uma folha de giro com várias vistas a partir da imagem de referência do personagem (primeiro o avatar do pacote, depois a amostra de treinamento) e a compõe em mlx_models/characters/<id>/sheet.png + um sidecar sheet.json (phosphene/character_sheet@1). Síncrono, como /image/generate: quem chama fica bloqueado durante a renderização inteira; 429 quando a GPU já está ocupada por um job de renderização/treinamento/imagem (nunca entra na fila).

Content-Type: application/json. Todos os campos são opcionais (um corpo vazio renderiza a folha padrão de 3 vistas):

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

Só são aceitos motores que respeitam referências (hidream_*_inline, qwen_edit_*_inline, mock_inline): um motor só de texto renderizaria um estranho. seed >= 0 dá à vista i a seed seed + i, de modo que uma folha inteira se reproduz a partir de um número. O prompt de cada vista fixa o guarda-roupa na referência (“wearing exactly the same clothes as in the reference image”); wardrobe repete a roupa em palavras por cima disso. As vistas depois da primeira também encadeiam a primeira vista renderizada como segunda referência: medido em uma imagem de referência escura, renderizações laterais isoladas reimaginavam a cor do cabelo entre seeds e formulações, e uma vista frontal limpa da mesma execução reancora os atributos que a referência bruta deixa pouco especificados. O enquadramento por vista ainda pode variar (um sujeito fora do centro em uma vista): gere de novo ou varie a seed. Em caso de sucesso, o preview do bundle.json aponta para sheet.png somente se estava nulo: uma prévia curada nunca é sobrescrita.

POST /characters/<id>/generate

Monta a receita de produção travada e coloca na fila uma renderização T2V. O endpoint aceita prompt_body, framing, duration, quality e um seed inteiro opcional (-1 significa aleatório, como em /queue/add). Para chamadas de reprodução/depuração exatas, quem chama pode passar full_prompt mais campos de substituição HQ como stage1_steps, stage2_steps, teacache_thresh, cfg_scale, bongmath_max_iter, video_skip_step e audio_skip_step.


Geração de imagens (separada do vídeo)

POST /image/generate

Gera imagens estáticas pelo motor de imagem incluído (mflux, BFL, backend mock). Configurável a cada chamada.

Content-Type: application/json. Payload:

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

Veja image_engine.py para as opções específicas de cada backend.

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

Mantidos no caminho legado /agent/ por compatibilidade com o frontend do Image Studio. Leem/gravam a configuração do motor de imagem (backend padrão, família mflux, chave BFL etc.). Apesar do caminho, esta é a configuração do motor de imagem, NÃO o agente de chat removido.


Storyboard: planejar um filme e depois filmá-lo

Uma board é um filme: um conceito, um elenco, locações e uma lista numerada de planos. Toda renderização que ela inicia passa pelo mesmo contrato make_job → fila de /queue/add; nenhuma destas rotas tem um caminho de execução próprio. As boards ficam em state/storyboards/<board_id>/, com o storyboard.json gravado de forma atômica: as renderizações rodam por horas e uma board corrompida perderia a execução inteira.

Leitura

RotaRetorna
GET /storyboard/listTodas as boards, das mais novas para as mais antigas.
GET /storyboard/get?id=<bid>Um documento de board.
GET /storyboard/filmsOs filmes montados no disco: caminho do player, duração, tamanho da imagem, tamanho em disco, quando foi feito. O list_outputs faz glob de OUTPUT/*.mp4 e nunca desce em pastas, então sem isto a única coisa que o recurso produz seria a única coisa que o app não consegue mostrar.

Chaves do briefing (em plan)

CampoChave da boardEfeito
autoautodepois do plano: renderiza todos os planos, corta, monta, sem mais botões
anchor_stillsanchor_stillsantes de um plano de texto/personagem ser renderizado, um job de imagem comum faz o primeiro quadro dele (still_job_id → still; a folha do personagem é a referência pelo qwen_edit_inline quando existe) e o clipe é renderizado como i2v · anchor a partir dele. Uma imagem que falha define still_error e o plano é renderizado sem âncora, uma vez
long_windowslong_windowsum plano LTX com mais de 121 quadros é renderizado como temporal_mode=windows (uma cadeia no transformer dev Q8) com o estilo da board e a locação do plano como window_invariants, em vez de ser cortado para caber. O Estender não consegue reinjetar uma imagem por janela, então um plano longo ancorado só é ancorado pela primeira janela
take_secondstake_secondsum take: o filme é um único plano de 30 / 45 / 60 / 90 / 120 s. O planejador escreve um beat a cada 5 s (_sb_take_concept), a board mantém UM plano com beats (collapse_take), o cartão mostra os beats para edição, e shot_to_job envia take_seconds + beats, o take da aba Vídeo, de modo que a renderização é a mesma nas duas portas. 0 desliga

Cada campo só é alterado quando enviado; um campo ausente mantém o valor da board.

POST /storyboard/restill: formulário id, n, pass opcional: esquece a imagem do plano n e o clipe renderizado a partir dela, liga anchor_stills se estava desligado e renderiza só esse plano (primeiro a imagem, depois o clipe a partir dela). As mesmas recusas de render (planejando, já renderizando).

Escrita: POST /storyboard/<action>

O Diretor. plan aceita soundtrack (um arquivo de áudio neste Mac) e bars_per_shot (1/2/4, padrão 2). Com uma faixa, o plano é um VIDEOCLIPE: o beat_map() (o mesmo ajuste que o Preparar do Editor executa) transforma os tempos fortes em slots de bars_per_shot compassos, o número de planos é o número de slots (os chips de shots ficam de lado; limitado a STORYBOARD_MAX_SHOTS com uma nota), o briefing do planejador traz o bpm, a duração do slot, uma instrução de arco e duas leis (comece toda descrição pelo movimento; sem diálogo, a faixa substitui o som de cada clipe), e o duration_s de cada plano planejado é o seu slot mais uma margem de um segundo, com slot: {start, end} no plano. O mapa da música decide a frequência. O song_map() (storyboard_edit) coloca SEÇÕES na mesma grade de compassos: {start, end, label, energy, brightness}, com os rótulos intro / verse / chorus / bridge / outro conforme a posição, o volume relativo e o brilho, e o director_pacing() transforma bars_per_shot em um passo por seção: o refrão corta duas vezes mais, a introdução e o final metade. Cada slot carrega a sua section; o briefing diz ao planejador quais planos caem em qual seção e quão quente ela é; uma faixa que o mapa não consegue ler é cortada no passo base e o log informa. A board registra soundtrack: {path, bpm, bars_per_shot, total_sec, count, slots, sections}, o primeiro corte automático do Editor usa essa faixa quando o Preparar não guardou outra em cache (assim o filme já abre cortado no ritmo), e GET /storyboard/edit retorna sections para que a régua possa pintar o arco. Um caminho inválido é um 400 antes de o planejador rodar; a etapa grid do planejador é informada enquanto o ritmo é lido.

Auto. plan aceita auto=1: quando o plano fica pronto, a renderização em rascunho de cada plano começa sozinha (_sb_auto_after_plan, depois que o planejador devolveu a memória), e quando a thread de renderização termina com todos os planos renderizados o filme é cortado (_sbe_auto_edit, no ritmo quando há faixa) e montado pelo mesmo montador que o Render usa (_sb_auto_film); a board registra auto_film. Um plano que não foi renderizado deixa o filme esperando e o log diz quantos. Parar ainda para a renderização; o corte e o filme são os comuns e podem ser recortados depois.

Codificado como formulário, salvo indicação em contrário. id é o id da board em todos os casos.

AçãoCamposObservação
planconcept, id, notes, shots, must, engine, character_id, style, locations, wardrobePlanejar ou replanejar. 409 enquanto o renderizador ocupa a memória ou o único slot de planejador está em uso. shots é respeitado ou recusado, nunca trocado em silêncio por outro número. Um replanejamento ATUALIZA locações e guarda-roupa em vez de sobrescrevê-los.
cancelidLibera um slot de planejador.
saveJSON {id, board}Grava uma board editada à mão.
gradeid, n, grade, noteAvalia um plano.
estimateid, pass, onlyEstimativa de custo/tempo antes de gastar.
renderid, pass, only, out, music, music_modeFilma a board.
stopidPara a renderização da board em andamento.
replan-shotsid, nsRefaz o sorteio de planos nomeados. Um reparo que viola uma lei é rejeitado; os novos sorteios entram no plano ATUAL, não no original.
add-shotid, path
import-shotsid, from, onlyClipes de REFERÊNCIA de outra board. A proveniência (imported_from), as LOCAÇÕES de origem e o ELENCO de origem viajam com eles: deixar qualquer um para trás quebra algo específico. Recusa enquanto o filme de destino está sendo renderizado.
exportid, auto_edit, music, target_seconds, music_mode
revealid, name, whatMostrar no Finder (macOS).
deleteid

Schema da board: os campos de geografia

Um plano é composto a partir da sua locação. Desde 2026-08-18, uma locação também pode ser vista de mais de uma direção, e é isso que faz de um contracampo um contracampo, e não uma segunda locação.

"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"
   …}
]
CampoOndeRegras
locations[].viewslocaçãoLista de {id, name, light, description}. Ausente, não [], quando a locação não tem nenhuma: toda board escrita antes de existirem vistas não tem a chave, e uma lista vazia seria um formato novo sobre o qual o validador teria opinião, sem ganho nenhum. Os ids seguem o mesmo conjunto de caracteres dos ids de locação.
shots[].viewplanoUm id de vista pertencente ao location_id desse plano. Uma vista em um plano sem locação, ou uma vista que não é uma das da locação, é um erro de validação (unknown_view) e falha exatamente como uma locação desconhecida: uma vista descartada em silêncio compõe o contracampo a partir da descrição de estabelecimento, e o carro que a vista existia para tirar do quadro volta a ele sem que nada seja dito.
shots[].eyelineplanoUm entre left, right, lens: um fato sobre o QUADRO, não sobre a sala. right = os olhos vão para fora, além da borda direita. Qualquer outro valor é um erro de validação (bad_eyeline).

O que o servidor faz com eles. O shot_scene_text injeta a descrição da VISTA quando um plano cita uma e, caso contrário, recorre à da locação: assim uma board sem vistas, ou um plano que não cita vista, é renderizado exatamente como sempre foi. O eyeline_clause compõe "his eyes fixed past the right edge of frame" na hora da renderização; lens deliberadamente não produz nada (mandar esses modelos olharem para dentro da lente rende uma atuação mais dura do que o silêncio), e ele existe para que um plano possa dizer que olha para a lente, o que permite à verificação dos 180 graus distinguir “olha para a câmera” de “ninguém escreveu nada”.

A regra dos 180 graus é imposta, não sugerida. Depois do planejamento, o _enforce_eyelines percorre os planos em ordem de tela e inverte o segundo de quaisquer dois planos adjacentes que alternam entre dois personagens diferentes na mesma locação e que afirmam o mesmo lado, e avisa isso em warnings. Ele corrige de forma mecânica porque eyeline é um campo discreto com exatamente um complemento: invertê-lo não pode danificar a prosa de ninguém. As leis em nível de prosa recebem uma ida e volta ao modelo, justamente por não terem essa propriedade.


Editor: a linha do tempo

O Editor é um fluxo de trabalho de nível superior, não uma etapa do storyboard: independe do motor, abre sem que uma board esteja no meio de uma renderização, e o seu documento é o edit.json no diretório da board. Uma faixa de vídeo, uma faixa de música. O som de cada clipe é vinculado por padrão e pode ser separado (J/L cuts); isso não é uma segunda faixa de áudio.

Leitura

RotaRetorna
GET /storyboard/edit?id=<bid>O arranjo. Na primeira chamada de uma board ele executa a edição automática UMA vez, a grava na faixa automática e a retorna com generated: true. Todo GET seguinte é uma leitura de arquivo. Um edit.json corrompido retorna 500 com corrupt: true e nunca é substituído em silêncio: isso jogaria fora o arranjo do qual ele é uma cópia quebrada.
GET /storyboard/edit/status?id=<bid>O estado do job de preparação.
GET /storyboard/edit/peaks?id=<bid>A forma de onda. Centenas de KB: busque uma vez, nunca em uma consulta periódica. 404 até que prepare tenha rodado.
GET /storyboard/edit/proxy?id=<bid>&name=<file>.mp4Um vídeo proxy, servido com suporte a range. O Safari não faz seek em um <video> cujo servidor responde apenas 200, o que desfaria toda a razão de existirem os proxies. name deve casar com [A-Za-z0-9._-]{1,120}\.mp4: é um nome base gerado pelo servidor, então qualquer outra coisa é uma sondagem.
GET /storyboard/edit/uploadsVídeos que o usuário trouxe (panel_uploads/timeline/, os mais novos primeiro, limitado a 200). Mantidos fora de OUTPUT de propósito, e é por isso que precisam de uma rota; as imagens não precisam, elas vão para a biblioteca que a galeria já percorre.
GET /storyboard/edit/sounds?id=<bid>A fonte Som do pool de mídia: {sounds: [{path, name, where, mtime}], dir}: primeiro a própria pasta audio/ do filme (where: "film"), depois os arquivos de som (.wav .m4a .mp3 .aac .flac .aif .ogg .opus) no topo de OUTPUT, os mais novos primeiro, limitado a 300. Sem sondagem; a duração é lida quando um som é adicionado.
GET /storyboard/edit/drafts?id=<bid>{active, drafts: [...], backup}: veja Rascunhos abaixo.
GET /storyboard/edit/versions?id=<bid>Só metadados: nome, revisão, quando foi guardada, número de clipes, duração, mais keep (= EDIT_HISTORY_KEEP, 50). Os documentos em si são lidos uma vez, por restore, a pedido do usuário. Abrir o painel não deve ser um download.

Escrita: POST /storyboard/edit/<sub>

SubCamposObservação
prepareid, music, target_secondsCria proxies + picos. 400 se music não for um arquivo.
add-clipid, from, only, path, title, kindkind é video | still | slug: passá-lo é o que impede que uma imagem entre como um vídeo sem quadros.
add-soundid, pathUm arquivo para uma faixa de áudio: sondado ({path, title, duration_s, has_video, imported}), 400 quando não tem som. Um arquivo fora de OUTPUT recebe um hardlink (copiado entre volumes) para a pasta audio/ do próprio filme antes, porque /file só serve OUTPUT e um som que a prévia não consegue tocar é meio som. A faixa é posicionada e salva pelo cliente.
relinkid, onlyReaponta os clipes para os arquivos finalizados (de entrega). Um RETAKE finalizado nunca faz parte desse lote: ele é oferecido junto ao seu clipe com retake: true nas linhas relink do payload e adotado um clipe por vez com only=<clip id>.
cancelidCancela o job de preparação.
autoid, music, target_seconds, min_shot, max_shotExecuta de novo o corte da máquina. Cai na faixa automática.
saveJSON {id, edit, expect_revision?}Veja abaixo.
draftid, op, slug, name, fromVeja Rascunhos.
backupJSON {id, edit}A faixa silenciosa. Veja Rascunhos.
recoveridAdota o backup pendente.
discard-backupidDescarta-o.
versionid, labelDá nome a uma versão. Dar nome não é salvar: sem aumento de revisão, sem gravação em edit.json, nada na linha do tempo muda, e é exatamente por isso que é seguro apertar a qualquer momento.
restoreid, fileRestaura uma entrada do histórico. Recusa enquanto o filme é renderizado.
renderid, out, music, music_mode, format, sizeMonta o filme. music_mode é replace | under. Entregar como: format é h264 (padrão, a predefinição do painel) | hevc (VideoToolbox, hvc1, cerca de metade dos bytes) | prores (422 HQ, 10 bits 4:2:2, som PCM, um .mov que nenhum navegador mostra); size é native (como cortado) | 1080p | 2160p: uma única escala Lanczos depois das sobreposições, só para cima, nunca um recorte, ignorada quando o corte já tem essa altura. finish é none | grain | heavy_grain: grão de filme em movimento (noise t+u, intensidade 9 / 18) acrescentado DEPOIS do tamanho, para que uma entrega em 4K receba grão em 4K; um tratamento de entrega, nunca no documento, nunca na prévia nem na exportação. Uma entrega diferente é um arquivo diferente: <slug>_film_hevc_1080p.mp4, <slug>_film_prores.mov, <slug>_film_1080p_grain.mp4. Os fatos trazem deliver: {format, size, finish, label}.
export-nleidXML do FCP7 + JSX do After Effects + mídia vinculada.
revealid, whatMostrar no Finder.
generateid, prompt, duration, duration_s, film_start, pass, character_id, seed, title, engine, trigger, retake_ofFilma um novo clipe direto em um slot. Com retake_of=<clip id> é um retake: o plano do próprio clipe é CLONADO (personagem, refs, locação, motor) e só o prompt, a duração e a seed mudam; o novo plano traz edit_slot.retake_of, e quando é renderizado o Editor o oferece junto a esse clipe (“Use it” / “Keep the old one”). 400 se o clipe não estiver mais na linha do tempo.

Semântica de save. revision é o contador do servidor, tirado do disco, nunca do que o cliente lembrava: uma aba desatualizada não pode conseguir fazê-lo voltar atrás. Passe expect_revision para descobrir que outra aba passou na sua frente em vez de sobrescrevê-la em silêncio: um conflito retorna 409 com conflict: true e a revisão atual. Os erros de validação voltam todos de uma vez (errors: [...], 400) com o arquivo em disco intocado, de modo que um cliente possa destacar todos os clipes ruins em uma passada, em vez de brincar de acerta-a-toupeira.

Schema do edit.json

version é 2 (EDIT_VERSION). A versão 1 é atualizada somente na LEITURA (migrate_edit): subir a versão sem um caminho de atualização na leitura não recusaria as versões antigas, recusaria todas as linhas do tempo que alguém já tinha. Uma versão do futuro é deixada como está, para que o validador possa dizer a coisa honesta.

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

CampoObservação
id, path, proxypath/proxy são null em um slug.
start, endA janela DENTRO da origem.
film_start, film_endO slot no filme. Nunca independentes: um clipe toca a 1x, então film_end - film_start == end - start dentro de LENGTH_TOLERANCE (2 ms).
kindvideo (ausente significa vídeo: gravá-lo em 400 clipes reescreveria todo edit.json da máquina para dizer o que a ausência dele já diz), still (mantido pela duração do seu slot; start/end são sintetizados a partir do slot, duration: null), slug (preto, sem arquivo).
sourceauto | human.
lockedbool.
adjust{brightness}, um deslocamento aditivo de eq=brightness do ffmpeg limitado a ±BRIGHTNESS_LIMIT (0,5). O neutro é a ausência: arrastar o controle de volta a zero deixa um documento idêntico ao de um que nunca teve controle.
frame{zoom, x, y}: um reenquadramento. A imagem é ampliada zoom vezes (1 a 3) e a janela é centrada na fração (x, y) da origem. Renderização: um crop dos pixels da própria origem antes do ajuste, de modo que uma única string vale em qualquer tamanho; prévia: uma escala CSS em torno da mesma âncora (aproximada); exportação: Basic Motion do FCP7 (escala + centro) e escala + posição do AE. O neutro é a ausência; um slug não tem o que reenquadrar.
speedTaxa de reprodução, SPEED_MIN a SPEED_MAX (0,25 a 4,0), só vídeo. O slot é (end - start) / speed, então a regra de 1x acima passa a dizer “na sua velocidade”. A imagem é setpts, o som é atempo encadeado além da janela de 0,5 a 2,0 do ffmpeg, e o envelope do som (afx) continua no relógio TOCADO da faixa: um keyframe em 2 s continua em 2 s da faixa depois de uma mudança de tempo. Ausente é 1x. Nunca definido automaticamente.
audioA edição dividida. Veja abaixo.

clip.audio: o J-cut e o L-cut

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

Só clipes de vídeo. Os mesmos três números da imagem, para o SOM: assim o som pode começar antes da imagem (J) ou continuar além dela (L), que é como um corte deixa de ser uma emenda seca.

Ausente significa vinculado, e essa é toda a migração: todo clipe já escrito não tem a chave audio e todos eles tocam o próprio som sob a própria imagem. EDIT_VERSION não mudou por isso e nenhum documento foi reescrito.

A PRESENÇA do campo é o interruptor, não os valores dentro dele. Não deduza “vinculado” de audio ser igual à janela da imagem: desvincular grava a janela que o clipe já tem, então um clipe que o usuário acabou de desvincular seria lido como vinculado e se recusaria a ser arrastado. A alternância adiciona o objeto ou o apaga; nada mais decide. normalise_edit arredonda o campo, mas nunca o remove, pelo mesmo motivo, e o retira por completo de uma imagem estática ou de um slug.

As janelas de áudio não podem se sobrepor entre si, assim como as imagens. Uma edição dividida é uma emenda seca que cai em outro lugar, não uma mixagem: a mixagem é para isso que audio_tracks serve.

audio_tracks[]: A3, A4, … sob a 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]]}}]}]

Qualquer número de faixas, cada uma com qualquer número de faixas de áudio (strips). start/end são os pontos de entrada/saída dentro do arquivo (uma strip toca a 1x, então tem end - start de duração no filme); film_start é um segundo da linha do tempo, posicionado com adelay exatamente como a base é. afx é o mesmo objeto de envelope que o som de um clipe e a base carregam, lido por audio_gain_points; o gain da strip e o gain da faixa (linear 0 a 1) o multiplicam: track_strip_gain_points é a única curva que a prévia, a renderização e a exportação leem. Ausente é nenhuma e o neutro é a ausência: uma edição sem faixas não tem a chave, então carrega, salva e renderiza com bytes idênticos; uma faixa vazia é mantida.

As strips de uma mesma faixa não podem se sobrepor (audio_track_strips_overlap, um erro, com TOUCH_TOLERANCE para uma emenda seca); as strips de faixas diferentes se sobrepõem e se misturam. Erros de formato: 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*.

Renderização: toda strip audível (sem mudo, faixa sem mudo, curva não silenciosa) é um -vn -i depois das sobreposições, atrim → volume (a sua curva, no relógio da strip) → aresample → adelay (em amostras) → apad → atrim para o filme, e todas elas passam por amix (normalize=0, duration=first) sobre o som dos clipes e a base, sob o único limitador asoftclip; os fatos do filme trazem sound_strips e mix_peak. Uma strip cujo arquivo sumiu recusa a renderização, citando o seu caminho e a faixa. Exportação: cada faixa é uma faixa de áudio própria do FCP7 (clipitems com entrada/saída, keyframes de nível, <enabled>FALSE</enabled> para um mudo) e cada strip é uma camada do After Effects chamada <track> · <title>.

transitions[]: um objeto tipado que é dono de uma FRONTEIRA

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

Uma dissolução cruzada são dois clipes no mesmo segundo, e a regra da faixa de imagem de um clipe de cada vez (clips_overlap) sustenta tudo: por isso uma transição não é uma sobreposição. Ela nomeia o clipe de SAÍDA e fica sobre o corte entre ele e o seguinte na ordem do filme; uma por fronteira. Os film_start/film_end dos próprios clipes não se movem e o filme continua exatamente tão longo quanto a linha do tempo diz. A renderização puxa metade da duração de cauda extra de depois do ponto de saída do clipe de saída e metade de cabeça extra de antes do ponto de entrada do clipe de entrada (material de origem que os cortes deixaram para trás), divide a concatenação da imagem na fronteira e junta as duas partes com xfade (fade / fadeblack) centrado no corte. O som não precisa de nada novo: segue o caminho das faixas (_sb_split_audio_plan), exatamente como um J-cut.

duration é limitada em toda leitura (transition_duration) a min(asked, half the shorter neighbour, 2.0 s) e ajustada a um número par de quadros; o documento guarda o número digitado. Um lado sem material sobrando é recusado: transition_no_handles cita o lado e a falta (“clip 2 has only 0.10s before its in-point and the dissolve needs 0.25s there”). Todo código de transição (transitions_shape, transition_shape, transition_unknown_clip, transition_last_clip, transition_duplicate_boundary, transition_kind, transition_duration, transition_no_handles) é um erro; nenhum está em WARNING_CODES. render recusa com a mesma frase. Uma imagem estática e um slug têm todas as margens que alguém poderia pedir.

overlays[]: cartões, máscaras e títulos

kind é still | video | text. Um kind explícito vale; sem ele, o sufixo do caminho decide (.png/.webp/.tif são imagens), então toda sobreposição escrita antes de existirem títulos é lida como antes. Um título é uma sobreposição cujos pixels a renderização desenha:

{"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 é em px em um quadro de 1080 de altura e escala com o filme; x/y são a âncora como frações do quadro; align diz qual borda do texto fica em x. overlay_text() é o único acessor e o estilo só é gravado onde difere dos padrões. A fonte é um ARQUIVO (LTX_TITLE_FONT, ou então a primeira de TITLE_FONT_CANDIDATES presente na máquina), verificado antes de o ffmpeg ser montado; sem nenhuma, render responde 400 com uma frase, em vez de entregar um filme com um buraco. O raster é um PNG RGBA do tamanho do quadro ao lado do filme (.titles/) alimentado pela mesma cadeia de sobreposição de um cartão enviado, de modo que um título herda o alfa, os fades e a ordem de camadas da faixa. Os títulos são desenhados no palco, no DOM, na mesma âncora e no mesmo tamanho; não viajam na exportação para NLE (não têm caminho).

audio: a trilha sonora, como um objeto na linha do tempo

"audio": {"path": "…", "duration": 180.0, "peaks": "peaks.json",
          "offset": -4.0, "trim_start": 12.0, "trim_end": 96.0}
CampoSignificado
offsetO segundo da FAIXA que toca no tempo 0 do filme. Significa isso desde antes de o editor existir, então todo documento no disco continua funcionando. Agora pode ser negativo: a faixa começa -offset segundos dentro do filme, com silêncio na frente.
trim_start / trim_endPontos de entrada/saída DENTRO da faixa, em segundos da faixa. Ausente significa sem corte, e por isso um edit.json escrito antes disto continua válido: sem campo, sem corte, o mesmo filtergraph. Um corte no fim da faixa ou além dele não é um corte, e o normalise_edit o descarta: uma alça arrastada de volta até o fim deixa um grafo idêntico byte a byte.

music_window(audio, duration=…) é o único lugar onde isso vira os números de que o ffmpeg e todo exportador precisam: start = max(trim_start, offset) (um corte de cabeça e um offset positivo são o mesmo gesto vistos de dois lados; vale o que corta mais), end ou None para “tocar até o fim”, e delay/film_start = start - offset. Cortar a borda esquerda não desliza o resto da faixa para mais cedo: isso seria um ripple, e música não faz ripple, então os segundos que um corte de cabeça remove voltam como silêncio na frente. Uma janela que os cortes fecham por completo retorna “sem música”, em vez de um atrim de duração zero que o ffmpeg recusa.

Rascunhos, backups e histórico: três coisas diferentes

Os rascunhos são variações nomeadas do mesmo filme, em drafts/, com um index.json que nomeia o ativo. Uma board que só tem edit.json tem exatamente um rascunho e sempre teve; só não tinha nome para ele. O load_draft_index o nomeia na saída, e não em uma passada de reescrita, para que a atualização não possa acontecer pela metade.

POST /storyboard/edit/draft é uma rota com cinco verbos: são cinco edições do mesmo ponteiro ativo, e separá-los seriam cinco lugares para esse ponteiro ficar errado:

opCampos extrasEfeito
newname, from=currentNovo rascunho, vazio ou copiado do que está na tela. Torna-se o ativo.
duplicateslug, name
renameslug, name
deleteslug
activateslugGuarda antes o rascunho ativo atual: nunca o perde.

new, duplicate, delete e activate retornam 409 com busy: true enquanto esse filme é renderizado: a renderização lê este documento clipe a clipe, e trocar a linha do tempo por baixo dela é o mesmo risco que import-shots e restore recusam.

O backup é nosso, o salvamento é do usuário. POST /storyboard/edit/backup grava history/backup-<draft>.json e mais nada: nem edit.json, nem revisão, nem verificação de conflito. O rascunho salvo do usuário continua exatamente como ele o salvou por último. Ele aparece em GET …/drafts como backup e é oferecido, nunca aplicado: recover o adota, discard-backup o descarta.

O histórico são duas faixas mais uma faixa de guarda, distinguidas pelo prefixo do nome do arquivo e não pela abertura dos arquivos: uma limpeza que precisa ler cinquenta documentos para decidir o que apagar falha no meio, no primeiro corrompido:

PrefixoO quêLimpo?
edit-r*Um snapshot automático.Sim, limitado a EDIT_HISTORY_KEEP (50).
save-r*Um salvamento que o usuário apertou.Nunca.
keep-r*Uma versão que o usuário nomeou (version).Nunca.

Todo salvamento arquiva o antecessor antes de o novo documento ser gravado (~5 KB cada). Uma falha no histórico nunca deve bloquear um salvamento: perder uma migalha não é nada diante de recusar-se a persistir o arranjo que está na tela. origin também é gravado dentro do JSON, para quem lê um arquivo isoladamente.


Gerenciamento de resultados

POST /output/delete

CampoTipoObservação
pathstringDeve estar em mlx_outputs/.

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

Ocultam/reexibem resultados na galeria sem excluir o arquivo.

POST /output/open_folder

Abre no Finder (Mac) a pasta que contém o resultado.


Licenças de modelos (4.19.8)

GET /licences

Todas as licenças sobre as quais o painel pergunta, com o estado de aceitação deste Mac: {"licences": [{"key": "h3", "model": ..., "licence": ..., "licensor": ..., "version": ..., "url": ..., "non_commercial": false, "title": ..., "summary": ..., "terms": [...], "badge": ..., "accept_label": ..., "accepted": false, "accepted_at": null, ...}, ...], "ui": {...}}. Chaves: h3, ideogram4, yue2, flux1_dev, fibo. A entrada do H3 também traz territory_notice, excluded_territories, report_line, report_url e credit_line.

POST /licences/accept

Campos de formulário key=<licence key> e accept=1 (a caixa que o usuário marcou). Registra a aceitação da version atual da licença em state/model_licences.json (mais um arquivo marcador que o instalador do H3 lê) e retorna {"ok": true, "key": ..., "record": {...}, "licence": {...}}. Uma versão alterada da licença pergunta de novo. Aceitar em nome de alguém é aceitar por essa pessoa: um agente deve mostrar ao usuário os termos de GET /licences antes.

Auxiliar / sistema

POST /helper/restart

Reinicia o subprocesso auxiliar aquecido (usado depois de mudanças de ajustes que exigem um processo novo).

POST /stop_comfy

Encerra um processo do ComfyUI se o Phosphene iniciou um.

GET /version/check, POST /version/pull

Autoatualização contra o repositório do GitHub. /version/pull é só um git pull: ele não executa scripts/post_update.sh, então nada do que uma atualização instala (novos pacotes, pesos) é instalado por ele. Desde a 4.17.4, o painel instala sozinho, na próxima inicialização, um separador de voz de sincronização labial que esteja faltando (veja /a2v/separator).

POST /engine/repair

Executa de novo apenas a etapa do ambiente do motor (scripts/pinokio/ltx_engine_env.sh, a mesma etapa que a instalação executa): reinstala os pacotes Python do motor de renderização no seu venv, em segundo plano. Sem downloads, sem reconstruir o venv, sem Parar. Responde 202 (iniciado), 200 {nothing_to_do} (o motor está bem) ou 409 (um reparo está em andamento, ou installing: true: a própria instalação do Pinokio ainda está gravando o venv). O progresso e o resultado seguem em GET /status -> engine_env (ok, fault, installing, repair.{state, active, log, error}).

POST /h3/repair

4.19.5. Executa de novo apenas o scripts/pinokio/h3_deps.sh no checkout do Hailuo H3: reinstala os pacotes Python do H3 no seu próprio venv, no conjunto com que esta versão foi testada (scripts/pinokio/h3_constraints.txt, passado com -c; o uv leva de volta qualquer coisa que já esteja fora dele). Sem pesos, sem Parar: o painel nunca importa o venv do H3. Responde 202 (iniciado) ou 409 (o H3 não está instalado, uma renderização H3 está em andamento ou um reparo já está em andamento). O progresso e o resultado seguem em GET /status -> h3_env (ok, fault, repair.{state, active, log, error}). Uma renderização H3 em um venv fora do conjunto é recusada no início com H3 cannot start: the Hailuo H3 venv ... e este reparo no cartão.

Alertas push: o aviso de conclusão para uma aba fechada

O sinal sonoro na aba e o alerta do navegador (Ajustes → Alertas de conclusão) precisam da página aberta. O Web Push não precisa: o navegador guarda uma assinatura para esta origem, o painel assina cada mensagem com um par de chaves VAPID que ele gera uma vez (state/vapid.json), e o serviço de push do navegador acorda o /sw.js para mostrar a notificação. Sem retransmissor: o painel envia direto ao fornecedor do navegador. Oferecido somente quando pywebpush é importado (GET /settings → push_available).

RotaO quê
GET /sw.jso service worker, servido no escopo raiz com Service-Worker-Allowed: /
GET /push/key{ ok, available, public_key, subscriptions }: a chave pública VAPID com que o navegador se inscreve (503 quando indisponível)
POST /push/subscribeformulário subscription = o JSON do PushSubscription; uma entrada por endpoint
POST /push/unsubscribeformulário endpoint
POST /push/testenvia “This is what a finished render will say.” a todos os inscritos; { ok, sent }

Todo job que termina done ou failed envia um push Phosphene — render done / — a render failed com o rótulo do job (ou os primeiros 60 caracteres do prompt), fora do bloqueio da GPU, somente enquanto notify_done está ativado. Uma assinatura que o fornecedor informa como inexistente (404 / 410) é descartada.

POST /settings

CampoTipoObservação
(any setting key)stringVeja state/panel_settings.json para o conjunto canônico.
notify_done1/0Alertas de conclusão: um sinal sonoro na aba quando uma renderização termina ou falha, e uma notificação do navegador quando a aba está em segundo plano e a pessoa as permitiu. Ativado por padrão; GET /settings o retorna.

POST /prompt/enhance

Codificado como formulário. Reescreve um prompt de antemão com o Gemma. Usado pelos botões Aprimorar do painel (Vídeo e Sincronização labial).

CampoObservação
promptobrigatório
modet2v (padrão), i2v ou a2v (Sincronização labial: o prompt auxiliar de i2v mais a lei de prompt da sincronização labial)
preserve_tokenslista JSON (ou lista separada por vírgulas) de palavras que o resultado deve manter, exatamente como estão: palavras-gatilho
translate0 mantém um prompt de alfabeto não latino no próprio idioma; o padrão é traduzir para inglês
loras4.18.0: lista JSON de caminhos de LoRAs instalados na renderização. O painel lê de cada um o nome, as palavras-gatilho e o guia (ou, na falta, a descrição do criador) na biblioteca de LoRAs (caminhos que ela não lista são ignorados) e entrega no máximo 4, limitados, ao auxiliar como texto de referência delimitado. Um LoRA cujas palavras-gatilho estão todas ausentes do resultado tem o primeiro gatilho recolocado no início.

Retorna { ok, original, enhanced, mode, elapsed_sec, source_non_latin, translated, lora_notes_used: [names], lora_triggers_added: [words] }; { error } com 409 enquanto uma renderização ocupa a GPU.

409 needs_pack (4.20). O Aprimorar roda no Gemma 3, que uma instalação nova baixa em segundo plano depois da primeira inicialização (veja deferred_downloads em GET /status). Até que ele esteja no disco, a rota responde 409 { ok: false, error, needs_pack: "gemma", pack_name, pack_size, pack_state } com pack_state sendo downloading, queued, waiting_disk ou missing, e nunca pede ao auxiliar que o carregue. /storyboard/plan, /storyboard/replan-shots, /oneshot/plan e /train/auto-caption respondem com o mesmo formato pelo mesmo motivo. POST /models/download repo_key=<needs_pack> o baixa agora: enquanto o fetcher em segundo plano ocupa a vaga de download, isso responde 202 { queued: true } e move o pacote para a frente da fila ({ already: true } quando é o que está sendo baixado).

POST /upload

multipart/form-data. Envia uma imagem de referência para os modos I2V ou keyframe. Retorna {"path": "<absolute path under panel_uploads/>"}.


Formato do JSON sidecar

Todo clipe concluído grava um sidecar em <output>.mp4.json junto ao MP4. Schema (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 }
}

Leia os sidecars para comparar execuções sem consultar o painel de novo.


Receita de produção (validada em 2026-05-15)

Para trabalho de vídeo com LoRA de personagem, a receita travada e 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

Tempo total em um M4 Max de 64 GB: ~7:06 por clipe de 7 s em 1024×576, ~3:24 em 736×416.


Exemplo completo: o controle por um agente

Envie um clipe com dois LoRAs, consulte até terminar e imprima o caminho do resultado. Só a biblioteca padrão.

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

Esse é o padrão completo: enviar → consultar → ler o caminho do resultado.


O que foi removido (e o que o substituiu)

O recurso de fluxos agênticos dentro do painel (um planejador de planos guiado por chat) foi removido em 2026-05-15. O snapshot anterior à remoção está guardado de forma durável no GitHub, na tag pre-agent-removal-2026-05-15.

Tudo o que o chat fazia (planejar vários planos, gerar imagens-âncora candidatas, renderizar I2V condicionado a essas âncoras, gerenciar sessões) pode ser feito por um agente externo por meio da API documentada acima. Especificamente:

  • Planejamento de planos: raciocínio de texto do lado do agente, sem envolvimento do painel.
  • Geração de âncoras: POST /image/generate.
  • Âncora para vídeo: POST /queue/add com mode=i2v e image=<anchor_path>.
  • Estado da sessão: o agente o mantém externamente.

Agentes externos podem usar os fluxos documentados por meio desta API.

Fonte: docs/API.md no repositório público. Revisado para este site antes da publicação. Traduzido do original em inglês. Sugerir uma edição.