对话生图 · Generate Image for Message

为对话中的某一条消息（通常是 AI 回复）生成一张配图。生成时会参考角色卡的角色图以保持形象一致。常用于在聊天界面里给剧情画面「配图」。

接口地址

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

生图耗时较长（可能超过普通接口 90s），与对话补全一样走 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 GenImageForMessageRequest {
  /** 对话存档 ID */
  archiveId: string;
  /** 要配图的消息 ID */
  messageId: string;
  /** 角色 ID（用于获取角色参考图） */
  characterId: string;
}

响应（JSON）

返回更新后的消息对象，其中 imageUrl 为生成的图片地址。若本次未能产出图片，则响应中不含 imageUrl。

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

计费

• 按账号图片设置（宽高比 / 分辨率）预估积分并在生成前扣费；若生成失败会自动退还。
• 非 VIP 用户有免费生图额度限制，额度用尽后需开通 VIP 或充值。

示例

请求：

curl -X POST "https://api.xiangcao.ai/gen-image-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": "我很好，谢谢你的关心～" }] }
  ],
  "imageUrl": "https://img.xiangcao.ai/3a1b....png/public"
}

错误处理

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