Visual Struct

Visão geral

O Visual Struct recebe uma captura de tela de UI ou mockup e retorna uma descrição JSON hierárquica de cada elemento que ela contém. Cada elemento é tipado (header, button, card, table, etc.), posicionado (bounding box preciso em pixels) e vinculado ao seu pai, de modo que toda a imagem é representada como uma única árvore.

O schema é compartilhado com o PDF to Visual Struct, então consumidores downstream podem aceitar ambas as entradas através de um único caminho de código.

Endpoint

POSThttps://api.codia.ai/v1/open/image_to_design

A autenticação é via bearer token. Obtenha uma chave em codia.ai/dashboard/developer.

Requisição

Campo	Tipo	Obrigatório	Descrição
`image_url`	string	sim (ou `image_base64`)	URL publicamente acessível da imagem de origem.
`image_base64`	string	sim (ou `image_url`)	Dados da imagem codificados em Base64.
`output_format`	string	não	`json` (padrão), `svg` ou `figma`.

Exemplo

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

Resposta

json

{
  "elementId": "header_section_001",
  "elementName": "HeaderSection",
  "elementType": "header",
  "displayName": "Header Section",
  "layoutConfig": {
    "positionMode": "flex",
    "flexibleMode": "row",
    "flexAttributes": {
      "justifyContent": "space-between",
      "alignItems": "center"
    }
  },
  "childElements": [ /* elementos aninhados */ ]
}

Referência de campos

Campo	Descrição
`elementType`	Classe do elemento — `header`, `button`, `card`, `badge`, `icon`, `tab`, `table`, `chart` e outros.
`layoutConfig.positionMode`	`flex` ou `absolute`. Containers flex expõem `flexibleMode` (`row` / `column`) e `flexAttributes`.
`boundingBox`	`[x, y, width, height]` em coordenadas de pixel da imagem de origem.
`processingMeta.detectionScore`	Confiança de 0 a 1.
`childElements`	Array recursivo de elementos filhos.

Formatos de saída

Formato	Caso de uso
`json`	Padrão. Melhor para pipelines downstream customizados.
`svg`	Re-renderização vetorial sem perda da cena detectada, agnóstica a ferramentas de design.
`figma`	Árvore formatada para inserção direta em um arquivo Figma via REST API ou plugin.

Todos os três formatos são pós-processados a partir do mesmo schema subjacente.

Capacidades

Capacidade	Valor
Qualidade de correspondência de elementos	Depende da clareza e complexidade estrutural do arquivo de origem
Latência típica	2–5 s por imagem
Idiomas de OCR	50+
Tamanho máximo de imagem	25 MB
Resolução recomendada	600–4000 px no lado maior
Disponibilidade	Conforme o status atual do serviço e o acordo aplicável

Padrões comuns

Filtrar por confiança

function visibleElements(tree, threshold = 0.6) {
  const out = []
  const walk = (n) => {
    if ((n.processingMeta?.detectionScore ?? 1) >= threshold) {
      out.push(n)
      ;(n.childElements ?? []).forEach(walk)
    }
  }
  walk(tree)
  return out
}

Capturas de tela longas

Capturas de tela de marketing de página inteira (10k+ pixels de altura) funcionam, mas fragmentar em limites de seção antes de chamar produz agrupamentos de nível superior mais estáveis.

UIs em modo escuro

O detector não depende de suposições sobre o fundo. As cores extraídas refletem os pixels renderizados — se você precisa de tokens semânticos (a cor da marca como declarada, não como pintada), mapeie de volta para seu sistema de tokens do seu lado.

FAQ

O que acontece com UIs em múltiplos idiomas?

O OCR detecta o idioma por bloco de texto, então uma interface com controles em inglês e texto do corpo em japonês é tratada corretamente em uma única requisição.

A API mantém as imagens enviadas?

As imagens são retidas apenas o tempo suficiente para completar a requisição e gerar a URL de resposta. A retenção pode ser customizada para implantações enterprise.

Posso executar on-premises?

Sim — o mesmo modelo é entregue como um container isolado para empresas. Entre em contato com [email protected].

Como lidar com regiões roláveis?

A API retorna uma árvore plana; ela não tem conceito de overflow de scroll. Anote a rolagem do seu lado com base em padrões de UI conhecidos ou overflow de elementos.

Próximos passos

PDF to Visual Struct — mesmo schema, entrada de PDF.
Design to Code — encaminhe o schema para geração de código.
Referência completa do endpoint em /api.