Extração estruturada

Duas rotas, a mesma ideia: você descreve o formato que quer como um JSON Schema, e a resposta tem a garantia de ser válida contra ele. Você não extrai o texto por conta própria — o OCR roda automaticamente onde for necessário.

Use /documents/extract para um PDF (o OCR só entra nas páginas escaneadas) e /images/extract para uma imagem avulsa — uma foto do celular, um print, um documento escaneado solto —, em que toda imagem passa pelo OCR.

Requisição#

As duas recebem multipart/form-data com os mesmos campos:

Exemplo#

curl -X POST "https://api.trystac.com/v1/documents/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F file=@nota-fiscal.pdf \
  -F 'schema={
        "type": "object",
        "properties": {
          "numero_nota":       {"type": "string"},
          "cnpj_fornecedor":   {"type": ["string", "null"]},
          "total":             {"type": "number"}
        },
        "required": ["numero_nota", "cnpj_fornecedor", "total"]
      }'

curl -X POST "https://api.trystac.com/v1/images/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F file=@nota-fiscal.jpg \
  -F 'schema={"type": "object", "properties": {"total": {"type": "number"}}, "required": ["total"]}'

Resposta#

{
  "data": { "numero_nota": "12345", "cnpj_fornecedor": "11.222.333/0001-81", "total": 1500.0 },
  "pages": 3,
  "files": 1,
  "ocr_used": false,
  "usage": { "prompt_tokens": 2104, "completion_tokens": 48 }
}

A regra mais importante: campos que podem faltar precisam aceitar null#

A saída é restrita por gramática para seguir o seu schema token a token — é isso que garante um JSON válido, mas tem uma consequência que decide a qualidade dos seus resultados:

Declare como anulável todo campo que possa legitimamente não existir:

"cnpj_fornecedor": { "type": ["string", "null"] }

Há uma segunda armadilha, na direção oposta: um campo fora de required é opcional no JSON Schema, então o modelo pode simplesmente omitir a chave em vez de procurar o valor — você recebe um 200 com JSON válido e um campo faltando, sem nenhum aviso. A combinação que evita as duas armadilhas é required em todos os campos, com tipos anuláveis nos que podem legitimamente faltar:

{
  "type": "object",
  "properties": {
    "numero_nota":     { "type": "string" },
    "cnpj_fornecedor": { "type": ["string", "null"] },
    "total":           { "type": "number" }
  },
  "required": ["numero_nota", "cnpj_fornecedor", "total"]
}

Isso vale também dentro de arrays e objetos aninhados — cada objeto de uma lista precisa do próprio required, ou os itens voltam com campos faltando em silêncio.

Vários arquivos numa requisição#

Quando os campos que você quer estão espalhados entre documentos — a nota fiscal e o comprovante, o contrato e o aditivo —, envie todos numa só requisição por files e receba um JSON de volta. Disponível a partir do Pro.

curl -X POST "https://api.trystac.com/v1/documents/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F files=@nota-fiscal.pdf \
  -F files=@comprovante.pdf \
  -F 'schema={
        "type": "object",
        "properties": {
          "numero_nota":  {"type": "string"},
          "valor_pago":   {"type": ["number", "null"]}
        },
        "required": ["numero_nota", "valor_pago"]
      }' \
  -F 'user=O número da nota está na nota fiscal; o valor pago está no comprovante.'

Cada arquivo chega ao modelo num bloco numerado próprio, identificado pelo nome do arquivo (--- DOCUMENTO 1 DE 2 (nota-fiscal.pdf) ---), então o user pode dizer onde procurar cada campo.

• O Go aceita 1 arquivo por requisição. Um segundo arquivo — em files, ou repetindo file — devolve 413 com uma mensagem explicando isso. Para vários documentos no Go, envie uma requisição por arquivo.
• Os limites do plano valem para a soma. Tamanho e número de páginas são somados entre todos os arquivos da requisição, e ela é recusada antes de qualquer OCR rodar.
• Um documento vazio aborta a requisição inteira (400, com o nome do arquivo). Seguir sem ele deixaria o modelo preencher o schema a partir dos outros arquivos sem que você tivesse como saber.
• Quer um JSON por arquivo? Continue enviando uma requisição por arquivo — o envio de vários arquivos é para campos que moram em documentos diferentes.

Erros#

Um raw_output truncado num 502 costuma significar que a resposta não coube no contexto restante — o arquivo é grande e sobrou pouco espaço para o JSON. Divida o PDF ou enxugue o schema.

Limites#

Schema de até 64 KB nas duas rotas. Timeout do servidor: 240s — configure o timeout do seu cliente acima disso; um documento escaneado de várias páginas pode levar minutos.