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ê envia | Declare | O que o engine recebe |
|---|---|---|
| Texto | um estado text, ou um campo string | o texto |
| JSON estruturado | um estado object com campos tipados, ou uma list | o JSON |
| Imagem | um campo image — PNG, JPEG, GIF ou WebP | OpenAI Decisions: a própria imagem. Jev e Laya: uma descrição da imagem com o texto visível nela, escrita pela OpenAI |
| Texto + imagem | um estado object com um campo string e um campo image | os dois, lado a lado |
| Voz / áudio | um campo audio — MP3, WAV, OGG/Opus (áudios do WhatsApp), M4A, WebM, FLAC, AAC, AMR | a transcrição (speech-to-text da OpenAI) |
| Documento ou qualquer arquivo | um campo file | o 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:
| Forma | Exemplo |
|---|---|
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.pdfDe 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.pdfNo 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
| Arquivo | Lido por | Custo |
|---|---|---|
| Documentos que a Dcision consegue interpretar (PDF com texto, Office, OpenDocument, planilhas, CSV, RTF, HTML, texto) | Dcision | nenhum |
| Imagens na OpenAI Decisions | o engine | parte da chamada ao engine |
| Áudio; imagens no Jev ou no Laya; PDFs escaneados e outros formatos | OpenAI | a 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:
| Campo | O que é |
|---|---|
metrics.input_files | Quantos arquivos foram lidos. |
metrics.input_processing_ms | Tempo para baixá-los e lê-los, incluído em latency_ms. |
metrics.input_cost_usd | O 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
| Limite | Valor |
|---|---|
| Um arquivo | 20 MB |
| Todos os arquivos de um estado | 24 MB, até 10 arquivos |
| Corpo da requisição de uma execução | 32 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 estado | cerca de 96.000 caracteres no total, cortados por igual |
| Leitura dos arquivos de uma execução | 60 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://.
Decision schema
O documento JSON por trás de toda decisão — o estado que ela aceita, as perguntas que responde, composites, as políticas que escolhem a ação, as configurações de runtime e os destinos.
Perguntas
Perguntas de choice, score e probability — instruções e critérios estruturados, o que a API devolve para cada uma, níveis ponderados, a opção reservada other e a confiança mínima.