Hero AI API 文档

完整的 RESTful API 参考，助你快速集成 Hero AI Agent 能力到任何应用。

📋 概览

所有 API 请求的 Base URL：

https://api.herowith.com/v1

当前版本：v1　｜　协议：HTTPS　｜　数据格式：JSON

速率限制

套餐	请求上限	并发数
Free	50 次/小时	2
Cloud	500 次/小时	10
Enterprise	5,000 次/小时	50

🔐 认证鉴权

所有 API 请求需在 Header 中携带 Bearer Token：

Authorization: Bearer <your_access_token>

获取 Token

POST/auth/login

curl -X POST https://api.herowith.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

# 响应
{
  "access_token": "eyJhbGci...",
  "refresh_token": "dGhpcyBp...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

刷新 Token

POST/auth/refresh — 使用 refresh_token 获取新的 access_token。Token 过期后请求将返回 401，客户端应自动刷新后重试。

👤 用户 API

注册用户

POST/users/register

// 请求
{ "email": "new@example.com", "password": "SecureP@ss1", "name": "张三" }

// 响应 201
{ "id": "usr_a1b2c3", "email": "new@example.com", "name": "张三", "plan": "free", "created_at": "2026-03-01T08:00:00Z" }

登录

POST/auth/login — 同上认证鉴权章节。

获取当前用户

GET/users/me

更新用户信息

PUT/users/me

// 请求
{ "name": "张三丰", "avatar_url": "https://..." }

// 响应 200
{ "id": "usr_a1b2c3", "name": "张三丰", "updated_at": "2026-03-10T12:00:00Z" }

🤖 Agent API

创建 Agent

POST/agents

// 请求
{
  "name": "客服小助手",
  "description": "处理售前咨询和订单查询",
  "model": "claude-sonnet-4",
  "system_prompt": "你是一个专业的客服助手...",
  "temperature": 0.7,
  "channels": ["feishu", "wecom", "qq"]
}

// 响应 201
{
  "id": "agt_x9y8z7",
  "name": "客服小助手",
  "status": "draft",
  "model": "claude-sonnet-4",
  "created_at": "2026-03-10T08:00:00Z"
}

列表 / 详情 / 更新 / 删除

GET/agents — 获取所有 Agent 列表（支持 ?page=1&limit=20）

GET/agents/:id — 获取单个 Agent 详情

PUT/agents/:id — 更新 Agent 配置

DELETE/agents/:id — 删除 Agent（不可恢复）

部署 Agent

POST/agents/:id/deploy

// 响应 200
{ "id": "agt_x9y8z7", "status": "deploying", "deploy_url": "https://herowith.com/a/x9y8z7" }

查询部署状态

GET/agents/:id/status

{ "status": "running", "uptime": 86400, "requests_today": 142, "avg_latency_ms": 320 }

💬 消息 API

发送消息

POST/agents/:id/messages

// 请求
{ "content": "我想查询订单状态", "user_id": "u_12345", "session_id": "sess_abc" }

// 响应 200
{
  "message_id": "msg_001",
  "reply": "好的，请提供您的订单号，我帮您查询。",
  "tokens_used": 156,
  "latency_ms": 280
}

获取消息历史

GET/agents/:id/messages?limit=20&session_id=sess_abc

Webhook 回调格式

// Hero 主动推送到你的回调地址
{
  "event": "message.received",
  "agent_id": "agt_x9y8z7",
  "message": { "id": "msg_002", "content": "用户的新消息", "user_id": "u_12345" },
  "timestamp": "2026-03-10T12:30:00Z"
}

📡 渠道 API

绑定渠道

POST/channels/bind

// 飞书配置
{
  "agent_id": "agt_x9y8z7",
  "type": "feishu",
  "config": { "app_id": "cli_xxx", "app_secret": "xxx", "verification_token": "xxx" }
}

// Telegram 配置
{
  "agent_id": "agt_x9y8z7",
  "type": "telegram",
  "config": { "bot_token": "123456:ABC-DEF" }
}

// 微信配置
{
  "agent_id": "agt_x9y8z7",
  "type": "wechat",
  "config": { "app_id": "wx_xxx", "app_secret": "xxx", "token": "xxx", "aes_key": "xxx" }
}

// 企业微信配置（Bot WebSocket 模式，无需域名）
{
  "agent_id": "agt_x9y8z7",
  "type": "wecom",
  "config": { "bot_id": "BOT_ID", "bot_secret": "BOT_SECRET" }
}

// 企业微信配置（Bot + Agent 双模式）
{
  "agent_id": "agt_x9y8z7",
  "type": "wecom",
  "config": {
    "bot_id": "BOT_ID", "bot_secret": "BOT_SECRET",
    "corp_id": "CORP_ID", "agent_id": 1000001, "agent_secret": "AGENT_SECRET"
  }
}

// QQ 官方机器人配置
{
  "agent_id": "agt_x9y8z7",
  "type": "qq",
  "config": { "app_id": "QQ_APP_ID", "client_secret": "QQ_CLIENT_SECRET" }
}

解绑 / 列表

DELETE/channels/:id — 解绑渠道

GET/channels?agent_id=agt_x9y8z7 — 查看已绑定渠道列表

💳 支付 API

创建支付订单

POST/payments/create

// 请求
{ "plan": "cloud", "period": "monthly", "coupon": "HERO20" }

// 响应 201
{ "payment_id": "pay_001", "amount": 79.00, "currency": "CNY", "pay_url": "https://pay.herowith.com/pay_001", "expires_at": "2026-03-10T13:00:00Z" }

查询订单

GET/payments/:id

支付回调

POST/payments/callback

🔔 Webhook

事件类型

事件名称	说明	触发时机
agent.created	Agent 创建	调用 POST /agents
agent.deployed	Agent 部署完成	部署流程结束
agent.stopped	Agent 停止运行	手动停止或异常
message.received	收到用户消息	用户发送消息
message.replied	Agent 回复完成	生成回复后
payment.completed	支付成功	支付确认
payment.failed	支付失败	支付超时或拒绝
channel.bound	渠道绑定成功	渠道配置完成

签名验证

每个 Webhook 请求头包含 X-Hero-Signature，算法：

signature = HMAC-SHA256(your_webhook_secret, raw_request_body)

# Python 验证示例
import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert expected == request.headers["X-Hero-Signature"]

重试策略

Webhook 推送失败时最多重试 3 次，采用指数退避：

重试次数	延迟
第 1 次	10 秒
第 2 次	60 秒
第 3 次	300 秒

❌ 错误码

状态码	含义	常见原因与建议
400	请求无效	参数格式错误、缺少必填字段。检查请求体 JSON 格式。
401	未认证	Token 缺失或已过期。请刷新 Token 后重试。
403	无权限	当前用户无权操作此资源。检查套餐权限或角色。
404	未找到	资源不存在。检查 ID 是否正确。
409	冲突	资源状态冲突（如重复创建）。检查是否已存在。
422	不可处理	参数类型正确但值不合法。检查业务规则约束。
429	请求过多	超过速率限制。等待 X-RateLimit-Reset 后重试。
500	服务器错误	内部异常。请稍后重试或联系 support@herowith.com。

// 统一错误响应格式
{
  "error": {
    "code": 422,
    "type": "validation_error",
    "message": "Field 'name' is required",
    "request_id": "req_abc123"
  }
}

📦 SDK 示例

Python

# pip install hero-sdk
from hero import HeroClient

client = HeroClient(api_key="your_api_key")

# 创建 Agent
agent = client.agents.create(
    name="客服助手",
    model="claude-sonnet-4",
    system_prompt="你是专业客服..."
)

# 发送消息
reply = client.messages.send(
    agent_id=agent.id,
    content="你好，我想退货",
    user_id="u_123"
)
print(reply.text)  # Agent 的回复

Node.js

// npm i @hero/sdk
const { HeroClient } = require("@hero/sdk");
const hero = new HeroClient({ apiKey: "your_api_key" });

// 创建 Agent
const agent = await hero.agents.create({
  name: "客服助手",
  model: "claude-sonnet-4",
  systemPrompt: "你是专业客服..."
});

// 发送消息
const reply = await hero.messages.send({
  agentId: agent.id,
  content: "你好，我想查物流",
  userId: "u_456"
});
console.log(reply.text);

Go

// go get github.com/herowith/hero-sdk-go
package main

import (
    "fmt"
    hero "github.com/herowith/hero-sdk-go"
)

func main() {
    client := hero.NewClient("your_api_key")

    // 创建 Agent
    agent, _ := client.Agents.Create(&hero.AgentParams{
        Name:         "客服助手",
        Model:        "claude-sonnet-4",
        SystemPrompt: "你是专业客服...",
    })

    // 发送消息
    reply, _ := client.Messages.Send(agent.ID, &hero.MessageParams{
        Content: "你好，我想改地址",
        UserID:  "u_789",
    })
    fmt.Println(reply.Text)
}

🎓 智慧课堂使用指南

什么是 Hero AI 智慧课堂？

Hero AI 智慧课堂是一款基于 AI 的互动课程生成解决方案。上传一份 PDF 或文档，AI 将自动生成完整的互动课程，包括幻灯片、测验、模拟互动和 PBL 项目——让备课变得轻而易举。

如何启用

进入 Console → 解决方案 → 智慧课堂，点击「启用」即可激活。免费用户也可立即启用体验。

启用路径：Console → 解决方案 → 智慧课堂 → 启用
访问地址：http://learn.herowith.com

如何使用

三步生成互动课程：

1. 上传文档：支持 PDF、Word、PPT、TXT 等格式
2. 选择模型：根据需求选择 AI 模型（DeepSeek / GPT / Claude / Gemini / 通义等）
3. 生成课程：AI 自动分析文档内容，生成完整的互动课程

功能介绍

功能	说明
🖥️ AI 幻灯片	自动从文档内容生成结构化幻灯片，支持自定义主题
📝 智能测验	自动生成选择题、填空题、简答题，附带答案解析
💬 模拟互动	AI 扮演教师/学生角色，进行互动问答，加深理解
🎯 PBL 项目	生成项目式学习任务，培养实践能力
📤 课程导出	支持导出为 PDF、PPT 或分享链接

支持的模型

模型	提供商	特点
DeepSeek	深度求索	中文能力强，性价比高
GPT-4o	OpenAI	综合能力强，推理出色
Claude	Anthropic	长文本处理优秀，分析精准
Gemini	Google	多模态支持，图片理解
通义千问	阿里云	国产替代，稳定可靠

定价

套餐	课程限额	功能
Free	3 节/月	全部基础功能，社区模型
Cloud	无限制	全部功能，全部模型，优先生成，批量导出

常见问题