Hugging Face's logo

Spaces:
Jadewave
/
trans3
Paused

App Files Community
trans3 / docs /pt-BR /reference /http-api.md
Mayo
docs: update to match current implementation
725264a unverified
preview code
|
raw
history blame contribute delete
13.1 kB
metadata 
title: Referência da API HTTP

Referência da API HTTP

O Koharu expõe uma API HTTP local em:

http://127.0.0.1:<PORT>/api/v1

Esta é a mesma API usada pela UI desktop e pela Web UI em modo headless.

Modelo de runtime

Comportamento atual importante:

  • a API é servida pelo mesmo processo da GUI ou do runtime headless
  • o servidor faz bind em 127.0.0.1 por padrão; use --host para fazer bind em outro lugar
  • a API e o servidor MCP compartilham o mesmo projeto carregado, modelos e estado do pipeline
  • quando nenhum --port é fornecido, o Koharu escolhe uma porta local aleatória
  • tudo, exceto /api/v1/downloads, /api/v1/operations e /api/v1/events, retorna 503 Service Unavailable até o app terminar a inicialização

Modelo de recursos

A API é centrada em projetos. Apenas um projeto fica aberto por vez e contém:

  • uma lista de Pages indexada por PageId
  • Nodes por página (camadas de imagem, máscaras, blocos de texto) referenciados por NodeId
  • um armazenamento Blob endereçado por conteúdo, que guarda os bytes brutos das imagens por hash Blake3
  • um snapshot de Scene montado a partir dessas peças, avançado por um contador epoch
  • um histórico de mutações Op que podem ser desfeitas ou refeitas

As mutações sempre passam pela camada de histórico (POST /history/apply), de modo que a cena, o autosave e os assinantes de eventos permaneçam sincronizados.

Formatos comuns de response

Tipos de response frequentemente usados incluem:

  • MetaInfo — versão do app e label do dispositivo de ML
  • EngineCatalog — ids das engines instaláveis por etapa do pipeline
  • ProjectSummary — id, nome, caminho, contagem de páginas, último acesso
  • SceneSnapshot — { epoch, scene }
  • LlmState — estado atual de carga do LLM (status, target, error)
  • LlmCatalog — modelos locais + de provedor agrupados por família
  • JobSummary — { id, kind, status, error }
  • DownloadProgress — id do pacote, contagens de bytes, status

Endpoints

Meta

Método Path Finalidade
GET /meta obtém a versão do app e o backend de ML ativo
GET /engines lista as engines de pipeline registradas por etapa

Fontes

Método Path Finalidade
GET /fonts catálogo combinado de fontes do sistema + Google Fonts para render
GET /google-fonts catálogo do Google Fonts como uma lista isolada
POST /google-fonts/{family}/fetch baixa e faz cache de uma família do Google Fonts
GET /google-fonts/{family}/{file} serve o arquivo TTF/WOFF em cache

Projetos

Todo projeto vive sob o diretório gerenciado {data.path}/projects/; clientes nunca fornecem caminhos do filesystem.

Método Path Finalidade
GET /projects lista os projetos gerenciados
POST /projects cria um novo projeto (body { name })
POST /projects/import extrai um arquivo .khr em um diretório novo e o abre
PUT /projects/current abre um projeto gerenciado por id
DELETE /projects/current fecha a sessão atual
POST /projects/current/export exporta o projeto atual; retorna bytes binários

POST /projects/current/export aceita { format, pages? } onde format é um de khr, psd, rendered, inpainted. Quando o formato produz múltiplos arquivos, a response é application/zip.

Páginas

Método Path Finalidade
POST /pages cria páginas a partir de N arquivos de imagem enviados (multipart)
POST /pages/from-paths caminho rápido só para Tauri que importa por caminho absoluto
POST /pages/{id}/image-layers adiciona um node de imagem Custom a partir de um arquivo enviado
PUT /pages/{id}/masks/{role} faz upsert de um node de máscara a partir de bytes PNG brutos
GET /pages/{id}/thumbnail obtém a thumbnail da página (cache em WebP)

role é segment ou brushInpaint. POST /pages aceita um campo opcional replace=true; a importação é ordenada pelo nome de arquivo em ordem natural.

Cena e blobs

Método Path Finalidade
GET /scene.json snapshot completo da cena para clientes web/UI
GET /scene.bin Snapshot { epoch, scene } codificado em postcard para o cliente Tauri
GET /blobs/{hash} bytes brutos do blob por hash Blake3

/scene.bin inclui o epoch atual no header de response x-koharu-epoch.

Histórico (mutações)

Todas as mutações da cena passam por aqui. Cada response retorna { epoch }.

Método Path Finalidade
POST /history/apply aplica um Op (incluindo Op::Batch)
POST /history/undo reverte a última op aplicada
POST /history/redo reaplica a última op desfeita

Op é a união discriminada que cobre add/remove/update node, add/remove page, batch e outras transições da cena. O body é a variante com tag JSON.

Pipelines

Método Path Finalidade
POST /pipelines inicia uma execução de pipeline como uma operação

Campos do body:

  • steps — ids das engines a executar em ordem (validados contra o registry)
  • pages — subconjunto opcional de PageIds; omita para processar o projeto inteiro
  • region — bounding box opcional para o inpainter (fluxo de pincel de reparo)
  • targetLanguage, systemPrompt, defaultFont — overrides opcionais por execução

A response carrega um operationId. O progresso e a conclusão chegam em /events como JobStarted, JobProgress, JobWarning e JobFinished.

Operações

/operations é o registry unificado para jobs em andamento e recém-concluídos (pipelines + downloads).

Método Path Finalidade
GET /operations snapshot de toda operação em andamento ou recente
DELETE /operations/{id} cancela uma execução de pipeline; remoção best-effort para downloads

Downloads

Método Path Finalidade
GET /downloads snapshot de todo download ativo ou recente
POST /downloads inicia o download de um pacote de modelo ({ modelId })

modelId é um id de pacote declarado via declare_hf_model_package! (ex.: "model:comic-text-detector:yolo-v5"). A response é { operationId }, reutilizando o id do pacote.

Controle do LLM

O modelo carregado é um recurso singleton em /llm/current.

Método Path Finalidade
GET /llm/current estado atual (status, target, error)
PUT /llm/current carrega o target informado (local ou de provedor)
DELETE /llm/current descarrega / libera o modelo
GET /llm/catalog lista os modelos locais + de provedor disponíveis

PUT /llm/current aceita um LlmLoadRequest:

  • targets de provedor — { kind: "provider", providerId, modelId }
  • targets locais — { kind: "local", modelId }
  • options { temperature, maxTokens, customSystemPrompt } opcional

PUT /llm/current retorna 204 assim que a tarefa de carga é enfileirada. O estado pronto efetivo é publicado como LlmLoaded em /events.

Configuração

Método Path Finalidade
GET /config lê o AppConfig atual
PATCH /config aplica um ConfigPatch; persiste e faz broadcast
PUT /config/providers/{id}/secret salva (ou sobrescreve) a chave de API de um provedor
DELETE /config/providers/{id}/secret limpa a chave de API armazenada de um provedor

AppConfig expõe os top-level data, http, pipeline e providers:

  • data.path — diretório de dados local usado para runtime, cache de modelos e projetos
  • http { connectTimeout, readTimeout, maxRetries } — client HTTP compartilhado usado por downloads e requests baseados em provedor
  • pipeline { detector, fontDetector, segmenter, bubbleSegmenter, ocr, translator, inpainter, renderer } — id da engine selecionada para cada etapa
  • providers[] { id, baseUrl?, apiKey? } — chaves de API salvas vão e voltam como o placeholder redatado "[REDACTED]"; nunca o segredo bruto

Ids de provedores embutidos:

  • openai
  • gemini
  • claude
  • deepseek
  • deepl
  • google-translate
  • caiyun
  • openai-compatible

As chaves de API ficam armazenadas no credential store da plataforma, não em config.toml. Fazer PATCH de apiKey: "" limpa a chave salva; fazer PATCH de "[REDACTED]" mantém o valor inalterado. As rotas dedicadas /config/providers/{id}/secret são a forma explícita, fora do PATCH, de gerenciar o segredo de um provedor.

Stream de eventos

O Koharu expõe um stream de Server-Sent Events em:

GET /events

Comportamento:

  • uma conexão nova (sem header Last-Event-ID) começa com um evento Snapshot contendo os registries atuais de jobs e downloads
  • na reconexão, o servidor reenvia, em ordem, os eventos com seq > Last-Event-ID que ainda estão no buffer; se o id solicitado já saiu do ring, o servidor reenvia um Snapshot
  • cada evento ao vivo é emitido com seu seq no campo id: do SSE
  • um keepalive de 15 segundos é mantido

As variantes de evento atualmente incluem:

  • Snapshot — estado completo inicial para clientes novos e em recuperação de atraso
  • JobStarted, JobProgress, JobWarning, JobFinished — ciclo de vida do job de pipeline
  • DownloadProgress — ticks de progresso de download de pacote
  • ConfigChanged — config foi aplicada via PATCH /config ou via uma rota de segredo
  • LlmLoaded, LlmUnloaded — transições do ciclo de vida do LLM
  • SceneAdvanced — emitido quando uma mutação de cena avança o epoch

Workflow típico

A ordem normal da API para um projeto novo é:

  1. POST /projects — cria o projeto
  2. POST /pages (ou /pages/from-paths no Tauri) — importa as imagens
  3. PUT /llm/current — carrega um modelo de tradução (local ou de provedor)
  4. POST /pipelines — dispara detect → ocr → translate → inpaint → render
  5. acompanha GET /events até JobFinished
  6. POST /projects/current/export com format = "rendered" ou "psd"

Para controle mais fino, faça POST /history/apply com payloads Op explícitos em vez de rodar um pipeline completo.

Se você prefere acesso orientado a agentes em vez de orquestrar endpoints HTTP, veja a Referência das ferramentas MCP.