API REFERENCE

创建一次决策

输入上下文、任务指令与候选项，获取模型对每个候选决策的概率。

POST/v1/decisionsJSON

托管 API 的端点和示例来自官方 API cookbook。 查看来源

免费 API：无需 Key

我们提供免费、有限额的 API，适合体验和少量调用。右侧代码无需 Key；遇到 HTTP 429 请稍后重试，避免并发批量调用。

https://api.valen-team.workers.dev/v1/decisions

免费入口支持 valen-preview-0923、valen-2b、valen-4b、valen-0-8b，通过 model 字段选择。每次传一个 name 为 q0 的问题，支持 predicate、choice、score；choice 传 2–8 个候选项，score 传 2–8 个从低到高的 levels（label、description），temperature 固定为 1.0。文本最多 4000 字符，问题最多 1000 字符，每项描述最多 300 字符。图片建议小于 3 MB，请求体不超过 4,500,000 字节。

Python/cURL 示例包含免费入口要求的 Origin 请求头。官网演示和 Valen API Hugging Face Space 可直接使用；其他网站的浏览器跨域访问目前不开放。Origin 不是访问凭据。

更高额度：邮件申请 Key

需要批量调用或更高额度，请邮件联系 liuziyu77@sjtu.edu.cn，说明用途、预计调用量和输入类型。具体额度以服务方确认的信息为准。

获批后，将示例 URL 改为官方接口，并通过 Authorization: Bearer 发送自己的 Key；不要把 Key 放进前端代码。

import os

url = "https://llm-proxy.openxxlab.com/v1/decisions"
headers = {"Authorization": "Bearer " + os.environ["VALEN_API_KEY"]}

请求体

APPLICATION/JSON

modelstringREQUEST

可选 valen-preview-0923、valen-2b、valen-4b、valen-0-8b；示例默认 valen-2b。

inputstring | messages[]REQUEST

文本上下文，或包含文本、图像数据的消息列表。

questionsobject[]REQUEST

免费入口一次传一个问题，name 固定为 q0。

namestring

问题标识，用于关联返回结果。

typestring

支持 predicate（是非）、choice（选择）、score（评分）。

instructionsstring

说明模型应当如何判断。

choicesobject[]

每个候选项包含 value 和 description 两个字段。

{"value": "cat", "description": "A cat"}

levelsobject[]

score 专用：2–8 个从低到高的档位，每档包含 label 和 description。返回 score 是从 0 开始的档位索引的概率加权平均值。

{"label": "High", "description": "Strong purchase intent"}

temperaturenumber

示例值为 1.0，完整参数说明以托管服务文档为准。

读取结果

通过 answers 读取返回的问题结果。保留问题标识和候选项，供后续决策流程使用。

response.json()["answers"][0]

predicate 返回 probability（条件成立的概率）；choice 返回 choice 和 probabilities；score 返回 score 和档位 probabilities（label、数值索引 value、probability）。score 按从 0 开始的档位索引加权，五档对应 0–4 分。可选 confidence 表示独立置信度。confidence 是独立字段，不等于最大候选概率。answers 与 questions 按位置对应，name 用于核对问题。通过请求 model 选择模型，响应 model_id 提供模型标识。

多模态输入

图像可以表示为 JPEG data URL，放入包含 input_text 和 input_image 的消息列表，再作为 input 传入。

了解数据格式与本地接口差异

视频输入：从画面做决策

首页的视频示例先提取 MP4 中间帧，再将 JPEG data URL 作为 input_image 发送。这不是直接上传视频；当前未验证托管接口支持 input_video。单帧不能判断运动或事件顺序。

python -m pip install requests "Pillow>=10" av==16.1.0

将官方仓库 assets/cookbook/momos.mp4 放在当前目录，使用免费接口运行，无需 Key。只向接口发送一张 JPEG，帧提取在本地完成。

import base64
import io

import av
import requests

# 按照官方 Cookbook，提取视频中间帧。
video_path = "momos.mp4"
with av.open(video_path) as video:
    frame_count = sum(1 for _ in video.decode(video=0))
if frame_count == 0:
    raise ValueError("The video has no decodable frames")
with av.open(video_path) as video:
    for index, frame in enumerate(video.decode(video=0)):
        if index == frame_count // 2:
            image = frame.to_image()
            break

buffer = io.BytesIO()
image.save(buffer, format="JPEG", quality=95)
image_url = "data:image/jpeg;base64," + base64.b64encode(
    buffer.getvalue()
).decode("ascii")

response = requests.post(
    "https://api.valen-team.workers.dev/v1/decisions",
    headers={"Origin": "https://valen-team.github.io"},
    json={
        "model": "valen-2b",
        "input": [{
            "role": "user",
            "content": [
                {"type": "input_text", "text": "请仅根据图片中可见的内容回答问题。"},
                {"type": "input_image", "image_url": image_url},
            ],
        }],
        "questions": [{
            "name": "q0",
            "type": "choice",
            "instructions": "左边铝箔容器里的酱料是什么颜色？",
            "choices": [
                {"value": "brown", "description": "棕色"},
                {"value": "white", "description": "白色"},
                {"value": "red", "description": "红色"},
                {"value": "orange", "description": "橙色"},
            ],
        }],
        "temperature": 1.0,
    },
    timeout=120,
)
response.raise_for_status()
answer = response.json()["answers"][0]
print(answer["choice"], answer["confidence"])
for entry in answer["probabilities"]:
    print(entry["value"], entry["probability"])