角色智能体（点卡模式）HTTP API 接口文档

📋 概述

角色智能体（点卡模式） HTTP API 服务是一个封装了认证、扣点、消息发送和任务追踪的完整解决方案。开发者只需调用一个接口，传入 api_key、card_id、role_id 和消息内容，即可自动完成整个流程并返回最终结果。点卡模式是将AI智能体的服务能力进行API化与Token化封装，使每一次专业咨询、每一份智能报告，都被量化为可消费的Token。用户通过购买"点卡"（即Token包），即可按需使用各类专家智能体服务。这个API不仅仅服务于志愿填报，任何可以被结构化的专业知识都可以被封装成角色智能体：每一部ibbot手机都可以成为一个"AI服务工作站"，每一位专业人才都可以培养自己的"数字员工"，通过点卡模式将能力开放给更多人。一个人能走多远，取决于有多少真正有帮助的数字伙伴。1人带领百万数字兵团的时代已然到来。

🚀 快速开始

服务地址

http://ai.ibbrole.html.dtns.top

接口列表

📖 接口详细说明

1. 核心接口：发送消息并等待结果

端点：/api/chat

方法：GET / POST

请求参数

请求示例

GET 方式：

http://ai.ibbrole.html.dtns.top/api/chat?api_key=dtns_xxx&card_id=xxx&role_id=xxx&message=生成报告：北京历史类3500，想学新闻&mode=task

POST 方式：

curl -X POST http://ai.ibbrole.html.dtns.top/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "dtns_xxx",
    "card_id": "xxx",
    "role_id": "role_xxx",
    "message": "生成报告：北京历史类3500，想学新闻",
    "mode": "task"
  }'

响应格式

任务模式响应（成功）：

{
  "success": true,
  "data": {
    "is_task": true,
    "task_id": "task_1781751992963_0573vy5q9",
    "status": "completed",
    "status_text": "✅ 已完成",
    "final_result": "嘿，同学，你那份纠结的北京历史类3500名志愿填报报告，叔已经给你整好了！\n\n来，直接点这个链接看你的专属报告：\n👉 http://web3apps.devibbot.html.dtns.top/...",
    "response": "嘿，同学，你那份纠结的北京历史类3500名志愿填报报告，叔已经给你整好了！...",
    "task_info": {
      "created_at": "2026-06-18T03:06:12.963Z",
      "ibbot_task_id": "ibbot_1781751984661_14d370a103ea",
      "is_complex_task": true
    },
    "cost": {
      "card_id": "67D19A81BC995C290802EC8EC7CA5AAE",
      "points": 1,
      "balance": 556
    },
    "tracking_history": [
      {"timestamp": "2026-06-18T03:08:28.359Z", "attempt": 22, "status": "pending"},
      {"timestamp": "2026-06-18T03:08:48.232Z", "attempt": 26, "status": "completed"}
    ],
    "elapsed_ms": 161202,
    "identification": {
      "isTask": true,
      "isChat": false,
      "confidence": 1,
      "reason": "用户指定了任务模式"
    }
  }
}

聊天模式响应：

{
  "success": true,
  "data": {
    "is_task": false,
    "response": "根据你的情况，我建议...",
    "identification": null,
    "cost": {
      "card_id": "xxx",
      "points": 1,
      "balance": 100
    },
    "elapsed_ms": 1234
  }
}

错误响应：

{
  "success": false,
  "error": "认证失败: 无效的 API Key"
}

响应字段说明

2. 简化接口：仅发送消息

端点：/api/send

方法：GET / POST

不自动追踪任务结果，适合不需要等待任务完成的场景。

请求参数

同 /api/chat，额外支持：

响应格式

{
  "success": true,
  "data": {
    "is_task": true,
    "task_result": {
      "task_id": "task_xxx",
      "success": true
    },
    "response": null
  },
  "cost": {
    "card_id": "xxx",
    "points": 1,
    "balance": 100
  }
}

3. 查询任务状态

端点：/api/task/:taskId

方法：GET / POST

请求参数

请求示例

http://ai.ibbrole.html.dtns.top/api/task/task_1781751992963_0573vy5q9?api_key=dtns_xxx&role_id=role_xxx

响应格式

{
  "success": true,
  "data": {
    "task_id": "task_1781751992963_0573vy5q9",
    "status": "completed",
    "status_text": "✅ 已完成",
    "final_result": "嘿，同学，你那份纠结的...",
    "is_completed": true,
    "task_data": {
      // 完整的任务数据
    }
  }
}

4. 健康检查

端点：/health

方法：GET / POST

响应格式

{
  "status": "ok",
  "timestamp": "2026-06-18T03:08:48.232Z",
  "activeTrackers": 3
}

🔧 配置说明

环境变量

启动命令

# 使用默认配置
node ibbrole_agent.js

# 自定义配置
BASE_URL=http://your-server.com PORT=3000 node ibbrole_agent.js

Docker 运行

docker run -d \
  -p 22001:22001 \
  -e BASE_URL=http://ibbot.devibbot.html.dtns.top \
  ibbrole-agent:latest

📝 完整调用示例

JavaScript (Node.js)

const axios = require('axios');

async function consultAgent(message) {
  const params = {
    api_key: 'dtns_78e301a57f66dcf9f0e74052a557bca14627c768f788a9b9c094c8003afba498',
    card_id: '67D19A81BC995C290802EC8EC7CA5AAE',
    role_id: 'role_1781657551308_84yfibimd',
    mode: 'task',
    message: message
  };

  try {
    const response = await axios.get('http://ai.ibbrole.html.dtns.top/api/chat', { params });
    if (response.data.success) {
      console.log('结果:', response.data.data.final_result);
      console.log('余额:', response.data.data.cost.balance);
    } else {
      console.error('错误:', response.data.error);
    }
  } catch (error) {
    console.error('请求失败:', error.message);
  }
}

// 使用示例
consultAgent('生成报告：北京历史类3500，想学新闻或者传播...');

Python

import requests

def consult_agent(message):
    params = {
        'api_key': 'dtns_78e301a57f66dcf9f0e74052a557bca14627c768f788a9b9c094c8003afba498',
        'card_id': '67D19A81BC995C290802EC8EC7CA5AAE',
        'role_id': 'role_1781657551308_84yfibimd',
        'mode': 'task',
        'message': message
    }
    
    try:
        response = requests.get('http://ai.ibbrole.html.dtns.top/api/chat', params=params)
        data = response.json()
        
        if data['success']:
            print('结果:', data['data']['final_result'])
            print('余额:', data['data']['cost']['balance'])
        else:
            print('错误:', data['error'])
    except Exception as e:
        print('请求失败:', str(e))

# 使用示例
consult_agent('生成报告：北京历史类3500，想学新闻或者传播...')

cURL

curl "http://ai.ibbrole.html.dtns.top/api/chat?api_key=dtns_xxx&card_id=xxx&role_id=role_xxx&mode=task&message=生成报告：北京历史类3500，想学新闻"

⚠️ 错误码说明

📊 任务状态说明

💎 点卡模式：让专业AI服务成为可交易的Token

什么是点卡模式？

点卡模式是将AI智能体的服务能力进行API化与Token化封装，使每一次专业咨询、每一份智能报告，都被量化为可消费的Token。用户通过购买"点卡"（即Token包），即可按需使用各类专家智能体服务。

核心优势

商业模式创新

"一次开发，无限分发"：开发者将角色智能体部署到ibbhub平台后，每一个客户端都可以成为该智能体的"服务节点"。用户通过点卡即可在任意节点激活并使用该智能体服务。

"Token即服务"：顶级专家的知识服务，从高不可攀的"咨询产品"变成了随手可得的"Token消费"。正如手机话费充值一样，用户按需购买，用完即止。

价值闭环：Token作为服务的计量单位，可在ibbhub生态内流通。智能体开发者、点卡发行方、算力贡献者均可通过Token流转获得收益，形成正向激励的价值网络。

应用场景扩展

这个API不仅仅服务于志愿填报，任何可以被结构化的专业知识都可以被封装成角色智能体：

• 教育领域：AI学科私教，按课时/按问题收费
• 医疗领域：AI健康顾问，按次咨询收费
• 法律领域：合同审查AI助理，按文档页数收费
• 设计领域：AI设计师，按产出物收费

每一部手机都可以成为一个"AI服务工作站"，每一位专业人才都可以培养自己的"数字员工"，通过点卡模式将能力开放给更多人。一个人能走多远，取决于有多少真正有帮助的数字伙伴。1人带领百万数字兵团的时代已然到来。