API 参考

把一份 state 和一组带类型的 questions 发给象信，拿回结构化的 answers，每个问题一个。第一次接触的话，建议先读原语总览。

评估接口

POST https://api.xiangxinai.cn/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体

每个请求的顶层结构如下。questions 中的每一项都是一个由你命名的、带类型的问题。

statestring | object | array必填

要评估的内容。纯文本用字符串；对话记录、业务记录、应用的当前状态等结构化数据用对象或数组。格式与写法建议见状态。

modelstring

处理请求的模型，省略时为 "xiangxin-latest"。可取的值：别名 xiangxin-latest，或版本号 xiangxin-2.0.0。其他名称返回 404 model_not_found。

别名的含义、价格与速率限制见模型。

questionsmap<string, Question>必填

由带类型的 Question 对象组成的映射。键由你决定，答案会以同样的键返回。

‹问题 ID›Question

你自己起的键。对应的 Answer 会以同一个 ID 返回。ID 不会发送给模型，也不参与推理，所以完整的问题必须写在 instructions 里。

{
  "state": "订单 20260921-7788 已经五天没发货了，今天再不发我就申请退款。",
  "model": "xiangxin-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "用户是否表达了紧迫感或时间压力？"
    }
  }
}

限制

项	限制	超出时
单请求总 token（state + 全部问题）	64k	422 max_tokens_exceeded
state + 最长的单个问题	32k	422 max_tokens_exceeded
Choice 选项数	≤ 255	422 Too many choices. Must have at most 255 choices.
Score 档位数	2–10	422（校验错误列表）
速率（每组织，默认）	250,000 token/秒；1,200 请求/分钟	429，带 retry-after
输入模态	仅文本，UTF-8 JSON	—

问题类型

Question 有三种，由 type 字段区分。三者都有 type 和 instructions，各自的 criteria 形状不同。

instructions 可以是字符串、对象或数组。如果一个问题较长、带有额外背景，或者需要引用一段数据，可以把它拆成结构化对象：问题放在一个字段里，数据放在其他字段里，再在问题中用反引号写出字段名来引用，和引用 state 里嵌套字段的写法一样：

"instructions": {
  "疑似重复候选人": {
    "姓名": "王磊",
    "城市": "杭州",
    "最近雇主": "某电商公司"
  },
  "question": "这份简历与 `疑似重复候选人` 是否是同一个人？"
}

更多写法见进阶：结构化。

Noul

是非题。返回答案为"是"的概率。详见 Noul。

type"noul"必填

instructionsstring | object | array必填

要判断的是非问题，或一个让模型判断真假的陈述。写成对象时，可以把问题放在一个字段、把它引用的数据放在其他字段，见进阶：结构化。

criteriaobject

可选，对"是"与"否"含义的补充说明。

truestring | object | array

什么情况算"是"（值接近 1）。

falsestring | object | array

什么情况算"否"（值接近 0）。

{
  "state": "订单 20260921-7788 已经五天没发货了，今天再不发我就申请退款。",
  "model": "xiangxin-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "用户是否表达了紧迫感或时间压力？",
      "criteria": {
        "true": "明确提到期限、催促或不尽快处理的后果",
        "false": "只是陈述情况，没有时间上的要求"
      }
    }
  }
}

Choice

从你定义的一组选项中选一个。返回选中的选项和完整的概率分布。详见 Choice。

type"choice"必填

instructionsstring | object | array必填

需要模型做出的选择。写成对象时，可以把问题放在一个字段、把它引用的数据放在其他字段，见结构化的 instructions 与 criteria。

criteriamap<string, string | object | array | null>必填

选项 → 选项说明的映射；某个选项不需要额外说明时写 null。每个 Choice 最多 255 个选项。

‹选项›string | object | array | null

你自己起的键，值是这个选项的说明。与问题 ID 不同，选项键本身也会被模型读到，请用有含义的名字（如 after_sales），不要用 opt1、opt2。

{
  "state": "订单 20260921-7788 已经五天没发货了，今天再不发我就申请退款。",
  "model": "xiangxin-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "这条消息应该由哪个团队处理？",
      "criteria": {
        "presale": "售前咨询：商品参数、优惠活动、库存",
        "logistics": "物流：发货、配送进度、快递异常",
        "after_sales": "售后：退换货、退款、质量问题"
      }
    }
  }
}

Score

按你定义的档位给 state 打分。返回按各档概率加权得到的分值。详见 Score。

type"score"必填

instructionsstring | object | array必填

要评估的维度。写成对象时，可以把问题放在一个字段、把它引用的数据放在其他字段，见进阶：结构化。

criteriaarray<string | object | array>必填

按从低到高排列的档位描述。第 0 项对应 0 分，第 1 项对应 1 分，依此类推。至少 2 档，最多 10 档。

{
  "state": "订单 20260921-7788 已经五天没发货了，今天再不发我就申请退款。",
  "model": "xiangxin-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "用户的不满程度如何？",
      "criteria": ["平静，只是询问", "略有不满", "明显不满，语气强硬", "非常愤怒，威胁投诉或曝光"]
    }
  }
}

响应体

每个问题一个答案，以你提供的问题 ID 为键返回。

modelstring必填

实际作答的模型版本号，例如 xiangxin-2.0.0。即使请求里写的是别名，这里也返回具体版本。

answersmap<string, Answer>必填

每个问题一个 Answer，键与 questions 中的问题 ID 相同。

‹问题 ID›Answer

你在 questions 中起的同一个 ID。

usageobject必填

本次请求的 token 用量。

input_tokensinteger

输入 token 数，计费依据。

output_tokensinteger

输出 token 数，不计费。

{
  "model": "xiangxin-2.0.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.9
    }
  },
  "usage": { "input_tokens": 55, "output_tokens": 17 }
}

响应头

响应头	说明
x-request-id	本次请求的唯一 ID。联系技术支持时请附上
x-xiangxin-model-ms	模型推理耗时（毫秒），保留一位小数，例如 1.8
x-xiangxin-total-ms	网关处理总耗时（毫秒），包含鉴权、排队、计费等
retry-after	仅在 429 / 529 时出现，建议等待的秒数（整数）
retry-after-ms	同上，精确到毫秒；两者都有时优先用它

答案类型

每个答案都带有与问题相同的 type。Choice 和 Score 的答案还带有 0–1 之间的 confidence，由答案的概率分布计算得出，见置信度。

Noul 答案

type"noul"必填

noulnumber必填

是非题的答案，取值 0（否）到 1（是），即答案为"是"的概率。Noul 没有单独的 confidence，0.5 附近即表示拿不准。

{
  "model": "xiangxin-2.0.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.91
    }
  },
  "usage": { "input_tokens": 81, "output_tokens": 18 }
}

Choice 答案

type"choice"必填

choicestring必填

概率最高的选项。

probabilitiesmap<string, number>必填

每个选项对应的概率（总和为 1）。

‹选项›number

你在 criteria 中定义的一个选项。

confidencenumber必填

模型有多确定，由 probabilities 计算得出。

{
  "model": "xiangxin-2.0.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "logistics",
      "confidence": 0.4,
      "probabilities": { "presale": 0.01, "logistics": 0.6, "after_sales": 0.39 }
    }
  },
  "usage": { "input_tokens": 98, "output_tokens": 44 }
}

Score 答案

type"score"必填

scorenumber必填

按各档概率加权得到的分值，可以落在两档之间。

legendmap<string, string>必填

档位编号 → 你提供的档位描述。

probabilitiesmap<string, number>必填

每一档（字符串形式的编号）对应的概率（总和为 1）。

‹档位›number

档位编号，字符串形式，与 legend 的键一致。

confidencenumber必填

模型有多确定，由 probabilities 计算得出。

{
  "model": "xiangxin-2.0.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.81,
      "confidence": 0.61,
      "legend": { "0": "平静，只是询问", "1": "略有不满", "2": "明显不满，语气强硬", "3": "非常愤怒，威胁投诉或曝光" },
      "probabilities": { "0": 0.04, "1": 0.23, "2": 0.61, "3": 0.12 }
    }
  },
  "usage": { "input_tokens": 93, "output_tokens": 217 }
}

数值规则

量	计算方式
概率	保留两位小数，并重新归一化使总和恰为 1
Choice confidence	(n · peak − 1) / (n − 1)，n 为选项数，peak 为最大概率。均匀分布时为 0，全部集中在一个选项时为 1
Score score	Σ i · pᵢ，即各档编号按概率加权求和
Score confidence	max pᵢ，即最可能那一档的概率

用上面的示例核对：Choice 有 3 个选项、峰值 0.6，(3 × 0.6 − 1) / 2 = 0.4；Score 为 0 × 0.04 + 1 × 0.23 + 2 × 0.61 + 3 × 0.12 = 1.81，confidence = 0.61。

相同的请求多次调用，处于中间区间的概率可能有小幅抖动（推理使用低精度浮点并做批处理），接近 0 或 1 的值基本不变。不要在测试中对概率做精确相等断言，参见象信 2.0 已知短板。

错误

出错时返回标准 HTTP 状态码，响应体为 JSON：{"detail": ...}。detail 通常是一个简短的机器可读字符串，参数校验失败时是一个错误列表。只有成功的请求才按 usage.input_tokens 计费，返回任何错误状态码的请求都不收费。

状态码	detail	含义与处理	可重试	SDK 异常
401 Unauthorized	invalid_api_key	缺少 Authorization 头、密钥写错，或密钥已被禁用/删除。检查 XIANGXIN_API_KEY 和 Bearer 前缀，到控制台确认密钥状态	否	AuthenticationError
402 Payment Required	insufficient_balance	组织可用余额 ≤ 0。充值或开启自动充值，见定价与额度	否（充值后再试）	InsufficientBalanceError
404 Not Found	model_not_found	model 写了不存在的名称，例如 xiangxin-lastest。可用名称见模型	否	NotFoundError
422 Unprocessable Entity	校验错误列表	缺少必填字段、type 拼错、Score 档位少于 2 或多于 10、criteria 形状不对。按 detail[].loc 修正请求体	否	UnprocessableEntityError
422 Unprocessable Entity	Too many choices. Must have at most 255 choices.	单个 Choice 超过 255 个选项。先在代码里粗筛候选，或改成分层选择	否	UnprocessableEntityError
422 Unprocessable Entity	max_tokens_exceeded	全部内容超过 64k token，或 state + 最长问题超过 32k token。精简 state，或把问题拆到多个请求	否	UnprocessableEntityError
429 Too Many Requests	超限说明	超出组织速率限制。按 retry-after 等待后重试、降低并发；需要更高配额请联系 wanglei@xiangxinai.cn	是	RateLimitError
529 Overloaded	overloaded	服务暂时过载，或所有模型后端暂不可用。指数退避后重试	是	OverloadedError
500 / 502 / 503 / 504	—	服务内部错误或网关超时。指数退避后重试；持续出现请带上 x-request-id 联系支持	是	InternalServerError
无响应	—	DNS、TLS、网络中断等，没有收到 HTTP 响应。检查网络与代理	视情况	APIConnectionError
超时	—	在客户端设定的时间内没有收到响应。适当调大超时	视情况	APITimeoutError

同一状态码下的不同情形可以用异常的 detail 区分，例如 UnprocessableEntityError 的 detail 可能是校验错误列表、max_tokens_exceeded 或选项过多的说明。"SDK 异常"一列在 Python 与 JavaScript SDK 中类名相同，完整层级见 Python 的异常与 JavaScript SDK 参考。

例如缺少 Authorization 头或密钥无效时：

{"detail": "invalid_api_key"}

422 有两种形态。字段校验失败时，detail 是一个错误列表，loc 指出出错的位置。下面是 Choice 缺少 criteria、Score 只给了一档时的真实响应：

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "questions", "department", "choice", "criteria"],
      "msg": "Field required",
      "input": {"type": "choice", "instructions": "这条消息应该由哪个团队处理？"}
    }
  ]
}

{
  "detail": [
    {
      "type": "too_short",
      "loc": ["body", "questions", "f", "score", "criteria"],
      "msg": "List should have at least 2 items after validation, not 1",
      "input": ["平静"],
      "ctx": {"field_type": "List", "min_length": 2, "actual_length": 1}
    }
  ]
}

触发业务限制时，detail 是一个字符串：

{"detail": "Too many choices. Must have at most 255 choices."}

处理限流

收到 429 Too Many Requests 或 529 Overloaded 时，不要立即原样重试，而是用指数退避：响应带 retry-after-ms / retry-after 时按它等待；否则按 0.5 秒、1 秒、2 秒……递增等待（单次不超过 5 秒）并加入随机抖动；设置重试上限，超过后把错误交给上层处理。408 和所有 5xx 也可以这样重试；401、402、404、422 原样重试只会得到同样的错误。

Python SDK 与 JavaScript SDK 默认就是这样做的：最多重试 2 次，对 408、429 和所有 5xx（含 529）生效，并遵守 retry-after-ms / retry-after（超过 60 秒的建议改按指数退避）。使用 SDK 的默认重试策略时不需要额外处理，见重试。