灵感回复

接口说明

基于当前对话上下文，为用户生成 1～3 条回复建议，引导用户更自然地与智能体互动。

基本信息

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

请求体

{
  "agentId": "agent-uuid",
  "conversationId": "conv-uuid",
  "language": "en"
}

字段	类型	必填	说明
agentId	string	✅	智能体 ID
conversationId	string	✅	会话 ID，由 /v1/chat/conversation 接口创建获取
language	string	❌	语言代码，如 en、zh、ja；默认 en

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "suggestions": [
      "Tell me more about yourself",
      "What do you like to do for fun?",
      "Can you describe your ideal day?"
    ]
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.suggestions	string[]	回复建议列表，最多 3 条

错误响应

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

业务错误（HTTP 200）：

message	说明
agentId is required	缺少 agentId 字段
conversationId is required	缺少 conversationId 字段
Invalid API key	API Key 无效或已禁用
Too many requests, please try again later	触发频率限制
API key usage limit reached	达到总调用次数上限

客户端示例

async function getInspire(apiKey, apiSecret, userId, agentId, conversationId, language = 'en') {
  const body = { agentId, conversationId, language }
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body, {
    url: '/v1/chat/inspire',
  })

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

  const result = await response.json()
  if (!result.success) { console.error('灵感回复失败：', result.message); return [] }
  return result.data.suggestions // string[]
}

配合 SSE 流的完整用法

// 在 SSE 流结束后获取回复建议
if (parsed.type === 'message_saved') {
  const suggestions = await getInspire(API_KEY, API_SECRET, USER_ID, agentId, conversationId)
  // 展示建议按钮，供用户一键发送
  renderSuggestions(suggestions)
}

使用时序

Client                     AI-DOL Open API
  │                               │
  │  SSE: [DONE]                  │
  │<──────────────────────────────│
  │  SSE: {type:message_saved}    │
  │<──────────────────────────────│
  │  POST /v1/chat/inspire        │
  │──────────────────────────────>│  生成回复建议
  │  { suggestions: [...] }       │
  │<──────────────────────────────│