Skip to main content
valen
GitHub
EN中
valen

System One

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/systemone

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/systemone",
    headers={"Origin":"https://valen-team.github.io"},
    json={
      "model": "valen-2b",
      "state": "A cat is sitting on the sofa.",
      "questions": {
        "q0": {
          "type": "choice",
          "instructions": "Which animal is present?",
          "criteria": {
            "cat": "A cat",
            "dog": "A dog"
          }
        }
      },
      "temperature": 1
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"]["q0"]
print(answer)
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
TypeSafe-Danger-Zone-ImagesRequired for images: true

Body​

FieldTypeRequiredDescription
modelstringYesHosted model ID, such as valen-2b; see List Models.
statestringYesShared evidence for all questions.
questionsobjectYesQuestions keyed by ID.
temperaturenumberNoValen calibration extension; finite and positive, defaults to 1.0.
assetsobjectNoImage assets keyed by reference; see Images below.

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,
  "state": "A cat is on the sofa.",
  "questions": {
    "q0": {
      "type": "noul",
      "instructions": "The cat is on the sofa."
    }
  }
}

Example answer:

JSON
{
  "answers": {
    "q0": {
      "type": "noul",
      "noul": 0.98
    }
  }
}

Response​

Successful requests return HTTP 200 with a JSON response body.

FieldTypeDescription
modelstringModel that answered the request.
answersobjectAnswers keyed by question ID.
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 provided through assets and referenced in state.

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_format = mime_type.split("/", 1)[1]
image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")

response = requests.post(
    "https://api.valen-team.workers.dev/v1/systemone",
    headers={"Origin":"https://valen-team.github.io","TypeSafe-Danger-Zone-Images":"true"},
    json={
      "model": "valen-2b",
      "state": "Answer using only the visible image.\nvalen-example-photo",
      "questions": {
        "q0": {
          "type": "choice",
          "instructions": "Which animal is present?",
          "criteria": {
            "cat": "A cat",
            "dog": "A dog"
          }
        }
      },
      "temperature": 1,
      "assets": {
        "valen-example-photo": {
          "type": "image",
          "format": image_format,
          "data_base64": image_b64
        }
      }
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"]["q0"]
print(answer)
print("Model ID:", body.get("model_id"))

Errors​

StatusDescription
400Request rejected by the upstream API.
422Upstream field validation failed; detail is an error list.
429Rate limit exceeded; retry later.

Protocol reference: TypeSafe System One.