图片

象信 3.0 正式支持图片输入。你可以对照片做是非判断、分类、评分，也可以用 Box 获取目标的位置。图片与文字可以一起组织成嵌套 JSON，放在 state、问题的 instructions 或 criteria 中。

接口仍是 POST /v1/systemone，鉴权与文本请求相同，无需额外的功能开关或实验请求头。图片与 Box 请求使用 model: "xiangxin-3.0"（固定版本为 xiangxin-3.0.0）。在 Playground 中上传图片即可体验。

图片与引用

请求顶层的 assets 保存图片；其他字段用一个唯一字符串引用它。下面的 photo 指向上传的图片，同一次请求同时判断物体是否存在、给它分类并定位：

{
  "model": "xiangxin-3.0",
  "state": {"photo": "<image-7f8d9c>"},
  "assets": {
    "<image-7f8d9c>": {
      "type": "image",
      "format": "jpg",
      "data_base64": "此处替换为完整的图片 base64"
    }
  },
  "questions": {
    "present": {"type": "noul", "instructions": "`photo` 中有杯子吗？"},
    "material": {
      "type": "choice",
      "instructions": "`photo` 中的杯子主要是什么材质？",
      "criteria": {"ceramic": "陶瓷", "glass": "玻璃", "other": "其他材质或没有杯子"}
    },
    "mug": {"type": "box", "instructions": "`photo` 中靠近水槽的杯子"}
  }
}

data_base64 需要完整的标准 base64 内容，不能使用示例中的占位文字。生成方式见下面的 Python 示例。

Asset 字段

字段	类型	用法
type	"image"	可省略；提供时必须是 image
format	"png"、"jpg"、"jpeg"	base64 方式必填，须与文件实际格式一致；multipart 可省略
data_base64	字符串	文件的标准 base64 编码，保留 = 补位，不含空白、换行或 data: 前缀
part	字符串	multipart 文件字段名，与 request 区分

通常只提供 part 或 data_base64 中的一种。如果两者都有，以 part 对应的文件为准。

引用匹配

引用只在字符串值中生效，对象键、问题 ID 和选项名不会替换。引用既可以独占整个字符串，也可以嵌在句子中。每个 asset 必须至少被 state、instructions 或 criteria 引用一次；未使用的 asset 会使请求失败。

建议每张图片使用独立 UUID，避免短引用意外匹配正文。字符串整体等于一个引用时优先按整体处理；句子内从左向右匹配，不重复覆盖同一片文本。一个引用最多 1,024 个 UTF-8 字节，全部引用合计最多 65,536 字节。

文件只上传一次，但引用几次就会在模型输入中出现几次，每次都占上下文和输入 token。多个问题共用的照片宜放在 state，用字段路径引用；问题专用的参考图则放在该问题中。

上传图片

multipart 文件上传

multipart 直接传文件，避免 base64 带来的体积增加。第一部分必须叫 request，内容为 JSON；每张图单独一个文件部分，名称对应 asset 的 part。

curl https://api.xiangxinai.cn/v1/systemone \
  -H "Authorization: Bearer $XIANGXIN_API_KEY" \
  -F 'request={
    "model": "xiangxin-3.0",
    "state": {"photo": "<image-7f8d9c>"},
    "assets": {"<image-7f8d9c>": {"type": "image", "part": "photo-file"}},
    "questions": {
      "mug": {"type": "box", "instructions": "`photo` 中的杯子"}
    }
  };type=application/json' \
  -F 'photo-file=@kitchen.jpg;type=image/jpeg'

所有部分名称必须非空且互不重复。文件部分与 assets 一一对应：缺失文件、多余文件、两个 asset 共用同一个文件部分都将返回错误。支持的文件 Content-Type 是 image/png、image/jpeg、image/jpg、application/octet-stream 或省略。

base64 JSON

任何可以发送 JSON 的 HTTP 客户端都能调用。下面是可直接运行的 Python 示例（先执行 pip install requests，准备好 kitchen.jpg 和环境变量 XIANGXIN_API_KEY）：

import base64
import os
import uuid
from pathlib import Path

import requests

ref = str(uuid.uuid4())
response = requests.post(
    "https://api.xiangxinai.cn/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['XIANGXIN_API_KEY']}"},
    json={
        "model": "xiangxin-3.0",
        "state": {"photo": ref},
        "assets": {
            ref: {
                "type": "image",
                "format": "jpg",
                "data_base64": base64.b64encode(Path("kitchen.jpg").read_bytes()).decode("ascii"),
            }
        },
        "questions": {
            "visible": {"type": "noul", "instructions": "`photo` 中有杯子吗？"},
            "mug": {"type": "box", "instructions": "`photo` 中的杯子"},
        },
    },
)
response.raise_for_status()
print(response.json()["answers"])

Node.js 18+ 可以使用内置 fetch（把文件名与 format 改成实际文件）：

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const ref = randomUUID();
const response = await fetch("https://api.xiangxinai.cn/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XIANGXIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "xiangxin-3.0",
    state: { photo: ref },
    assets: {
      [ref]: { type: "image", format: "jpg", data_base64: (await readFile("kitchen.jpg")).toString("base64") },
    },
    questions: { mug: { type: "box", instructions: "`photo` 中的杯子" } },
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).answers);

图片放在哪里

State：所有问题共用

state 可以同时包含多张图和业务信息，例如 {"before": "<image-a>", "after": "<image-b>", "rule": "比较装配前后的变化"}。问题通过反引号路径指明要比较的图片，也可以按时间顺序组织成数组，参考状态。

Instructions：某题的参考图

"instructions": "判断 photo 中的人与证件照 <image-badge> 是否是同一个人"。此时参考图只属于这一题，不会自动传给其他问题。

Criteria：用样图定义选项或档位

例如 Choice 的 criteria 可以写成：

{
  "qualified": {"description": "合格装配", "examples": ["<image-good-1>", "<image-good-2>"]},
  "faulty": "<image-faulty>",
  "unknown": "无法与任何样图匹配"
}

description 和 examples 是此例自定义的 JSON 字段。Noul 的 true/false 描述、Score 的档位描述也可以引用图片；使用方法见结构化问题。答案中的判据或 legend 仍保留引用字符串。

大小与格式限制

项目	限制
格式	静态 PNG 或 JPEG；不接受动画 PNG
单文件	最多 16 MiB，base64 按解码后的大小计算
宽度、高度	每边 280–1568 像素，包含边界
总像素	78,400–2,458,624
HTTP 请求体	最多 32 MiB，包含 JSON、base64 和 multipart 包装
全部图片	处理后合计不超过 32 MiB
引用展开后的请求	图片按引用次数计入，与文本和结构合计不超过 32 MiB

文件在处理时会去掉元数据并重新编码，处理后的体积可能变化。API 不会为不合规格的图片自动缩放；任何图片无效都会让整次请求失败。

发送前把图片旋转到正确方向、转换为静态 PNG 或标准 JPEG，再自行缩放到范围内。EXIF 方向不会自动应用。大图找小物体时，先裁剪目标区域；截图、PDF 页面也应先导出为合规格图片。

用量与错误

图片使用输入 token，与文字按同一单价计费，合计在响应 usage.input_tokens 中。重复引用会增加图片 token，用量也计入上下文和速率限制。输出免费。

状态	原因
400	文件损坏、格式或 base64 无效、尺寸过小、未引用 asset、multipart 对应关系有误，或 Box 未提供图片
413	文件、尺寸、请求体、引用长度或展开后体积超限
422	问题字段校验失败或模型上下文超限

完整鉴权、额度、限流及重试说明见 API 参考。Box 文档说明如何理解坐标、检查存在性并裁剪目标。