Tutorial da OpenAI Decisions API: sua primeira chamada de decisão

Passo 1 — obtenha uma chave

Abra o playground e pressione Run uma vez — uma sessão de convidado, uma chave de API e 2 créditos grátis são criados automaticamente. Para produção, entre e crie uma chave nomeada no painel em API keys. As chaves vão no cabeçalho Authorization Bearer..

Mantenha a chave no servidor. Toda requisição que a carrega é cobrada do seu saldo, então nunca a coloque em código de navegador ou repositório público.

Passo 2 — envie a primeira requisição

Uma requisição de decisão tem três campos: model (decisions-1 ou decisions-latest), state (o contexto que o modelo lê — uma string, objeto JSON ou array de texto) e questions (um mapa de 1 a 6 ids de pergunta). Escreva a pergunta real em instructions — o id é apenas o rótulo sob o qual a resposta retorna.

Uma pergunta noul é um julgamento sim/não: o campo de resposta noul é a probabilidade de a afirmação ser verdadeira.

curl https://decisions-api.net/api/v1/decisions \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "decisions-1",
  "state": "I was charged twice for my subscription this morning.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}'

Passo 3 — adicione uma pergunta choice

Uma pergunta choice escolhe um rótulo da lista que você define. criteria é um objeto de 2 a 8 ids de opção, cada um com uma descrição curta — o modelo lê a descrição, então escreva-a como uma regra de roteamento.

Uma pergunta score funciona igual, mas recebe um array ordenado de 2 a 10 descrições de nível, da menor para a maior. Você pode misturar os três tipos numa chamada, até seis perguntas.

{
  "team": {
    "type": "choice",
    "instructions": "Which team should own this ticket?",
    "criteria": {
      "payments": "Checkout, billing, or payment processing.",
      "frontend": "Rendering or browser behavior.",
      "account": "Login, permissions, or profile."
    }
  }
}

Passo 4 — leia as probabilidades

Uma resposta bem-sucedida traz model, answers indexadas pelos seus ids de pergunta, usage e credits_used. Uma resposta noul é apenas a probabilidade. Uma resposta choice inclui o choice vencedor, uma probabilidade por opção e um valor de confiança.

O segundo lugar importa tanto quanto o vencedor. Duas opções perto de 0.5 cada não é o mesmo que 0.9 contra 0.1 — trate casos apertados como candidatos a revisão, não como escolhas confiantes.

{
  "model": "decisions-1",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "credits_used": 1
}

Passo 5 — defina um limiar e trate erros

Escolha um limiar de confiança com seu próprio tráfego: aceite acima dele, mande o resto para uma pessoa. Comece alto (0.7–0.8) e baixe só depois de revisar os casos que ficaram aquém.

402 significa saldo vazio; 429 ou 502 significa tentar depois — chamadas que falham não são cobradas. 422 é erro de validação do corpo e a mensagem indica o campo.

const res = await fetch('https://decisions-api.net/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})

if (res.status === 402) { /* out of credits */ }
if (res.status === 429 || res.status === 502) { /* retry later */ }

const { answers } = await res.json()
const team = answers.team

if (team.type === 'choice' && team.confidence >= 0.7) {
  routeTo(team.choice)          // confident: auto-assign
} else {
  queueForHuman(team)           // low confidence or near-tie: review
}

Perguntas frequentes