README.md

metadata

title: Valen API
emoji: 🌊
colorFrom: blue
colorTo: gray
sdk: static
app_file: index.html
fullWidth: true
short_description: Valen API examples with text, images and video

Valen API

A bilingual, static playground for the Valen Decisions API. Use text, images, or a video frame with native predicate, choice, and score questions. Results show probability bars, optional confidence, the returned model ID, and raw JSON. The Python example follows the current inputs, so you can reproduce a request in your own application.

Architecture

Browser on valen-team-valen-api.static.hf.space
  → https://api.valen-team.workers.dev/v1/decisions
  → hosted Valen model

The browser sends requests directly to the existing public API. There is no Python server, model download, GPU, API key, or build step. The Space does not proxy traffic and does not solve network restrictions on workers.dev. It shares the website's upstream service and limits. HTTP 429 means wait at least a minute; the app does not automatically retry or call the model when an example loads.

The Worker must allow the exact browser origin:

ALLOWED_ORIGINS=https://valen-team.github.io,https://valen-team-valen-api.static.hf.space

Keep the website origin when updating the setting. Do not allow * or all of hf.space. Browsers set Origin automatically. Python/cURL examples include the documented Origin: https://valen-team.github.io header; this is not a credential.

Run and test

python3 -m http.server 7860 --bind 127.0.0.1
node --test tests/*.test.mjs

Local preview supports the interface and code generation. Live requests from localhost are intentionally not in the production CORS allowlist; test the full browser flow on the deployed Space. ?lang=zh opens the Chinese interface.

API contract

• Models: valen-2b, valen-4b, valen-0-8b, valen-preview-0923.
• One question named q0, with temperature: 1.0.
• predicate: probability is the probability the condition is true.
• choice: 2–8 {value, description} candidates; response has choice and probabilities.
• score: 2–8 {label, description} levels ordered low to high. The score is the probability-weighted zero-based level index. Five levels span 0–4.
• confidence is optional and separate from the candidate probability.
• The response model_id is shown independently from the requested model.

Questions are limited to 1000 characters, context to 4000, each option to 300. JPG/PNG/WebP uploads are limited to 3 MB. Images are resized locally to fit 1536 × 1536 and encoded as JPEG before submission. The request preview omits the base64 bytes; the generated Python example reads the selected local filename. MP4/WebM videos up to 20 MB are decoded in the browser, and only a JPEG of the middle frame is sent as input_image. This is not whole-video inference; a single frame cannot establish motion or event order. The Python video example uses PyAV to extract a middle frame locally.

The three examples match the website cookbook: a customer changing a delivery address (text), naming a group of sheep (image), and identifying the sauce color in momos.mp4 (video). Example media is bundled in cookbook/. Clicking an example loads its inputs and prepares the image/frame without calling the API.

Data

Inputs are sent to the API only when Ask Valen is pressed. This static app does not upload images to a Hugging Face backend, store conversations, write local storage, or include analytics. Inputs and results remain in page memory. The API and hosting providers may have their own logging and retention policies. Requests can be cancelled and time out after two minutes.

Files

• index.html, style.css, app.mjs, locales.mjs: responsive bilingual UI.
• api.mjs: request validation, response parsing and Python examples.
• media.mjs: local image/video decoding and frame extraction.
• tests/: offline contract, error and example-generation tests.
• assets/: pinned Valen design tokens, brand mark and font; see NOTICE.md.

Upload these files to the static Space Valen-Team/Valen-API. Do not upload local virtual environments, caches, credentials or .env files. Static configuration follows the Hugging Face reference.