PDF to Visual Struct

Visão geral

O PDF to Visual Struct converte uma página de PDF no Visual Element Schema da Codia: uma árvore JSON hierárquica de elementos de UI tipados, com bounding boxes, configurações de layout e especificações de estilo. O schema é o mesmo formato que alimenta o Codia Studio, então consumidores downstream — importadores do Figma, geradores de código, pipelines de QA visual — podem trabalhar com uma única forma de dados estável.

Endpoint

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

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

Requisição

A requisição é multipart/form-data.

Campo	Tipo	Obrigatório	Descrição
`pdf_file`	file	sim	O arquivo PDF a converter. Um arquivo por requisição.
`page_no`	string	sim	Número da página indexado em zero. Faça loop no lado do cliente para conversão de múltiplas páginas.

Exemplo

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"xx.pdf"' \
  --form 'page_no="0"'

Resposta

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* elemento raiz */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

Campos de nível superior

Campo	Descrição
`configuration.baseWidth`	Largura de referência usada ao resolver o layout. Escale os bounding boxes em relação a este valor ao renderizar em uma largura de viewport diferente.
`configuration.measurementUnit`	Unidade de coordenada — tipicamente `px`.
`configuration.scalingFactor`	Fator de escala pré-aplicado. Geralmente `1`.
`size.width`, `size.height`	O canvas da página resolvido no sistema de coordenadas base.
`pages[].visualElement`	O elemento raiz da árvore da página. Percorra `childElements` recursivamente.

Visual Element Schema

Cada nó na árvore tem o mesmo formato:

json

{
  "elementId": "pdf_page_1",
  "elementName": "PDF Document Page",
  "elementType": "Panel",
  "displayName": "First Page",
  "displayOrder": 0,
  "boundingBox": [0, 0, 595, 842],
  "layoutConfig": {
    "positionMode": "Normal",
    "flexibleMode": "Absolute"
  },
  "styleConfig": {
    "widthSpec":  { "sizing": "FIXED", "value": 595 },
    "heightSpec": { "sizing": "FIXED", "value": 842 },
    "backgroundSpec": {
      "type": "COLOR",
      "backgroundColor": { "rgbValues": [255, 255, 255] }
    }
  },
  "processingMeta": {
    "surfaceArea": 501490,
    "detectionScore": 0.92,
    "textContainerized": false
  },
  "childElements": []
}

Referência de campos

Campo	Descrição
`elementId`	Identificador estável dentro desta resposta. Não é globalmente único entre páginas.
`elementType`	Classe tipada do elemento: `Panel`, `Text`, `Image`, `Icon`, `Button`, `Table`, `Chart` e mais de 50 outros.
`boundingBox`	`[x, y, width, height]` em coordenadas base.
`layoutConfig.positionMode`	`Normal` (flow) ou `Absolute`.
`layoutConfig.flexibleMode`	`Row`, `Column` ou `Absolute` — espelha a semântica de auto-layout do Figma.
`styleConfig.widthSpec.sizing`	`FIXED`, `FILL_CONTAINER` ou `HUG_CONTENT`.
`styleConfig.backgroundSpec`	Preenchimento de fundo — cor, gradiente ou imagem.
`processingMeta.detectionScore`	Confiança do detector, `0.0` – `1.0`. Filtre nós de baixa confiança antes do uso downstream.
`childElements`	Array de Visual Elements filhos. Travessia em profundidade revela a hierarquia completa.

Limites

Configuração	Padrão
Tamanho máximo de arquivo	50 MB
Máximo de páginas por documento	100
Máximo de requisições por minuto	Depende do plano — veja preços.
Latência típica por página	600 ms – 2 s

Entradas suportadas

PDFs text-native (exportados de ferramentas de design, suítes de escritório ou gerados programaticamente) — maior fidelidade.
PDFs escaneados — OCR é aplicado automaticamente; espere mais ruído em digitalizações de baixa resolução.
PDFs protegidos por senha não são suportados. Desbloqueie antes de fazer upload.

Padrões comuns

Conversão de múltiplas páginas

Faça loop de page_no de 0 até o comprimento do documento, em paralelo até o limite de concorrência do seu plano:

const pages = await Promise.all(
  pageNumbers.map((n) => fetch(ENDPOINT, buildRequest(file, n))),
)

Filtrar nós de baixa confiança

function prune(node, minScore = 0.6) {
  node.childElements = (node.childElements || [])
    .filter((c) => c.processingMeta.detectionScore >= minScore)
    .map((c) => prune(c, minScore))
  return node
}

Ida e volta com Figma

Como layoutConfig espelha o auto-layout do Figma, a árvore pode ser importada como frames de auto-layout diretamente. Use o plugin PDF to Design para Figma se não quiser construir o importador você mesmo.

FAQ

Posso converter todas as páginas em uma única chamada?

Não em uma única chamada — o endpoint é por página. Faça loop e paralelize do seu lado.

Qual a precisão da conversão?

A qualidade real de reconhecimento depende da origem do PDF, da clareza do texto e da complexidade estrutural. Formulários legais escaneados e entradas anotadas à mão tendem a ser mais difíceis; sempre inspecione processingMeta.detectionScore.

As fontes são preservadas?

Nomes de fontes, tamanhos, pesos e cores são preservados em styleConfig. Renderizar a fonte preservada requer que a fonte esteja instalada onde você consome a saída.

Existe um SDK?

Nenhum SDK é necessário — a API é HTTP + JSON puro. Um SDK oficial está no roadmap.

Posso implantar on-premises?

Sim, para planos enterprise. Entre em contato com [email protected].

Próximos passos

Visual Struct — mesmo schema, entrada de imagem.
Remove BG — imagens com fundo transparente para composição na saída renderizada.
Referência completa do endpoint em /api#convert-pdf-to-design.