Da Captura de Tela à Estrutura: Construindo com a API Visual Struct

Engineering2026-04-23

Por que "estrutura" é a unidade que importa

Uma captura de tela de UI é, para um computador, uma grade de pixels. Para um designer ou desenvolvedor humano, é um card com um título, um preço, uma avaliação, um botão. Fazer a ponte entre essas duas visões — transformar pixels em uma árvore de elementos nomeados e tipados — é o que a API Visual Struct faz.

Envie uma imagem. Receba de volta uma descrição JSON hierárquica de cada elemento de UI que ela contém, cada um com um tipo, bounding box, conteúdo de texto e relação de layout com seu pai. É isso. Sem engenharia de prompt, sem rotulagem manual, sem boilerplate de visão computacional do seu lado.

Vimos equipes usarem essa saída para importar automaticamente capturas de tela de concorrentes para o Figma, para alimentar suítes de regressão visual em apps mobile, para indexar capturas de tela para busca por IA e para gerar código direto de uma imagem do Dribbble. Este post é sobre o que a API realmente retorna e como construir em cima dela.

O formato da resposta

Todo elemento tem os mesmos campos essenciais. Aqui está um cabeçalho recortado de uma captura de tela de landing page:

json

{
  "elementId": "header_section_001",
  "elementName": "HeaderSection",
  "elementType": "header",
  "displayName": "Header Section",
  "layoutConfig": {
    "positionMode": "flex",
    "flexibleMode": "row",
    "flexAttributes": {
      "justifyContent": "space-between",
      "alignItems": "center"
    }
  },
  "boundingBox": [0, 0, 1440, 88],
  "childElements": [
    { "elementType": "logo", /* ... */ },
    { "elementType": "nav",  /* ... */ },
    { "elementType": "button", "displayName": "Sign Up", /* ... */ }
  ]
}

Algumas coisas a notar:

elementType é a chave primária para programar. A API reconhece dezenas de tipos — header, button, input, card, badge, icon, tab, table, chart, entre outros — e o conjunto é treinado com milhões de UIs reais.
layoutConfig captura a forma como os filhos se organizam dentro do seu pai. Quando o detector vê uma linha de elementos com centros verticais iguais e espaçamento similar, ele emite um flex row com o justifyContent apropriado. Elementos posicionados livremente recebem absolute. Você obtém um grafo de layout, não apenas um saco de caixas.
childElements é recursivo. A imagem inteira é uma única árvore enraizada em um container de página, e você pode percorrê-la em profundidade para renderizar, comparar ou indexar.
Texto é tratado por uma etapa de OCR multilíngue — 50+ idiomas inclusos — e as strings reconhecidas ficam em seu container correto, não como runs de texto flutuantes.

Como precisão e velocidade são medidas

A qualidade real de correspondência de elementos depende do tipo de interface, da clareza da captura de tela e da complexidade estrutural. A latência ponta a ponta é influenciada por resolução, densidade de texto e estado da fila; a disponibilidade segue o status atual do serviço e o acordo aplicável.

Os bounding boxes são precisos ao pixel no sentido de que o IoU (interseção sobre união) da caixa comparado com ground truth anotado por humanos é em média acima de 0,9 para elementos visualmente distintos. Texto aninhado dentro de layouts apertados — pense em uma tabela de dados com seis colunas — é onde você verá mais desvio, e onde o detectionScore de cada elemento se prova útil: filtre a cauda longa de nós de baixa confiança antes do uso downstream.

Formatos de saída

A resposta padrão é JSON. Dois formatos alternativos estão disponíveis na mesma família de endpoints:

SVG — uma re-renderização vetorial da cena detectada. Útil quando você quer uma versão sem perda e editável da captura de tela que não esteja vinculada a uma ferramenta de design específica.
Nós compatíveis com Figma — uma árvore formatada para inserção direta em um arquivo Figma via REST API ou plugin. É isso que o plugin Codia para Figma consome.

A versão JSON é a mais flexível; as saídas SVG e Figma são wrappers de conveniência que pós-processam o mesmo schema subjacente.

Cinco coisas para construir

1. Pipeline captura de tela para Figma. Você provavelmente já viu isso: solte uma imagem em um plugin e receba um arquivo Figma totalmente editável. O plugin é um thin client sobre a API. Se você está fazendo ingestão de design dentro da sua própria ferramenta, pule o plugin e chame a API diretamente.

2. QA visual em escala. Em vez de comparar pixels de capturas de tela entre execuções de CI, compare suas árvores de elementos. Diffs em nível de elemento ignoram diferenças de renderização subpixel, fallbacks de fonte e ruído de anti-aliasing, e fornecem diffs que um humano pode realmente ler: "botão 'Continuar' moveu 12px para a direita, ganhou um border-radius de 4px."

3. Indexação semântica para busca por IA. Se você está construindo um produto tipo Pinterest-para-UI — ou apenas quer que sua equipe de design consiga buscar "dashboards dark mode com sparklines" — o schema fornece estrutura consultável. Indexe tipos de elementos, cores e conteúdo de texto em vez de imagens brutas.

4. Lint de acessibilidade para imagens. Uma captura de tela não é acessível; uma árvore de elementos tipados pode ser. Alimente o JSON em um verificador de acessibilidade para identificar texto alternativo ausente, combinações de baixo contraste ou botões sem rótulo em designs que existem como PNGs em tickets.

5. Geração de código a partir de capturas de tela. Como o schema compartilha semântica com nossos pipelines de PDF e design, você pode encaminhá-lo diretamente para os geradores de código da Codia para produzir React, Vue, Flutter ou HTML/Tailwind. A mesma árvore que descreve uma imagem também gera a UI.

Lidando com casos extremos

Algumas notas práticas de integrações:

Capturas de tela muito longas (como capturas de página inteira de sites de marketing) ficam melhores quando divididas em limites naturais de seção. O modelo ainda funciona em imagens de 10k pixels de altura, mas você obterá agrupamentos mais estáveis fragmentando.
UIs em modo escuro são bem suportadas — o detector não depende de suposições sobre o fundo — mas se uma captura de tela é um tema escuro renderizado de um design light mode, espere que as cores extraídas reflitam o que está na tela, não os valores de token por trás delas.
Mockups desenhados à mão ou em fidelidade de sketch funcionam, embora a distribuição de elementType tenda para nós genéricos de container e text até que o sketch seja refinado.
Múltiplas regiões roláveis aninhadas (um painel lateral que rola dentro de uma página que rola) são achatadas em uma única árvore. O modelo não tem conceito de scroll; modele isso do seu lado.

Primeiros passos

bash

curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "image_url": "https://example.com/ui.png" }'

Obtenha uma chave em codia.ai/dashboard/developer.
Envie uma imagem (URL ou base64). Uma captura de tela desktop de 1440x900 é o ponto ideal.
Percorra a árvore. Se você se importa apenas com elementos acima de um limiar de confiança, pré-filtre com processingMeta.detectionScore > 0.6 e ignore o ruído.
Referência completa — definições de schema, limites de taxa, códigos de erro — está em /api.

Se você está considerando isso para uma carga de trabalho empresarial — on-prem, região privada ou tipos de elementos customizados específicos do seu produto — [email protected] é a porta certa. O modelo é o mesmo; a embalagem muda.

UIs vão continuar sendo capturadas como imagens — em relatórios de bug, em threads do Slack, em shots do Dribbble, em pesquisa de concorrentes. Trate essas imagens como estrutura consultável e você desbloqueia uma pilha de trabalho que antes precisava ser feito manualmente.

#visual-struct#api#computer-vision#ocr#design-tooling

← Ver todos os artigos