Skip to main content

​
认证相关

  1. 访问 Wolian AI 客户端管理
  2. 使用你的账户登录
  3. 点击”+ 创建”按钮创建新的客户端
  4. 确保密钥状态为”已激活”（绿色标识）
  5. 点击复制按钮，复制并安全保存 API Key
注意：密钥仅在创建时完整显示一次，请妥善保管。
如果怀疑 API Key 泄露，请立即： 1. 在 Wolian AI 平台 中撤销该密钥 2. 创建新的 API Key 并激活 3. 更新所有使用旧 Key 的应用 4. 监控账户使用情况是否异常
常见原因：
  • API Key 格式错误（检查是否包含 Bearer 前缀）
  • API Key 已过期或被撤销
  • 请求头中缺少 Authorization 字段
  • 使用了错误的环境变量名
解决方法：
# 检查 API Key 格式
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://huajune.duliday.com/api/v1/models

​
模型与工具

调用 GET /api/v1/models 端点：
curl -X GET https://huajune.duliday.com/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY"
返回你账户可访问的所有模型列表。
可能原因：
  • 该模型不在你的许可列表中
  • 账户权限不足
  • 模型 ID 拼写错误
解决方法：
  1. 使用 GET /api/v1/models 查看可用模型
  2. 联系销售团队申请权限
  3. 检查模型 ID 是否正确（区分大小写）
在请求中添加 allowedTools 数组，并提供必要的上下文：
启用工具示例
{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
  ],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": { ... },
    "replyPrompts": { ... }
  }
}
查看可用工具：
查看工具列表
curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"
每个工具的 requiredContext 不同：
  • zhipin_reply_generator: 需要 configData 和 replyPrompts ✅ 推荐用于业务场景
  • bash: 需要 sandboxId（E2B 沙盒环境）⚠️ 一般不推荐使用
推荐：使用 zhipin_reply_generator 等业务工具，它们更贴合实际的招聘场景，无需额外的沙盒环境配置。
使用 GET /api/v1/tools 查看每个工具的具体要求。
花卷智能体 API 采用服务端自动执行模式，一次请求即可完成所有工具调用。完整流程：
  1. 用户发送请求：包含 allowedTools 参数和必要的上下文
  2. 服务端自动处理：
    • AI 决定需要调用工具
    • 服务端自动执行工具
    • AI 理解执行结果
    • 生成最终回复
  3. 返回完整历史：响应包含所有中间步骤（tool-call 和 tool-result）
请求示例
{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    { "role": "user", "content": "候选人问：薪资待遇怎么样？" }
  ],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": { ... },
    "replyPrompts": { ... }
  }
}
无需多轮请求：服务端自动完成所有工具调用，最多可执行 30 步。
详细说明请参阅：
工具在服务端自动执行，有两种方式查看执行过程：方式 1：使用流式输出（实时监控）
流式监控
const response = await fetch(url, {
  body: JSON.stringify({
    stream: true,
    allowedTools: ["zhipin_reply_generator"],
    context: { ... },
    ...
  })
});

const reader = response.body.getReader();
// 监听 event: tool 事件，实时查看工具调用过程
方式 2：检查响应中的 messages 数组（非流式）
查看完整历史
const data = await response.json();

// 响应包含完整执行历史
data.data.messages.forEach(msg => {
  msg.parts.forEach(part => {
    if (part.type === 'dynamic-tool') {
      console.log('工具调用:', part.toolName);
      console.log('输入:', part.input);
      if (part.output) {
        console.log('输出:', part.output);
      }
    }
  });
});
详见工具调用 - 流式输出

​
功能使用

特性流式 (stream: true)非流式 (stream: false)
响应方式实时逐字返回一次性返回完整内容
用户体验打字机效果，感知更快需要等待完整生成
适用场景聊天界面、交互应用后台处理、批量任务
Token 计费相同相同
推荐：面向用户的应用使用流式输出。
建议在以下情况启用消息剪裁：
  • 对话轮次超过 20 轮
  • 历史消息包含大量重复信息
  • 需要优化成本
  • 遇到上下文长度限制
不建议在以下情况使用：
  • 短对话（< 10 轮）
  • 需要完整历史信息的任务
  • 关键业务对话
三种方式：方式 1：直接指定（推荐）
{
  "systemPrompt": "你是一个专业的Python导师"
}
✅ 最简单，直接覆盖 system prompt方式 2：使用 promptType + context.systemPrompts
{
  "promptType": "bossZhipinSystemPrompt",
  "context": {
    "systemPrompts": {
      "bossZhipinSystemPrompt": "你是BOSS直聘招聘助手..."
    }
  }
}
✅ promptType 同时决定工具集和 system prompt✅ 适合多场景管理方式 3：使用默认值 不设置任何参数，使用 "You are a helpful AI assistant."详见系统提示词文档
promptType 有两个独立的作用：1. 决定工具集（内置、强制）
  • 通过内置的 PROMPT_TOOL_MAPPING 自动启用对应工具
  • 例如：bossZhipinSystemPrompt 自动启用招聘相关工具
2. 查找 system prompt（可选）
  • 从 context.systemPrompts[promptType] 查找提示词文本
  • 如果没有提供 context.systemPrompts，使用默认 system prompt
示例：
{
  "promptType": "bossZhipinSystemPrompt"
  // 效果：
  // ✅ 启用招聘工具集
  // ℹ️ 使用默认 system prompt（因为没有提供 context.systemPrompts）
}
查询可用的 promptType：
curl -X GET https://huajune.duliday.com/api/v1/prompt-types \
  -H "Authorization: Bearer YOUR_API_KEY"

​
性能与成本

立即生效的方法：
  1. 启用消息剪裁（节省 40-70%）
  2. 使用成本更低的模型（如 Qwen Plus）
  3. 精简系统提示词
  4. 实现结果缓存
长期优化：
  1. 监控 Token 使用情况
  2. 批量处理请求
  3. 仅在必要时启用工具
  4. 定期审查和优化提示词
详见性能优化指南
可能原因：
  1. 输入消息太长（检查 Token 数量）
  2. 启用了多个复杂工具
  3. 网络延迟
  4. 服务端负载高
解决方法：
  • 启用消息剪裁
  • 减少不必要的工具
  • 使用流式输出改善用户体验
  • 检查网络连接
默认限制：
  • 每秒请求数 (RPS): 10
  • 每分钟请求数 (RPM): 500
  • 并发请求数: 5
超过限制会收到 429 Too Many Requests 错误。如需更高限额，请联系销售团队。

​
错误处理

常见原因：
  • 请求参数格式错误
  • 缺少必需的工具上下文
  • 无效的 promptType
解决方法：
  1. 检查错误消息中的 details 字段
  2. 使用 validateOnly: true 预检查配置
  3. 查看 API 文档确认参数格式
说明超过了速率限制。解决方法：
// 实现指数退避重试
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}
每个响应都包含 correlationId：
const data = await response.json();
console.log('Correlation ID:', data.correlationId);
向技术支持报告问题时，请提供：
  1. correlationId
  2. 请求时间
  3. 错误消息
  4. 请求参数（不要包含 API Key）

​
集成与开发

花卷智能体 API 是标准的 REST API，支持所有能发送 HTTP 请求的编程语言：
  • JavaScript/TypeScript (Node.js, Browser)
  • Python
  • Java
  • Go
  • Ruby
  • PHP
  • C#/.NET
  • 等等…
文档中提供了 JavaScript 和 Python 的详细示例。
推荐使用流式输出：
function ChatBox() {
  const [messages, setMessages] = useState([]);

  const sendMessage = async (text) => {
    const response = await fetch('https://huajune.duliday.com/api/v1/chat', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'anthropic/claude-3-7-sonnet-20250219',
        messages: [...messages, { role: 'user', content: text }],
        stream: true
      })
    });

    const reader = response.body.getReader();
    // 处理流式响应...
  };

  return <div>{/* UI 组件 */}</div>;
}
详见流式输出功能
建议：
  1. 使用流式输出，可以实时看到进度
  2. 设置合理的超时时间（建议 60-120 秒）
  3. 实现重试机制
  4. 向用户显示加载状态
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 120000); // 120秒

try {
  const response = await fetch(url, {
    signal: controller.abort,
    ...options
  });
} finally {
  clearTimeout(timeoutId);
}

​
还有问题？

查看 API 文档

完整的 API 端点参考文档

联系技术支持

发送邮件获取人工支持

调试指南

学习调试技巧和工具

性能优化

优化 API 调用性能和成本