API 参考

概述

Karma Box 提供了完整的 RESTful API，让开发者能够将 AI 智能体的能力集成到自己的应用中。

认证

所有 API 请求需要通过 Bearer Token 进行认证：

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.karmabox.ai/v1/agents

你可以在 设置 → API 密钥 中创建和管理 API Key。

核心接口

智能体管理

| 方法 | 端点 | 描述 | |------|------|------| | GET | /v1/agents | 获取智能体列表 | | POST | /v1/agents | 创建新智能体 | | GET | /v1/agents/:id | 获取智能体详情 | | PUT | /v1/agents/:id | 更新智能体配置 | | DELETE | /v1/agents/:id | 删除智能体 |

对话与会话

| 方法 | 端点 | 描述 | |------|------|------| | POST | /v1/chat/completions | 发送对话消息 | | GET | /v1/sessions | 获取会话列表 | | GET | /v1/sessions/:id | 获取会话历史 | | DELETE | /v1/sessions/:id | 删除会话 |

技能与工作流

| 方法 | 端点 | 描述 | |------|------|------| | GET | /v1/skills | 获取已安装技能 | | POST | /v1/skills/install | 安装技能 | | POST | /v1/workflows/run | 运行工作流 | | GET | /v1/workflows/:id/status | 查询工作流状态 |

对话接口详解

发送消息

POST /v1/chat/completions

请求体：

{
  "agent_id": "agent_abc123",
  "messages": [
    {
      "role": "user",
      "content": "帮我分析这份季度报告"
    }
  ],
  "stream": true,
  "tools": ["web_search", "code_execution"]
}

响应：

{
  "id": "msg_xyz789",
  "agent_id": "agent_abc123",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "我来帮你分析这份报告..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 256
  }
}

流式响应

设置 stream: true 开启 SSE 流式传输：

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"agent_id":"agent_abc123","messages":[{"role":"user","content":"你好"}],"stream":true}' \
     https://api.karmabox.ai/v1/chat/completions

智能体配置

创建智能体

POST /v1/agents

{
  "name": "数据分析师",
  "description": "专业的数据分析和可视化助手",
  "model": "claude-sonnet-4-5-20250929",
  "system_prompt": "你是一位专业的数据分析师...",
  "tools": ["code_execution", "file_upload"],
  "temperature": 0.7,
  "max_tokens": 4096
}

速率限制

| 计划 | 请求频率 | 每日上限 | |------|---------|---------| | 免费版 | 10 次/分钟 | 100 次/天 | | 专业版 | 60 次/分钟 | 5,000 次/天 | | 企业版 | 300 次/分钟 | 不限 |

超出限制时，API 将返回 429 Too Many Requests。

错误处理

API 使用标准 HTTP 状态码：

| 状态码 | 含义 | |--------|------| | 200 | 请求成功 | | 400 | 请求参数错误 | | 401 | 认证失败 | | 403 | 权限不足 | | 404 | 资源不存在 | | 429 | 请求过于频繁 | | 500 | 服务器内部错误 |

错误响应格式：

{
  "error": {
    "code": "invalid_api_key",
    "message": "提供的 API Key 无效或已过期"
  }
}

SDK

我们提供以下语言的官方 SDK：

Python: pip install karmabox
JavaScript/TypeScript: npm install @karmabox/sdk
Go: go get github.com/karmabox/go-sdk

Python 示例

from karmabox import KarmaBox

client = KarmaBox(api_key="YOUR_API_KEY")

response = client.chat.completions.create(
    agent_id="agent_abc123",
    messages=[
        {"role": "user", "content": "你好，帮我写一段代码"}
    ]
)

print(response.choices[0].message.content)

TypeScript 示例

import { KarmaBox } from '@karmabox/sdk';

const client = new KarmaBox({ apiKey: 'YOUR_API_KEY' });

const response = await client.chat.completions.create({
  agentId: 'agent_abc123',
  messages: [
    { role: 'user', content: '你好，帮我写一段代码' }
  ]
});

console.log(response.choices[0].message.content);

Webhook

配置 Webhook 接收实时事件通知：

{
  "url": "https://your-app.com/webhook",
  "events": [
    "agent.message.created",
    "workflow.completed",
    "workflow.failed"
  ]
}

更多详细的 API 文档和交互式 API Explorer，请访问 api.karmabox.ai/docs。