Spaces:
Running
Running
| 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). | |