SmartCut
Reduza e particione conteúdos longos com ou sem IA, via endpoint único
O SmartCut recebe um conteúdo grande e devolve partes mais úteis para consumo em LLM, RAG e análises.
Você pode enviar texto direto, referência de asset existente ou URL de mídia para transcrição e processamento.
Para exemplos prontos de implementação, veja SmartCut - Casos de uso.
Endpoint
POST /api/externalAPIs/public/smartCut/lineSplit
Autenticação: Authorization: Bearer {TOKEN}
Parâmetros
ID do host para rastreamento de custo e execução
Texto bruto para processar diretamente
ID de um asset já existente para processar transcrição ou resumo
Alias de asset_id
URL de mídia para criação de asset e processamento
ID do avatar para contexto da seleção por IA
Método de divisão: default, sentence-parse, semantic-chunking ou chonkiejs
Ativa seleção inteligente de trechos com IA
Instruções para a IA decidir quais trechos manter (obrigatório quando useAI=true)
Modelo LLM a ser usado na etapa de seleção
Provedor do modelo LLM
Padrão regex customizado para dividir o texto em linhas (substitui o padrão do método selecionado)
Critérios automáticos para decidir se o SmartCut deve rodar. Se o gate reprovar, o texto original é devolvido via pass-through com skippedByRoiGate: true.
Estratégia para URL: force_transcription ou prefer_summary
Modelo LLM que receberá o conteúdo resultante — usado para estimar economia de tokens e custo
Provedor LLM correspondente ao intentModel
Alias de options.roiGate.targetModel — modelo downstream para cálculo de viabilidade do ROI Gate
Alias de options.roiGate.targetProvider — provedor do targetModel
Envie exatamente uma fonte de entrada: text ou asset_id/assetId ou url.
Exemplo
curl -X POST "{{BASE_URL}}/api/externalAPIs/public/smartCut/lineSplit" \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"hostId": "1754b7e6-dbd7-4ca3-a843-7f06fad4e4c0",
"method": "sentence-parse",
"text": "Primeira frase. Segunda frase com produto X. Terceira frase.",
"intentModel": "gpt-4o-mini",
"intentProvider": "openai",
"options": {
"useAI": true,
"generalInstructions": "Mantenha apenas frases sobre produto ou serviço.",
"model": "gpt-4o-mini",
"provider": "openai",
"roiGate": {
"maxContextChars": 8000
}
}
}'
Resposta
{
"data": {
"success": true,
"lines": [
"Segunda frase com produto X."
],
"allLines": [
"Primeira frase.",
"Segunda frase com produto X.",
"Terceira frase."
],
"intervals": [
[1, 1]
],
"requestControlId": "50baaf6c-5f50-4add-9df3-3f2abc8fd067",
"savingsReport": {
"intentModel": "gpt-4o-mini",
"intentProvider": "openai",
"originalTokens": 1200,
"selectedTokens": 480,
"savedTokens": 720,
"savingsPct": 60.0,
"originalCostUsd": 0.00000018,
"selectedCostUsd": 0.000000072,
"savedCostUsd": 0.000000108,
"pricingMissing": false
},
"error": null,
"auditLog": [
"lineSplitter started",
"AI selection completed"
]
}
}
Campos da Resposta
Indica se o processamento terminou com sucesso
Linhas ou chunks finais retornados pelo SmartCut
Todas as linhas geradas antes do filtro por IA
Intervalos selecionados quando useAI=true
Identificador de rastreamento de execução e custo
Mensagem de erro quando houver falha
Eventos resumidos do ciclo de processamento
Relatório de economia estimada para o modelo/provedor informado. null quando intentModel ou intentProvider não são fornecidos.
Presente quando o ROI Gate decide retornar pass-through
Motivo textual para o skip do ROI Gate
Estimativas calculadas pelo ROI Gate. Presente quando o gate é avaliado (mesmo que skippedByRoiGate seja false).
Erros
| Código | Descrição |
|---|---|
400 | Campos obrigatórios ausentes, fonte de entrada inválida ou combinações não permitidas |
401 | Token inválido ou ausente |
404 | Asset não encontrado |
500 | Erro interno do servidor |
Métodos de divisão
| Método | Quando usar |
|---|---|
default (regex) | Texto geral com divisão rápida e baixo custo |
sentence-parse | Conteúdo com pontuação irregular, HTML, Markdown e listas |
semantic-chunking | Contextos longos para RAG e leitura por LLM |
chonkiejs | Controle fino de chunking com limites personalizados |
ROI Gate na prática
O ROI Gate avalia automaticamente se vale executar o SmartCut antes de processar. Quando o gate reprova, o texto original é devolvido via pass-through sem custo de IA.
Ordem de decisão do gate:
- Texto vazio →
run=false - Texto já cabe (
chars ≤ maxContextCharsoutokensEst ≤ maxContextTokens) →run=false useAI=false→run=true(split sem IA é barato, gate não bloqueia)- Custo do SmartCut > 50% do custo de input do modelo alvo →
run=false - Retenção prevista ≥ 65% →
run=false(pouco seria removido) - Economia estimada <
minimumSavingsRatio→run=false - ROI total não fecha (custo ≥ break-even) →
run=false - Custo >
budget→run=false
Use options.roiGate.skip: true para desabilitar completamente o gate e sempre executar.
Quando o gate pular a execução, a resposta inclui skippedByRoiGate: true, roiGateReason com o motivo e roiGateEstimates com as estimativas calculadas.
Casos comuns
- Reduzir contexto antes de enviar para
ragSearch - Filtrar apenas trechos relevantes em análises (
docAnalyzer,analyzeDialogue) - Processar mídia via URL sem criar fluxo manual de transcrição