Skip to main content
valen
GitHub
EN中
valen

Decisions

Send text or images to the hosted API and ask predicate, choice, or score questions. The API returns results and associated probabilities for each question. For video, extract frames first and submit them as image inputs.

Text
POST /v1/decisions

Base URLs and authentication

Quick request​

Install requests in the client environment to run the Python example, or switch to cURL.

Python
import requests

response = requests.post(
    "https://api.valen-team.workers.dev/v1/decisions",
    headers={"Origin": "https://valen-team.github.io"},
    json={
      "model": "valen-2b",
      "input": "A cat is sitting on the sofa.",
      "questions": [
        {
          "name": "q0",
          "type": "choice",
          "instructions": "Which animal is present?",
          "choices": [
            {
              "value": "cat",
              "description": "A cat"
            },
            {
              "value": "dog",
              "description": "A dog"
            }
          ]
        }
      ],
      "temperature": 1
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"][0]
print(answer["choice"], answer["confidence"])
for entry in answer["probabilities"]:
    print(entry["value"], entry["probability"])
print("Model ID:", body.get("model_id"))

Headers​

FieldDescription
Content-TypeRequired: application/json
OriginOptional; sent automatically by browsers.
AuthorizationRequired on the keyed endpoint: Bearer $VALEN_API_KEY

Body​

FieldTypeRequiredDescription
modelstringYesHosted model ID, such as valen-2b; see List Models.
inputstring / messages[]YesShared evidence for all questions.
questionsobject[]YesQuestion list; each item has name, type, and instructions.
temperaturenumberNoValen calibration extension; finite and positive, defaults to 1.0.

Instructions must be nonempty text. The upstream API validates requests.

Question types​

Return the probability, from 0 to 1, that a condition holds.

Request:

JSON
{
  "model": "valen-2b",
  "temperature": 1.0,
  "input": "A cat is on the sofa.",
  "questions": [
    {
      "name": "q0",
      "type": "predicate",
      "instructions": "The cat is on the sofa."
    }
  ]
}

Example answer:

JSON
{
  "answers": [
    {
      "type": "predicate",
      "name": "q0",
      "probability": 0.98
    }
  ]
}

Response​

Successful requests return HTTP 200 with a JSON response body.

FieldTypeDescription
modelstringModel that answered the request.
answersobject[]Answers in request order, echoing each question name.
usageobjectinput_tokens and output_tokens.

confidence is separate from the maximum candidate probability. Responses may also include model_id, revision, internal_usage, timing, and images.

Images​

This example encodes a local PNG, JPEG, or WebP image and sends the request. Replace image.png with your file; its MIME type is inferred from the filename. Images are sent as input_image content parts.

Python
import requests

import base64
import mimetypes
from pathlib import Path

image_path = Path("image.png")
mime_type = mimetypes.guess_type(image_path.name)[0]
image_url = f"data:{mime_type};base64," + base64.b64encode(
    image_path.read_bytes()
).decode("ascii")

response = requests.post(
    "https://api.valen-team.workers.dev/v1/decisions",
    headers={"Origin": "https://valen-team.github.io"},
    json={
      "model": "valen-2b",
      "input": [
        {
          "role": "user",
          "content": [
            {
              "type": "input_text",
              "text": "Answer using only the visible image."
            },
            {
              "type": "input_image",
              "image_url": image_url
            }
          ]
        }
      ],
      "questions": [
        {
          "name": "q0",
          "type": "choice",
          "instructions": "Which animal is present?",
          "choices": [
            {
              "value": "cat",
              "description": "A cat"
            },
            {
              "value": "dog",
              "description": "A dog"
            }
          ]
        }
      ],
      "temperature": 1
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"][0]
print(answer["choice"], answer["confidence"])
for entry in answer["probabilities"]:
    print(entry["value"], entry["probability"])
print("Model ID:", body.get("model_id"))

Errors​

StatusDescription
400Request rejected by the upstream API.
429Rate limit exceeded; retry later.

Protocol reference: OpenAI Decisions.