Você pode testar esta rota diretamente em nossa documentação interativa.

Versão “só particionar”: recebe um texto bruto, devolve blocos temáticos rotulados pela IA com { text, label, lines } e não toca em dataset ou chunks. Use partition quando também quiser persistir os blocos como chunks pesquisáveis.

​
Endpoint

POST /api/externalAPIs/public/smartSplit/split

​
Parâmetros

text
string

Texto a ser particionado. Obrigatório se mediaUrls não for fornecido.

mediaUrls
string[]

URLs de mídia (imagens, PDFs, áudio, vídeo) convertidas em texto antes do particionamento. Obrigatório se text não for fornecido; ambos podem ser enviados juntos — o texto das mídias é concatenado antes do text.

hostId
string

ID do host. Inferido do token quando omitido; obrigatório para tokens de master admin.

avatarId
string

ID do avatar usado como contexto da chamada.

options.generalInstructions
string

Instruções livres anexadas ao prompt da IA (ex: "Agrupe por tópico").

options.model
string
default: "gpt-4.1-nano"

Modelo LLM usado no particionamento.

options.provider
string
default: "openai"

Provedor do modelo LLM.

options.maxLinesPerSession
integer
default: "400"

Máximo de linhas por janela de sessão de IA.

options.overlapLines
integer
default: "30"

Linhas repetidas entre janelas adjacentes para continuidade de contexto.

options.minCoverage
number
default: "0.90"

Fração mínima de linhas que precisa ser coberta (0–1).

options.maxCharsPerChunk
integer
default: "80000"

Tamanho máximo em caracteres de cada sub-texto na pré-divisão de textos longos.

options.fallbackMaxCharsPerBlock
integer
default: "3000"

Tamanho máximo em caracteres de cada bloco gerado pelo fallback mecânico.

options.includeUncoveredLines
boolean
default: "true"

Quando true, a resposta inclui uncoveredLines com índices e texto das linhas fora de cobertura.

A API aceita tanto camelCase quanto snake_case nos parâmetros. text ou mediaUrls é obrigatório; ambos podem ser fornecidos simultaneamente.

​
Exemplo

curl -X POST {{BASE_URL}}/api/externalAPIs/public/smartSplit/split \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Título do documento\nIntrodução ao tema...\nDetalhes do produto X...\nEspecificações técnicas...\nPolítica de preços...\nCondições comerciais...",
    "options": {
      "generalInstructions": "Agrupe por tópico. Repita títulos nos blocos onde forem relevantes."
    }
  }'

​
Resposta

{
  "success": true,
  "blocks": [
    {
      "lines": [0, 1],
      "text": "Título do documento\nIntrodução ao tema...",
      "label": "Introdução"
    },
    {
      "lines": [0, 2, 3],
      "text": "Título do documento\nDetalhes do produto X...\nEspecificações técnicas...",
      "label": "Produto X"
    },
    {
      "lines": [0, 4, 5],
      "text": "Título do documento\nPolítica de preços...\nCondições comerciais...",
      "label": "Preços e condições"
    }
  ],
  "coverage": 1.0,
  "totalLines": 6,
  "sessionsUsed": 1,
  "fallbackUsed": false,
  "failedSessions": 0,
  "reasoning": "Agrupado por tópico, repetindo o título em cada bloco.",
  "auditLog": [
    "[SmartSplit] Iniciando particionamento de texto...",
    "[SmartSplit] Particionamento concluído com sucesso"
  ],
  "uncoveredLines": { "count": 0, "indices": [], "ranges": [], "lines": [] },
  "costControl": {
    "usage": {
      "inputTokens": 320,
      "outputTokens": 85,
      "totalTokens": 405,
      "isEstimated": false,
      "source": "smart_split_aggregate"
    },
    "cost": {
      "inputCost": 0.000032,
      "outputCost": 0.000034,
      "totalCost": 0.000066,
      "currency": "USD",
      "pricingMissing": false,
      "matchedPricingKey": "openai:gpt-4.1-nano"
    },
    "control": { "decision": "allow", "reasons": [] },
    "references": { "caller": "smartSplit", "provider": "openai", "model": "gpt-4.1-nano" },
    "reconciliation": null
  }
}

​
Campos da Resposta

success
boolean

true quando a cobertura atinge o limiar e não houve erro fatal.

blocks
object[]

Blocos resultantes do particionamento.

coverage
number

Fração das linhas originais cobertas pelos blocos (0–1).

totalLines
integer

Número total de linhas do texto de entrada.

sessionsUsed
integer

Número de sessões de IA consumidas.

fallbackUsed
boolean

true quando ao menos uma janela precisou usar divisão mecânica em vez de IA.

failedSessions
integer

Número de janelas que retornaram 0 blocos e acionaram o fallback.

reasoning
string | null

Última reasoning do modelo, quando disponível.

auditLog
string[]

Rastro passo a passo do particionamento.

uncoveredLines
object

Linhas do input que não foram cobertas por nenhum bloco. Presente quando options.includeUncoveredLines: true (padrão).

costControl
object | null

Dados de consumo e custo da operação. null em erros internos.

​
Erros

CódigoDescrição
400text e mediaUrls ausentes ou vazios; hostId não resolvível
401Token inválido ou ausente
500Falha do LLM não recuperável após fallback

Quando a cobertura fica abaixo do limiar, a resposta volta com HTTP 200, success: false e reason: "coverage_below_threshold" junto com os blocos parciais.

O pipeline interno é o mesmo de partition — janelas deslizantes de 400 linhas com 30 de overlap, cobertura mínima de 90% e fallback mecânico quando a IA falha. Veja Como funciona.

Particionar textoConverter para texto