Extração

Use a Extração para transformar texto, imagens e PDFs em JSON moldado por um esquema que você define. Ela se adapta a faturas, recibos, formulários, contratos e outros documentos onde seu aplicativo precisa dos mesmos campos em cada documento, como um número, o nome de uma empresa, um total ou uma lista de itens.

Antes de chamar este endpoint, crie uma chave de API e certifique-se de que a conta tenha um saldo positivo.

Extração, Busca ou Descrições de Mídia #

Estes três serviços leem documentos, mas retornam coisas diferentes:

Escolha a Extração quando você já sabe quais campos precisa e deseja que sejam lidos diretamente do documento. Escolha a Busca quando precisar do texto completo do documento, por exemplo, para indexá-lo ou ler uma página da web. Escolha as Descrições de Mídia quando precisar de uma explicação sobre conteúdo visual ou audiovisual, como um gráfico, uma foto ou um vídeo, em vez de campos específicos.

Endpoint #

Construir a solicitação #

Cada propriedade em responseSchema é um campo a ser encontrado. Sua description é o critério de busca, então escreva-a como uma definição curta e específica, como “valor total devido” em vez de “total”. Objetos aninhados e arrays de objetos são suportados. $ref e $defs não são; incorpore todas as definições inline.

Imagens e arquivos aceitam URLs de dados base64 ou URLs HTTP(S) públicos:

• Os formatos suportados são JPEG, PNG, TIFF e PDF, incluindo PDFs de múltiplas páginas.
• A AIVAX baixa URLs remotos antes do processamento, dentro do limite de tamanho de arquivo em Preços e limites. O recurso deve ser acessível sem login.
• Outros tipos de conteúdo, como áudio ou vídeo, retornam 400 Bad Request. O erro não identifica qual documento foi rejeitado, então verifique o tipo de conteúdo de cada documento na solicitação.

A seguinte solicitação extrai campos de fatura de um documento de texto e um PDF:

{
  "instructions": "Considere apenas a empresa emissora como o fornecedor.",
  "responseSchema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string", "description": "número da fatura" },
      "vendor": { "type": "string", "description": "empresa que emitiu a fatura" },
      "total": { "type": "number", "description": "valor total devido" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "product": { "type": "string", "description": "nome do produto" },
            "quantity": { "type": "integer", "description": "quantidade de unidades" }
          }
        }
      }
    }
  },
  "documents": [
    {
      "type": "text",
      "text": "Fatura 1042 da Acme Corp. 2 x Widget a $10,00. Total: 20,00 USD."
    },
    {
      "type": "file",
      "file": {
        "filename": "fatura.pdf",
        "file_data": "https://example.com/fatura.pdf"
      }
    }
  ]
}

Ler a resposta #

data contém um objeto por documento, na mesma ordem que documents. Cada objeto usa os nomes de propriedade do seu esquema. Os valores são convertidos para o tipo number, integer ou boolean declarado no esquema, quando possível. Um campo que não é encontrado é null, e um array sem correspondências está vazio.

{
  "message": null,
  "data": [
    {
      "invoice_number": "1042",
      "vendor": "Acme Corp",
      "total": 20,
      "line_items": [
        { "product": "Widget", "quantity": 2 }
      ]
    }
  ]
}

Os documentos são processados independentemente e em paralelo. Se qualquer documento falhar, toda a solicitação retorna um erro em vez de resultados parciais. Corrija ou remova esse documento e tente novamente. Documentos que foram concluídos antes da falha ainda são cobrados e contam para sua cota, então tente novamente apenas após corrigir o documento com falha.

Os valores extraídos são gerados pelo modelo. Eles podem estar ausentes, incompletos ou errados, especialmente em digitalizações de baixa qualidade ou layouts complexos. Valide a estrutura e verifique valores críticos, como montantes e identificadores, contra o documento original.

Preços e limites #

A Extração é cobrada pelos tokens de entrada de cada documento. Tokens de saída não são cobrados.

A Extração e o Resumo compartilham os mesmos limites de documentos. Arquivos remotos são baixados até 5 MB cada. O número de documentos processados por minuto e por dia depende do plano; veja Limites de processamento de dados.

A cota conta cada item no array documents da solicitação, não cada solicitação HTTP. Uma solicitação que excederia qualquer janela ativa retorna 429 Too Many Requests.

A referência de API embutida contém os detalhes mantidos pelo servidor para solicitações, respostas, autenticação e erros: