Entradas — texto, JSON, imagens, áudio e documentos

O que uma decisão consegue ler — texto, JSON estruturado, imagens, áudios e documentos (PDF, Word, Excel, PowerPoint, CSV e mais) — e como cada um chega ao Jev, ao Laya ou à OpenAI Decisions.

Uma decisão lê o seu estado. Além de texto e JSON, um estado do tipo objeto pode levar arquivos: declare um campo como image, audio ou file e envie o arquivo nele. A Dcision transforma cada arquivo em algo que o engine lê — texto, ou uma imagem para engines que enxergam imagens — antes de chamar o engine, então a mesma decisão roda em qualquer engine.

Você enviaDeclareO que o engine recebe
Textoum estado text, ou um campo stringo texto
JSON estruturadoum estado object com campos tipados, ou uma listo JSON
Imagemum campo image — PNG, JPEG, GIF ou WebPOpenAI Decisions: a própria imagem. Jev e Laya: uma descrição da imagem com o texto visível nela, escrita pela OpenAI
Texto + imagemum estado object com um campo string e um campo imageos dois, lado a lado
Voz / áudioum campo audio — MP3, WAV, OGG/Opus (áudios do WhatsApp), M4A, WebM, FLAC, AAC, AMRa transcrição (speech-to-text da OpenAI)
Documento ou qualquer arquivoum campo fileo texto dele: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx, .xls), OpenDocument (.odt, .ods, .odp), CSV, RTF, HTML, XML, EPUB, Markdown e texto simples são lidos pela Dcision; PDFs escaneados, .doc/.ppt legados e outros formatos são lidos pela OpenAI. Imagens e áudio enviados num campo file são tratados como acima

Declarar campos de arquivo

{
  "kind": "object",
  "fields": [
    { "key": "message", "type": "string" },
    { "key": "photo", "type": "image" },
    { "key": "voice", "type": "audio" },
    { "key": "invoice", "type": "file", "required": true }
  ]
}

Enviar um arquivo

Um campo de arquivo aceita qualquer uma destas formas:

FormaExemplo
URL data: (base64)"data:image/png;base64,iVBORw0KGgo…"
Objeto com base64{ "data": "JVBERi0xLjQK…", "filename": "nf-1042.pdf", "mime_type": "application/pdf" } — filename e mime_type são opcionais
URL https://"https://files.example.com/nf-1042.pdf" ou { "url": "…", "filename": "nf-1042.pdf" } — a Dcision faz o download
curl -X POST https://api.dcision.io/v1/decisions/invoice-triage \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"state\": {\"message\": \"Can we pay this?\", \"invoice\": {\"data\": \"$(base64 -w0 nf-1042.pdf)\", \"filename\": \"nf-1042.pdf\"}}}"

Pelos SDKs e pela CLI:

import { readFile } from "node:fs/promises";
import { Dcision, fileFromBytes, fileFromUrl } from "@dcision/sdk";

const decision = await new Dcision().decide("invoice-triage", {
  message: "Can we pay this?",
  invoice: fileFromBytes(await readFile("nf-1042.pdf"), "nf-1042.pdf"),
  photo: fileFromUrl("https://files.example.com/receipt.jpg"),
});
from dcision import Dcision, file_from_path

decision = Dcision().decide("voice-routing", {"voice": file_from_path("note.ogg")})
dcision decide invoice-triage --state '{"message":"Can we pay this?"}' --file invoice=./nf-1042.pdf

De um formulário, do n8n, do Make ou do Zapier, o webhook de entrada também aceita arquivos como multipart/form-data:

curl https://api.dcision.io/v1/hooks/whk_… \
  -F state='{"message":"Can we pay this?"}' \
  -F invoice=@nf-1042.pdf

No Playground, campos de arquivo ganham um seletor de arquivo — e campos de áudio, um botão Gravar para gravar um áudio.

O formato vem dos bytes do arquivo, não do nome nem do mime_type: um .pdf que na verdade é um PNG é lido como imagem. Um campo image recusa tudo que não seja imagem, e um campo audio tudo que não seja áudio (422 INVALID_STATE); um campo file aceita qualquer formato.

URLs precisam ser endereços https:// públicos que respondam 200 com o arquivo — redirecionamentos não são seguidos, e endereços privados ou reservados são recusados, como nos destinos.

O que o engine lê

Cada campo de arquivo é substituído pelo que foi lido dele, e o engine — assim como os seus destinos e o log de execuções — vê isso no lugar dos bytes:

{
  "message": "Can we pay this?",
  "invoice": { "kind": "document", "file": "nf-1042.pdf", "content_type": "application/pdf", "bytes": 48213, "text": "NOTA FISCAL Nº 1042 … Total R$ 380,00" },
  "voice": { "kind": "audio", "file": "note.ogg", "content_type": "audio/ogg", "bytes": 21877, "text": "I want to cancel order 1042 and get a refund." },
  "photo": { "kind": "image", "file": "receipt.jpg", "content_type": "image/jpeg", "bytes": 90311, "text": "", "image": 1 }
}

Na OpenAI Decisions, "image": 1 aponta para a primeira imagem enviada com a chamada; escreva instruções que se refiram a ela com naturalidade ("A foto mostra algum dano?"). No Jev e no Laya, text traz a descrição da imagem.

Aponte as instruções para o texto pelo nome do campo: "Does the `invoice` total exceed R$ 1,000?", "Does `voice` ask for a refund?". Nos destinos, use {{state.voice.text}} para repassar a transcrição.

Arquivos longos são cortados para caber no orçamento de tokens do engine: os textos de todos os arquivos dividem cerca de 96.000 caracteres — os curtos ficam inteiros — e um texto cortado termina com … e tem "truncated": true.

Quem lê cada arquivo — e quem paga

ArquivoLido porCusto
Documentos que a Dcision consegue interpretar (PDF com texto, Office, OpenDocument, planilhas, CSV, RTF, HTML, texto)Dcisionnenhum
Imagens na OpenAI Decisionso engineparte da chamada ao engine
Áudio; imagens no Jev ou no Laya; PDFs escaneados e outros formatosOpenAIa sua conta OpenAI

Arquivos que precisam da OpenAI usam a chave OpenAI do workspace (Configurações → Engine → chave OpenAI), ou a da Dcision quando este ambiente tem uma. Sem nenhuma das duas, essas execuções respondem 424 ENGINE_NOT_CONFIGURED — documentos que a Dcision interpreta nunca precisam de chave. Uma falha enquanto a OpenAI lê um arquivo é um erro do engine (ENGINE_*): com onEngineError: "fallback" a decisão responde com a sua ação de fallback.

Ler arquivos leva tempo — um minuto de áudio leva alguns segundos para ser transcrito — além da chamada ao engine. Dê aos clientes um timeout de 60 s para decisões com áudio.

Custo na resposta

Quando o estado tinha arquivos, os metrics da resposta mostram o que a leitura custou:

CampoO que é
metrics.input_filesQuantos arquivos foram lidos.
metrics.input_processing_msTempo para baixá-los e lê-los, incluído em latency_ms.
metrics.input_cost_usdO custo estimado da leitura pela OpenAI — 0 quando a Dcision leu todos sozinha.

metrics.estimated_cost_usd — e o custo estimado no log de execuções e na Visão geral — inclui input_cost_usd. A estimativa usa os preços de tabela da OpenAI para os modelos que leem arquivos por padrão: gpt-4o-transcribe para áudio (US$ 2,50 por 1M de tokens de entrada, US$ 10 por 1M de tokens de saída) e gpt-5-mini para descrição de imagens e leitura de arquivos (US$ 0,25 e US$ 2). É uma estimativa; a referência é a sua fatura da OpenAI. Sem arquivos, esses campos não aparecem. Veja Executar uma decisão.

Limites

LimiteValor
Um arquivo20 MB
Todos os arquivos de um estado24 MB, até 10 arquivos
Corpo da requisição de uma execução32 MB na API, no Playground e nos webhooks de entrada (413 PAYLOAD_TOO_LARGE acima disso); o estado sem os arquivos continua limitado a 128 KB
Texto de arquivo lido para o estadocerca de 96.000 caracteres no total, cortados por igual
Leitura dos arquivos de uma execução60 s

O log de execuções guarda o nome, o tipo, o tamanho e os primeiros 4.000 caracteres do texto de cada arquivo — nunca o arquivo em si. Com storeInput: false ele não guarda nada.

Requisições ao MCP são limitadas a 1 MB: envie arquivos ao servidor MCP como URLs https://.

Nesta página