# Cookbook Complete Valen applications with runnable code, sample inputs and real-model outputs, grouped by the goal they serve. Every recipe follows the same split: Valen answers typed questions, and code turns the answers into a decision. Interactive content: [open the web page](https://valen-team.github.io/cookbook/). ## Run any recipe without an API key Each remote recipe ships with `caches/.json`: the real answers recorded for its sample inputs, keyed by model and request. After you download the bundle, every recipe runs offline and prints the same output as the page. Change a question or an input and the runner calls the model for that request and records the new answer. ```bash curl -fLO https://valen-team.github.io/cookbook/valen-cookbook.zip python -m zipfile -e valen-cookbook.zip . cd valen-cookbook python rerank.py # recorded answers, no key needed python rerank.py --replay off # always call the model ``` `--replay only` uses recorded answers only, which is how the site build checks every recipe. ## Reproduce and navigate [API documentation](/docs/valen/api.md) owns protocols, fields, errors and minimal calls. [Deployment documentation](/docs/valen/choosing.md) owns installation and backend configuration. The cookbook owns complete applications. Choosing an automation and review rule? Inspect the [released-model evidence](/docs/valen/reliability.md), then [calibrate on your own data](/docs/valen/calibration.md). [Validation, performance and versions](./validation/) · [Migration map](./migration/) · Download scripts, sample data and recorded answers # API basics This migrates the original API notebook without duplicating the application tutorials. Send a delivery-address message, identify the animal group in an image, and label the sauce color in one sampled video frame. The output contains named answers and the exact sampled frame position. The HTTP client uses **Decisions**. The API accepts an image data URL; the tutorial extracts a frame before sending the video example. This is not direct video inference on the hosted service. Set `VALEN_API_KEY` only if your chosen deployment requires it. ## Install and prepare inputs Use Python 3.11+. Download the small source bundle, extract it, then install its dependencies: ```bash curl -fLO https://valen-team.github.io/cookbook/valen-cookbook.zip python -m zipfile -e valen-cookbook.zip . cd valen-cookbook python -m pip install -r requirements.txt ``` Fetch only these small assets when you choose to run (image ≈58 KB, clip ≈395 KB), or provide authorized files with the same names through `--asset-dir`. ```bash curl -fL https://raw.githubusercontent.com/Valen-Team/Valen/main/assets/cookbook/sheep.jpg -o sheep.jpg curl -fL https://raw.githubusercontent.com/Valen-Team/Valen/main/assets/cookbook/momos.mp4 -o momos.mp4 ``` Interactive content: [open the web page](https://valen-team.github.io/cookbook/api-quickstart/). ## Run The recorded answers in `caches/api_quickstart.json` let the script run without an API key; `--replay off` calls the [free hosted API](/docs/valen/api.md) instead. ```bash python api_quickstart.py --asset-dir . --output result.json python api_quickstart.py --replay off --model valen-2b --asset-dir . --output result.json # An existing local HTTP deployment instead: python api_quickstart.py --replay off --base-url http://127.0.0.1:8000/v1 --model valen --asset-dir . --output result.json ``` For direct ONNX execution, use `--backend onnx --model /path/to/Valen-0.8B-ONNX` and first install `valen-sdk[onnx,video]==0.2.0`. Connect a GGUF service through `--backend remote`; a GGUF file is not a `Valen.local` model. ## Complete executable code `api_quickstart.py`: ```python """API basics: text, one image and a sampled video frame. Apache-2.0.""" from common import client, emit, image_bytes, image_input, middle_frame, parser, request, samples def main(): args = parser(__doc__).parse_args() data = samples() with client(args) as predict: text = request(predict, data["ticket"]["text"], data["ticket"]["questions"]) image = request(predict, image_input(image_bytes(args.asset_dir / data["product"]["image"])), [data["product"]["question"]]) payload, sampling = middle_frame(args.asset_dir / data["video"]["path"]) video_frame = request(predict, image_input(payload), [data["video"]["question"]]) emit({"text": text, "image": image, "video_frame": video_frame, "sampling": sampling}, args) if __name__ == "__main__": main() ``` The shared runner and `samples.json` are included in the download bundle, from the same maintained source as this page.

common.py

`common.py`: ```python """Shared cookbook runner. Apache-2.0. No implicit model or media downloads.""" import argparse import base64 from contextlib import ExitStack, contextmanager import datetime import hashlib import json import math import os from pathlib import Path import sys HERE = Path(__file__).resolve().parent CACHES = HERE / "caches" def samples(): return json.loads((HERE / "samples.json").read_text()) def parser(description): p = argparse.ArgumentParser(description=description) p.add_argument("--backend", choices=["remote", "onnx", "native"], default="remote") p.add_argument("--base-url", default=os.environ.get("VALEN_BASE_URL", "https://api.valen-team.workers.dev/v1")) p.add_argument("--model", default=os.environ.get("VALEN_MODEL")) p.add_argument("--threads", type=int, default=4) p.add_argument("--asset-dir", type=Path, default=Path(".")) p.add_argument("--output", type=Path) p.add_argument("--replay", choices=["auto", "only", "off"], default="auto", help="auto: reuse recorded answers and record new ones; only: recorded answers only; " "off: always call the model") return p @contextmanager def client(args): """Answers for remote requests are recorded in caches/