聊天图片生成

基本信息

项目	说明
接口路径	POST /v1/chat/image
响应类型	application/json
认证方式	API Key + 请求签名（认证说明）

WARNING

该接口为同步阻塞接口，图片生成期间连接保持，完成后一次性返回结果。生成过程通常需要 30～90 秒，请设置足够长的超时时间（建议 ≥ 120 秒）。

TIP

自定义角色同样支持该接口。系统会使用角色内部的 ComfyUI workflow（comfy_prompt）进行图片生成。 若你迁移或修复过角色数据，请确保 comfy_prompt 为完整的 ComfyUI workflow 节点结构（包含 class_type），否则 RunPod 可能返回 invalid_prompt。

请求体

{
  "agentId": "agent-uuid",
  "conversationId": "conv-uuid",
  "text": "一个穿着红色连衣裙的女孩站在樱花树下",
  "language": "zh",
  "metadata": {}
}

字段	类型	必填	说明
agentId	string	✅	智能体 ID
conversationId	string	✅	会话 ID，由 /v1/chat/conversation 接口创建获取
text	string	✅	图片描述文本
language	string	✅	语言代码，如 zh、en
metadata	object	❌	扩展字段，可传空对象 {}

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "base64Image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "metadata": {}
  },
  "traceId": "9fU0kfWy3E8YFGjS5S8bLPlAXG8xhdTH",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.base64Image	string	生成的图片，格式为 data:image/png;base64,<数据>
data.metadata	object	请求时传入的 metadata 原样返回

错误响应

HTTP 状态码	说明
401	鉴权失败（缺少请求头、时间戳过期、API Key 无效或签名错误）
200	业务错误：success=false，常见 code 为 10400 / 10404 / 10500，错误原因见 message

业务错误（HTTP 200）：

message	说明
Invalid API key	API Key 无效或已禁用
Too many requests, please try again later	触发频率限制
API key usage limit reached	达到总调用次数上限
Agent not found	智能体不存在
Agent missing image generation config	智能体未配置图片生成参数

客户端示例

async function generateImage(apiKey, apiSecret, userId, agentId, conversationId, text) {
  const body = { agentId, conversationId, text, language: 'zh' }
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body)

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), 120000) // 120s 超时

  try {
    const response = await fetch('/v1/chat/image', {
      method: 'POST',
      headers,
      body: JSON.stringify(body),
      signal: controller.signal,
    })

    const result = await response.json()
    if (!result.success) { console.error('生成失败：', result.message); return null }

    return result.data.base64Image // "data:image/png;base64,..."
  } finally {
    clearTimeout(timeoutId)
  }
}