对话选项生成 · Generate Plot Options

为对话中的某一条 AI 回复生成一组「剧情选项」（presetOptions）——即几条建议的用户回复，用户点选后会作为自己的消息发送，用来推动剧情。

接口地址

POST https://api.xiangcao.ai/gen-options-for-message

生成耗时较长，与对话补全一样走 api.xiangcao.ai 长连接通道，请把客户端超时设置得长一些。

鉴权

需要在请求头携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

缺少或无效的 Token 会返回 401。接口对每个用户有调用频率限制（rate limit）。

前置条件

本接口是给「已存在的消息」生成选项，因此你需要先有一段对话：

1. 先调用 创建对话补全 得到 archiveId 和 AI 回复消息的 id。
2. 再用这两个 ID（加上 characterId）调用本接口为该消息生成选项。

请求体（JSON）

只接受以下三个字段，全部必填。选项数量、生成语言、用户人设等由账号设置（model settings）决定，不在本接口传入。

类型定义（TypeScript）

interface GenOptionsForMessageRequest {
  /** 对话存档 ID */
  archiveId: string;
  /** 要生成选项的消息 ID */
  messageId: string;
  /** 角色 ID（用于获取角色卡上下文） */
  characterId: string;
}

响应（JSON）

返回更新后的消息对象，其中 presetOptions 为生成的选项文本数组。若本次未能产出选项，则该数组为空或缺失。

interface GenOptionsForMessageResponse {
  id?: string;
  role: "user" | "assistant" | "system";
  /** 原始文本；目前下发为空字符串（兼容保留），正文请用 contentItems */
  content: string;
  /** 服务端解析后的渲染指令（Server-Driven UI），消息正文以此为准 */
  contentItems?: ContentItem[];
  /** 生成的剧情选项；点选后作为 user 消息发送 */
  presetOptions?: string[];
  // …其余字段与 ArchiveMessage 一致，详见「创建对话补全」文档
}

计费

• 按账号设置的选项数量计费，并在生成前扣费；若生成失败会自动退还。
• 积分不足时返回 402。

示例

请求：

curl -X POST "https://api.xiangcao.ai/gen-options-for-message" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "archiveId": "arc_001",
    "messageId": "msg_a1",
    "characterId": "abc123"
  }'

响应（节选）：

{
  "id": "msg_a1",
  "role": "assistant",
  "content": "",
  "contentItems": [
    { "type": "paragraph", "segments": [{ "type": "text", "content": "我很好，谢谢你的关心～" }] }
  ],
  "presetOptions": [
    "那我们一起出去走走吧？",
    "你今天有什么打算？",
    "其实……我有件事想告诉你。"
  ]
}

错误处理

出错时返回相应 HTTP 状态码及 JSON：{ "success": false, "error": "..." }。