估算消息价格 · Calculate Model Price

根据模型与 token 设置，估算发送一条对话消息预计消耗的钻石（credits）。常用于在调用 创建对话补全 之前，给用户预览本次扣费。

该接口与对话实际扣费走同一套计算逻辑，返回的是「单条消息」的预估价格，结果与真实扣费一致。

接口地址

POST https://xiangcao.ai/api/calculate-model-price

该接口为普通接口，使用 POST 方法，仅做计算、不产生扣费。

鉴权

需要在请求头携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

缺少或无效的 Token 会返回 401。

请求体（JSON）

是否走官方角色路径由服务端根据 characterId 判断，客户端无需传 isOfficial。

类型定义（TypeScript）

interface CalculatePriceRequest {
  /** 模型 ID；命中官方角色时可不传 */
  modelId: number;
  /** 上下文 tokens（包含 maxOutputTokens） */
  maxContextTokens: number;
  /** 单条回复最大输出 tokens */
  maxOutputTokens: number;
  /** 角色卡最大 tokens（不影响价格） */
  maxCharacterTokens?: number;
  /** 内容模式，默认 roleplay */
  contentFormat?: 'roleplay' | 'script' | 'novel';
  /** script 模式下的最大输出 tokens */
  scriptMaxOutputTokens?: number;
  /** 是否开启冒险日志（额外加价） */
  knowledgeEnabled?: boolean;
  /** 是否自动生成状态栏（额外加价，官方角色忽略） */
  statusBarAutoGenerate?: boolean;
  /** 状态栏最大输出 tokens（200-2000） */
  statusBarMaxOutputTokens?: number;
  /** 角色 ID，用于判断官方角色并覆盖部分设置 */
  characterId?: string;
}

响应（JSON）

interface CalculatePriceResponse {
  /** 单条消息预计消耗的钻石（credits）总数 */
  estimatedTotalPrice: number;
}

计费说明

价格单位为钻石（credits），主要受以下因素影响：

• 模型：不同模型单价不同，能力越强通常越贵。
• token 设置：maxContextTokens / maxOutputTokens 越大，单条消息越贵。
• 附加项：开启冒险日志（knowledgeEnabled）、状态栏（statusBarAutoGenerate）会在基础价上额外增加费用。

具体计费规则由服务端统一计算，请以本接口返回的 estimatedTotalPrice 为准，其口径与对话实际扣费一致。

命中官方角色时：强制使用官方模型与固定输出 tokens，且不计状态栏费用，此时 modelId 与状态栏相关参数会被忽略。

模型 ID 参考

模型列表与可用性以 get-model-options 接口返回为准，上表仅供参考。

示例

请求：

curl -X POST "https://xiangcao.ai/api/calculate-model-price" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": 2,
    "maxContextTokens": 7000,
    "maxOutputTokens": 400,
    "contentFormat": "roleplay",
    "knowledgeEnabled": false,
    "statusBarAutoGenerate": false
  }'

响应：

{
  "estimatedTotalPrice": 310
}

错误处理

出错时返回相应 HTTP 状态码及 JSON。