Venice Decisions (Beta)

POST /api/v1/decisions evaluates a state (text or JSON) against a map of typed questions and returns one structured answer per question — probabilities, picks, and scores your code can branch on directly. It does not generate text. The only model is TypeSafe's Jev (jev-latest), a "System One" decision model.

Beta. The spec labels both routes Beta: "Request/response schemas and behavior may change without notice."

Use when

• Routing / classifying (support tickets, intents, moderation buckets) into a closed set of options.
• Yes/no gates where the probability itself is useful (is_urgent, requests_refund).
• Rating something on an ordered rubric (severity, frustration, quality).
• You want several independent judgments about the same state in one call.

Use venice-chat instead when you need prose, explanations, multi-turn conversation, tool calling, or open-ended answers.

Endpoints

Both POST routes accept Accept-Encoding: gzip, br.

Quick start

curl https://api.venice.ai/api/v1/decisions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My payouts have failed for three days and nobody has replied. Please help ASAP.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this message require urgent attention?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "Payments, invoices, or refunds",
          "technical": "Bugs, outages, or integrations",
          "sales": "Pricing, upgrades, or new accounts"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": ["Calm", "Frustrated", "Very angry"]
      }
    }
  }'

Illustrative response (values vary per request):

{
  "model": "jev-latest",
  "answers": {
    "is_urgent": { "type": "noul", "noul": 0.95 },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.95, "technical": 0.05, "sales": 0 },
      "confidence": 0.93
    },
    "frustration": {
      "type": "score",
      "score": 1.27,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0, "1": 0.73, "2": 0.27 },
      "confidence": 0.6
    }
  },
  "usage": { "input_tokens": 429, "output_tokens": 73 }
}

Request schema

Top level is strict — unknown fields are rejected with 400.

Question objects

Each question is strict (no extra keys) and discriminated by type. instructions on every type accepts a non-empty string, a JSON object, or a non-empty array.

Any other type value is rejected with 400.

Token limits

From GET /models?type=decision (model_spec):

• maxStateTokens: 32000 — state plus the single longest question.
• maxTotalTokens: 64000 — state plus all questions combined.

Venice does not count tokens before forwarding; these budgets are enforced by TypeSafe. An oversized request therefore passes Venice validation and fails upstream — as a 400 carrying TypeSafe's message if TypeSafe answers 400/422, otherwise as a 500 (see Errors). The generic JSON body cap is 35 MB.

Answer types

Every answer has type. The response schema passes unknown extra fields through, and an answer whose type is not noul/choice/score is forwarded as-is (forward-compat) — branch on type and ignore what you don't recognise.

noul — yes/no probability

{
  "refund_requested": {
    "type": "noul",
    "instructions": "Does the customer explicitly request a refund?",
    "criteria": {
      "true": "The customer asks for money to be returned",
      "false": "The customer does not ask for money to be returned"
    }
  }
}

{ "refund_requested": { "type": "noul", "noul": 0.88 } }

• noul: number in [0, 1]; ≈1 strong yes, ≈0 strong no, ≈0.5 uncertain. There is no confidence field on noul answers.

choice — pick one option

{
  "request_type": {
    "type": "choice",
    "instructions": "What is the customer's primary request?",
    "criteria": {
      "refund": "Return money already paid",
      "troubleshooting": "Help resolve a product problem",
      "information": "Answer a question without taking action",
      "other": null
    }
  }
}

{
  "request_type": {
    "type": "choice",
    "choice": "refund",
    "probabilities": { "refund": 0.9, "troubleshooting": 0.06, "information": 0.03, "other": 0.01 },
    "confidence": 0.85
  }
}

• choice: the highest-probability option name.
• probabilities: every option → probability in [0, 1] (sum to 1).
• confidence: [0, 1], derived from the distribution.
• Include an other / none option when your options may not cover every state.

score — position on an ordered rubric

{
  "severity": {
    "type": "score",
    "instructions": "How severe is the reported issue?",
    "criteria": [
      "Cosmetic or no material impact",
      "Workflow is impaired but a workaround exists",
      "Critical workflow is blocked with no workaround"
    ]
  }
}

{
  "severity": {
    "type": "score",
    "score": 1.4,
    "legend": {
      "0": "Cosmetic or no material impact",
      "1": "Workflow is impaired but a workaround exists",
      "2": "Critical workflow is blocked with no workaround"
    },
    "probabilities": { "0": 0.05, "1": 0.5, "2": 0.45 },
    "confidence": 0.55
  }
}

• Levels are indexed from 0 in the order you gave them; legend and probabilities are keyed by the index as a string.
• score: probability-weighted (≥ 0), so it can land between levels.
• confidence: [0, 1], derived from the distribution.

Response

Headers: x-ratelimit-{limit,remaining,reset}-{requests,tokens}; Content-Encoding when compressed. The spec also lists X-Balance-Remaining for x402 callers, but the server does not currently set it — poll GET /x402/balance/{walletAddress} instead.

JavaScript / Python

No OpenAI SDK method exists for this route — use plain HTTP.

const res = await fetch('https://api.venice.ai/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-latest',
    state: { ticket: { subject: 'Duplicate charge', message: 'I was charged twice. Please refund the duplicate.' }, account: { plan: 'pro' } },
    questions: {
      covered: { type: 'noul', instructions: 'Does ticket.message request a refund for a duplicate charge?' },
      priority: { type: 'score', instructions: 'How urgent is this ticket?', criteria: ['Low', 'Medium', 'High'] },
    },
  }),
})
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
const { answers } = await res.json()

if (answers.covered.type === 'noul' && answers.covered.noul >= 0.9) {
  // auto-approve
}

import os, requests

r = requests.post(
    "https://api.venice.ai/api/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['VENICE_API_KEY']}"},
    json={
        "model": "jev-latest",
        "state": "Help! My payouts have been failing for 3 days.",
        "questions": {
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {"billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations"},
            }
        },
    },
    timeout=60,
)
r.raise_for_status()
team = r.json()["answers"]["team"]
route = team["choice"] if team["confidence"] >= 0.8 else "human_review"

Authentication

Both routes accept either (see venice-auth):

• Authorization: Bearer $VENICE_API_KEY, or
• SIGN-IN-WITH-X wallet auth for x402 (legacy X-Sign-In-With-X also accepted). Payment headers (X-PAYMENT etc.) are only accepted on /x402/top-up; sending one here → 400 PAYMENT_HEADER_NOT_ACCEPTED. See venice-x402.

With no credentials at all you get a 402 x402 discovery response. The spec's x-payment-info is mode: dynamic, USD, min 0.001 / max 10.00.

API keys whose modelPrivacy is PRIVATE_ONLY or PRIVATE_TEXT are refused (403): Jev is an anonymized (third-party) model, and PRIVATE_TEXT gates decisions as well as text and embeddings.

Pricing & limits

• Price (live GET /models?type=decision): $0.042 per 1M input tokens (0.042 DIEM); output tokens $0. A 429-input-token request costs ≈ $0.000018. Always read model_spec.pricing for the current number.
• Charged from usage after a successful response. If the upstream answer is malformed or missing usage, you get 500 and are not charged.
• Balance is checked before the call; insufficient balance → 402.
• Rate limits (per account, shared by all its keys; Jev-specific override): Paid tier 100 RPM / 1,000,000 TPM; Partner Tier 1 300 RPM / 10,000,000 TPM. One request is counted before the model runs; tokens (input + output) are metered afterwards. Check yours with GET /api_keys/rate_limits (venice-api-keys).

Errors

General retry strategy and body shapes: venice-errors.

Gotchas

• Beta, one model. GET /models?type=decision currently returns only jev-latest; don't hard-code capabilities beyond what model_spec reports.
• Not chat. There is no messages, temperature, max_tokens, streaming, or tools. Adding any unknown field is a 400 (strict schema).
• Questions are isolated. One answer never becomes context for another. If question B depends on A's result, make a second request.
• Question ids carry no meaning to the model. {"urgent": {...}} with vague instructions won't help — write complete instructions and name the fields in structured state (e.g. "Does ticket.message request a refund covered by refund_policy?").
• Token budgets are enforced upstream, so Venice validation passes and the failure arrives from TypeSafe. Pre-trim long states yourself.
• Every 4xx except 429 counts toward the failed-requests error budget on this route (the separate unsupported-feature budget applies only to /chat/completions and /responses), so a client looping on bad requests locks itself out for the rest of the 30 s window.
• Probabilities vary between requests. Calibrate thresholds on your own data; confidence is not a correctness guarantee. Noul has no confidence — use distance from 0.5.
• score keys are strings ("0", "1", …) in both legend and probabilities.
• Branch on answer.type — unknown future answer types are passed through untouched.
• Anonymized, not private. State is sent to TypeSafe; don't route data that requires Venice-private inference.
• Model discovery and pricing fields: venice-models.