跳到主要内容
valen
GitHub
EN中
valen

System One

向托管 API 提供文本或图片，并提出判断、选择或评分问题。接口返回每个问题的结果及对应概率。视频可先提取画面帧，再作为图片输入。

Text
POST /v1/systemone

服务地址与认证

快速调用​

客户端安装 requests 后，可直接运行 Python 示例；也可切换为 cURL。

Python
import requests

response = requests.post(
    "https://api.valen-team.workers.dev/v1/systemone",
    headers={"Origin":"https://valen-team.github.io"},
    json={
      "model": "valen-2b",
      "state": "A cat is sitting on the sofa.",
      "questions": {
        "q0": {
          "type": "choice",
          "instructions": "Which animal is present?",
          "criteria": {
            "cat": "A cat",
            "dog": "A dog"
          }
        }
      },
      "temperature": 1
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"]["q0"]
print(answer)
print("Model ID:", body.get("model_id"))

请求头​

字段说明
Content-Type必填，application/json
Origin可选；浏览器跨域请求自动携带。
AuthorizationKey 入口必填，Bearer $VALEN_API_KEY
TypeSafe-Danger-Zone-Images图片请求必填，true

请求体​

字段类型必填说明
modelstring是托管模型 ID，例如 valen-2b；见 List Models。
statestring是所有问题共享的上下文。
questionsobject是按问题 ID 索引的映射。
temperaturenumber否Valen 校准扩展；有限正数，默认 1.0。
assetsobject否按引用名索引的图片资源，见下方图片输入。

问题指令为非空字符串。请求校验由上游 API 执行。

问题类型​

判断条件是否成立，返回 0–1 之间的概率。

请求：

JSON
{
  "model": "valen-2b",
  "temperature": 1.0,
  "state": "A cat is on the sofa.",
  "questions": {
    "q0": {
      "type": "noul",
      "instructions": "The cat is on the sofa."
    }
  }
}

答案示例：

JSON
{
  "answers": {
    "q0": {
      "type": "noul",
      "noul": 0.98
    }
  }
}

响应​

请求成功时返回 HTTP 200，响应内容为 JSON。

字段类型说明
modelstring是
answersobject按问题 ID 索引的答案。
usageobjectinput_tokens 和 output_tokens。

confidence 是独立置信度，不等于最大候选概率。响应还可能包含 model_id、revision、internal_usage、timing 和 images。

图片输入​

示例读取本地 PNG、JPEG 或 WebP 图片并完成编码和请求。将 image.png 替换为你的文件，MIME 类型会根据文件名自动识别。图片通过 assets 提供，并在 state 中引用。

Python
import requests

import base64
import mimetypes
from pathlib import Path

image_path = Path("image.png")
mime_type = mimetypes.guess_type(image_path.name)[0]
image_format = mime_type.split("/", 1)[1]
image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")

response = requests.post(
    "https://api.valen-team.workers.dev/v1/systemone",
    headers={"Origin":"https://valen-team.github.io","TypeSafe-Danger-Zone-Images":"true"},
    json={
      "model": "valen-2b",
      "state": "Answer using only the visible image.\nvalen-example-photo",
      "questions": {
        "q0": {
          "type": "choice",
          "instructions": "Which animal is present?",
          "criteria": {
            "cat": "A cat",
            "dog": "A dog"
          }
        }
      },
      "temperature": 1,
      "assets": {
        "valen-example-photo": {
          "type": "image",
          "format": image_format,
          "data_base64": image_b64
        }
      }
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()
answer = body["answers"]["q0"]
print(answer)
print("Model ID:", body.get("model_id"))

错误​

状态说明
400上游拒绝请求。
422上游字段校验失败，detail 为错误列表。
429触发限流，请稍后重试。

协议参考：TypeSafe System One.