Visão Computacional V4
OCR de nova geração com transcrição de PDFs gráficos/escaneados via modelo de visão, página a página. Mantém o pipeline V3 para imagens, áudios, vídeos e páginas web.
Pipeline OCR V4. Mesma proposta da Visão Computacional V3 — receber mídias e devolver os campos definidos no schema — com suporte a PDFs gráficos/escaneados: PDFs sem camada de texto são renderizados página a página em imagem e transcritos por modelo de visão.
Rota nova e isolada. Não substitui /api/externalAPIs/public/tolkyOCR (V3), que continua disponível.
Endpoint
POST /api/externalAPIs/public/tolkyOCRV4
Parâmetros
URL ou array de URLs das mídias a processar. Suporta imagens, áudios, vídeos, documentos (PDF, DOCX, txt) e URLs de páginas web. Todos os itens são processados em paralelo.
Define quais campos extrair. Segue o formato de function calling do OpenAI. Se omitido, usa o schema padrão extract_media_description, que devolve apenas um campo description com tudo que foi identificado.
Instrução adicional livre para a etapa de extração do schema. Não influencia a transcrição em si — só o mapeamento das descrições para os campos finais.
Como funciona
V4 mantém a estrutura de duas etapas (analisar mídias → mapear para schema), mas troca o handler de documentos por um caminho que decide entre camada de texto e OCR de visão.
Pipeline por tipo de mídia
| Tipo | Detecção | V4 |
|---|---|---|
| PDF com texto | getMediaType + heurística hasMeaningfulText | Usa a camada de texto direto (rápido/barato) |
| PDF gráfico/escaneado | hasMeaningfulText retorna falso | Renderiza páginas em PNG via pdf-parse.getScreenshot e transcreve com gpt-4.1-nano (visão). Limite de 10 páginas por PDF — excedente é sinalizado como truncado |
| DOCX | getMediaType | mammoth |
Texto (text/*) | getMediaType | UTF-8 direto |
| Imagem / áudio / vídeo / página web | getMediaType + extractURLs | Reaproveita o pipeline V3 (getAllMediaAndUrlDescriptions) |
A transcrição de PDF escaneado entra direto como descrição (sem re-resumir), preservando fidelidade para a extração por schema.
A transcrição de PDF escaneado é a única diferença prática vs. V3. Para PDFs com camada de texto, imagens, áudios, vídeos e páginas web, V3 e V4 entregam resultado equivalente — V4 só adiciona o caminho novo, não muda o existente.
Quando usar V4 vs V3
- V4 — quando o input pode conter PDFs escaneados, fotografados ou de origem desconhecida.
- V3 — quando o input é controlado (apenas mídias digitais, PDFs com texto, páginas web). Custo igual.
Exemplos
PDF escaneado — extração de contrato
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCRV4 \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/contrato-escaneado.pdf"],
"schema": {
"name": "extract_contract",
"description": "Extrai partes, objeto e vigência de um contrato escaneado",
"parameters": {
"type": "object",
"properties": {
"contratante": { "type": "string" },
"contratado": { "type": "string" },
"objeto": { "type": "string", "description": "Objeto do contrato" },
"vigencia_inicio": { "type": "string" },
"vigencia_fim": { "type": "string" }
},
"required": ["contratante", "contratado", "objeto"]
}
},
"generalInstructions": "Foque nas cláusulas de identificação das partes e de prazo"
}'
Resposta:
{
"contratante": "Empresa ABC S.A.",
"contratado": "Fornecedor XYZ Ltda.",
"objeto": "Prestação de serviços de manutenção predial",
"vigencia_inicio": "01/04/2026",
"vigencia_fim": "31/03/2027"
}
Sem schema — descrição livre
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCRV4 \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/documento-escaneado.pdf"]
}'
Resposta:
{
"description": "Documento escaneado de duas páginas contendo um contrato de prestação de serviços entre Empresa ABC S.A. e Fornecedor XYZ Ltda., com vigência de 12 meses a partir de 01/04/2026."
}
Mix de tipos — PDF escaneado + áudio + página web
PDFs escaneados seguem o caminho de visão; áudio e página web são processados pelo pipeline V3 em paralelo. As descrições são consolidadas antes da extração do schema.
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCRV4 \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": [
"https://exemplo.com/comprovante-escaneado.pdf",
"https://exemplo.com/audio-cliente.ogg",
"https://exemplo.com/landing-do-produto"
],
"schema": {
"name": "consolidate_case",
"description": "Consolida o caso de atendimento a partir de comprovante, áudio do cliente e landing do produto",
"parameters": {
"type": "object",
"properties": {
"produto": { "type": "string" },
"valor_pago": { "type": "string" },
"reclamacao": { "type": "string" }
},
"required": ["produto", "valor_pago", "reclamacao"]
}
}
}'
Resposta
Objeto com os campos definidos no schema (equivalente ao parsedData da extração). Sem costSummary na resposta — o V4 retorna apenas os dados extraídos.
Se uma URL estiver inacessível, expirada ou se um PDF escaneado exceder 10 páginas, o conteúdo correspondente é sinalizado como truncado/ignorado e o restante segue. Se nenhuma mídia puder ser processada, a extração roda com dialogue vazio e os campos do schema podem voltar nulos.
Erros
| Código | Descrição |
|---|---|
400 | Parâmetros inválidos |
401 | Token inválido ou ausente |
500 | Erro durante OCR ou extração do schema (mensagem inclui originalError quando vinda do easyCaptureFromSchema) |