Visão Computacional
Extrai informações estruturadas de imagens, áudios, vídeos, documentos e páginas web usando um pipeline multi-modelo com GPT-4.1, Whisper e Gemini 2.0 Flash
Envie qualquer combinação de mídias e receba de volta os campos exatos que você definiu no schema — transcrito, descrito e estruturado em JSON. Cada tipo de mídia passa por um modelo especializado antes da extração.
Endpoint
POST /api/externalAPIs/public/tolkyOCR
Parâmetros
URL ou array de URLs das mídias a processar. Suporta imagens, áudios, vídeos, documentos (PDF, DOCX, etc.) e URLs de páginas web. Todos os itens são processados em paralelo.
Define quais campos extrair do conteúdo das mídias. Segue o formato de function calling do OpenAI. Se omitido, retorna um campo description com tudo que foi identificado.
Instrução adicional livre para guiar a extração. Exemplo: "Foque nos valores monetários e datas". Aplicado no momento da extração do schema, não durante a análise das mídias.
Como funciona
O serviço opera em duas etapas: primeiro analisa cada mídia com o modelo mais adequado para o tipo, depois usa um LLM de extração para mapear as descrições resultantes para os campos do schema.
Modelo por tipo de mídia
| Tipo | Detecção | Processamento |
|---|---|---|
| Imagem (jpg, png, webp, gif…) | Content-Type + extensão | GPT-4.1-nano (visão) |
| Áudio (mp3, ogg, wav, m4a…) | Content-Type + extensão | Whisper (transcrição exata) + Gemini 2.0 Flash (descrição contextual) |
| Vídeo (mp4, webm, mov…) | Content-Type + extensão | Gemini 2.0 Flash |
| Documento (pdf, docx, xlsx…) | Content-Type + extensão | GPT-4.1-nano — com SmartCut automático para documentos acima de 40 mil caracteres |
| Página web (URL sem extensão de mídia) | Heurística de URL | Crawler + LLM de descrição |
O modelo de extração do schema escala com a complexidade: schemas com até 3 campos usam gpt-4.1-nano; schemas maiores usam gpt-4.1-mini.
Áudio é o tipo com mais saída: a resposta inclui tanto a transcription (texto literal via Whisper) quanto a description (tom, emoções, sons de fundo via Gemini). Ambas ficam disponíveis para o schema de extração.
Exemplos
Imagem — leitura de placa ou documento visual
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCR \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/comprovante.jpg"],
"schema": {
"name": "extract_receipt",
"description": "Extrai dados de um comprovante de pagamento",
"parameters": {
"type": "object",
"properties": {
"valor": { "type": "string", "description": "Valor total pago" },
"data": { "type": "string", "description": "Data da transação" },
"destinatario": { "type": "string", "description": "Nome ou instituição destinatária" }
},
"required": ["valor", "data", "destinatario"]
}
}
}'
Resposta:
{
"data": {
"valor": "R$ 1.250,00",
"data": "28/03/2026",
"destinatario": "Empresa Exemplo Ltda"
},
"costSummary": {
"totalInputTokens": 420,
"totalOutputTokens": 55,
"callers": ["describeImg", "easyCaptureFromSchema:tolkyOCR"]
}
}
Áudio — transcrição e análise de mensagem de voz
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCR \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/audio.ogg"],
"schema": {
"name": "analyze_voice_message",
"description": "Transcreve o áudio e identifica a intenção principal do falante",
"parameters": {
"type": "object",
"properties": {
"transcricao": { "type": "string", "description": "Texto literal do áudio" },
"intencao": { "type": "string", "description": "Intenção principal detectada" },
"tom": { "type": "string", "description": "Tom emocional: neutro, urgente, satisfeito, insatisfeito" }
},
"required": ["transcricao", "intencao", "tom"]
}
}
}'
Resposta:
{
"data": {
"transcricao": "Oi, queria confirmar se meu pedido já foi enviado. Faz três dias e ainda não recebi nenhuma atualização.",
"intencao": "Consulta sobre status de pedido",
"tom": "insatisfeito"
},
"costSummary": {
"totalInputTokens": 680,
"totalOutputTokens": 72,
"callers": ["describeAudio", "easyCaptureFromSchema:tolkyOCR"]
}
}
Vídeo — extração de informações de um vídeo de apresentação
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCR \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/apresentacao.mp4"],
"schema": {
"name": "summarize_video",
"description": "Resume o conteúdo de um vídeo de apresentação comercial",
"parameters": {
"type": "object",
"properties": {
"resumo": { "type": "string", "description": "Resumo do que foi apresentado" },
"produtos_mencionados": {
"type": "array",
"items": { "type": "string" },
"description": "Lista de produtos ou serviços citados"
}
},
"required": ["resumo", "produtos_mencionados"]
}
}
}'
Resposta:
{
"data": {
"resumo": "Apresentação de 3 minutos demonstrando o módulo de automações da plataforma, com foco em integração com WhatsApp e envio de campanhas segmentadas.",
"produtos_mencionados": ["Automações", "Campanhas", "Integração WhatsApp"]
},
"costSummary": {
"totalInputTokens": 1240,
"totalOutputTokens": 98,
"callers": ["describeVideo", "easyCaptureFromSchema:tolkyOCR"]
}
}
Documento — análise de PDF
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCR \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": ["https://exemplo.com/contrato.pdf"],
"schema": {
"name": "extract_contract_parties",
"description": "Extrai as partes e a vigência de um contrato",
"parameters": {
"type": "object",
"properties": {
"contratante": { "type": "string", "description": "Nome do contratante" },
"contratado": { "type": "string", "description": "Nome do contratado" },
"vigencia_inicio": { "type": "string", "description": "Data de início da vigência" },
"vigencia_fim": { "type": "string", "description": "Data de término da vigência" }
},
"required": ["contratante", "contratado", "vigencia_inicio", "vigencia_fim"]
}
},
"generalInstructions": "Foque nas cláusulas de identificação das partes e de prazo"
}'
Resposta:
{
"data": {
"contratante": "Empresa ABC S.A.",
"contratado": "Fornecedor XYZ Ltda.",
"vigencia_inicio": "01/04/2026",
"vigencia_fim": "31/03/2027"
},
"costSummary": {
"totalInputTokens": 2100,
"totalOutputTokens": 60,
"callers": ["describeDocument", "easyCaptureFromSchema:tolkyOCR"]
}
}
Múltiplas mídias — análise combinada
É possível misturar tipos na mesma chamada. Todos são processados em paralelo e as descrições são consolidadas antes da extração do schema.
curl -X POST {{BASE_URL}}/api/externalAPIs/public/tolkyOCR \
-H "Authorization: Bearer {{TOKEN}}" \
-H "Content-Type: application/json" \
-d '{
"files": [
"https://exemplo.com/foto-produto.jpg",
"https://exemplo.com/audio-cliente.ogg"
],
"schema": {
"name": "match_complaint_to_product",
"description": "Relaciona a reclamação do áudio com o produto identificado na imagem",
"parameters": {
"type": "object",
"properties": {
"produto_identificado": { "type": "string" },
"reclamacao": { "type": "string" },
"acao_sugerida": { "type": "string" }
},
"required": ["produto_identificado", "reclamacao", "acao_sugerida"]
}
}
}'
Resposta
Objeto com os campos definidos no schema. Se nenhum schema foi enviado, contém um único campo description com tudo que foi identificado nas mídias.
Resumo do custo computacional da requisição.
Se uma URL estiver inacessível ou expirada, o item correspondente é ignorado silenciosamente e os demais continuam sendo processados. O campo data reflete apenas as mídias que foram processadas com sucesso. Se nenhuma mídia puder ser processada, data é null.
Erros
| Código | Descrição |
|---|---|
400 | Parâmetro files ausente ou vazio |
401 | Token inválido ou ausente |
500 | Erro interno durante o processamento |