Quickstart da API de Ingestão

Envie um arquivo e inicie um trabalho de ingestão em três chamadas HTTP.

21 de mai. de 2026

A API de Ingestão transforma um arquivo bruto (PDF, imagem, áudio, texto) em um documento pesquisável na sua Biblioteca Vulgate. É um processo de duas etapas: envie o arquivo, depois inicie um trabalho de ingestão.

A referência completa está em /developers/ingest/overview. Este guia passa pelo mínimo necessário para enviar seu primeiro arquivo via código.

Passo 1 — Solicitar uma URL de upload assinada

O Vulgate usa URLs de armazenamento assinadas para que uploads de arquivos ignorem o servidor da API completamente. Primeiro, solicite uma URL de /api/uploads:

curl -G "https://vulgate.ai/api/uploads" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "name=artigo-pesquisa.pdf" \
  --data-urlencode "type=application/pdf"

Resposta:

{
  "url": "https://...signed-storage-url...",
  "method": "PUT",
  "headers": {
    "content-type": "application/pdf",
    "x-amz-meta-name": "artigo-pesquisa.pdf"
  }
}

Guarde o ID do arquivo retornado nos cabeçalhos (x-amz-meta-name junto com a parte do caminho da URL) — você precisará dele no passo 3. A URL assinada é válida por uma janela curta.

Passo 2 — Enviar o arquivo para a URL assinada

Envie o corpo do arquivo como um PUT para a URL assinada com os cabeçalhos do passo 1. Não inclua o cabeçalho de autenticação do Vulgate aqui — a assinatura cuida da autenticação:

curl -X PUT "<signed-url-do-passo-1>" \
  -H "Content-Type: application/pdf" \
  -H "X-Amz-Meta-Name: artigo-pesquisa.pdf" \
  --data-binary @artigo-pesquisa.pdf

O serviço de armazenamento responde com HTTP 200 e nenhum corpo quando bem-sucedido.

Passo 3 — Iniciar um trabalho de ingestão

Diga ao Vulgate para começar a processar o arquivo enviado fazendo POST para /api/jobs com o ID do arquivo do passo 1:

curl -X POST "https://vulgate.ai/api/jobs" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{ "id": "<id-arquivo-do-passo-1>" }],
    "ingest_mode": "standard"
  }'

ingest_mode seleciona o nível de processamento: "standard" (o padrão — OCR rápido, 1 crédito/página, todos os tipos de arquivo) ou "pro" (extração por modelo de visão para digitalizações difíceis, 5 créditos/página, apenas PDF e imagens). Veja a referência completa de parâmetros para as outras opções — pipeline, escopo, metadados do documento e processamento de áudio.

O trabalho roda em segundo plano. Uma vez concluído, o documento é pesquisável — chame a API de Busca ou API de Chat para interagir com ele.

Uploads multipart para arquivos grandes

O fluxo de arquivo único acima funciona bem para arquivos típicos. Para arquivos muito grandes, use os endpoints multipart (POST /api/uploads). Veja Enviando arquivos para a referência completa.

Relacionados

Pesquisar ajuda