README.md

---
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](https://valen-team.github.io/docs/valen/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

```text
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:

```text
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

```bash
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](https://huggingface.co/docs/hub/spaces-config-reference).