📡 API 参考

NeoWeb AI 提供完整的 REST API，支持程序化调用对话、管理模型、技能和对话历史。Base URL：http://localhost:3001

认证

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

http 
X-Api-Token: your-api-token

在 设置 → API → 生成 Token 中获取你的 API Token。

ℹ️ API Token 存储在本地，不与任何云端服务共享。

端点总览

方法路径说明
POST/api/chat发送聊天消息
GET/api/status服务状态
GET/api/models列出所有模型
GET/api/tools列出所有工具
GET/api/skills列出所有技能
POST/api/skills创建技能
DELETE/api/skills/:id删除技能
GET/api/conversations获取对话列表
POST/api/memory添加记忆
DELETE/api/memory/:id删除记忆
GET /api/status

获取服务运行状态和基本信息。无需认证。

响应：

json 
{
  "status": "running",
  "version": "1.0.0",
  "uptime": 3600,
  "models": 3,
  "skills": 18,
  "tools": 97
}
POST /api/chat

向 AI 发送消息并获取回复。支持普通模式和流式输出（SSE）。

请求体：

json 
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "帮我列出当前目录的文件"
    }
  ],
  "skillId": "skill-id-optional",
  "stream": false,
  "temperature": 0.7,
  "maxTokens": 4096
}

响应（普通模式）：

json 
{
  "id": "msg_01abc123",
  "role": "assistant",
  "content": "当前目录下有以下文件：\n...",
  "model": "gpt-4o",
  "toolCalls": [
    {
      "tool": "fs_list",
      "input": { "path": "." },
      "output": ["file1.txt", "file2.js"]
    }
  ],
  "usage": {
    "inputTokens": 42,
    "outputTokens": 156
  },
  "createdAt": "2026-03-31T05:00:00Z"
}

流式响应（stream: true）：

text 
data: {"type":"text","delta":"当前目录"}
data: {"type":"text","delta":"下有以下文件："}
data: {"type":"tool_use","tool":"fs_list","input":{"path":"."}}
data: {"type":"tool_result","tool":"fs_list","output":["file1.txt"]}
data: {"type":"done","usage":{"inputTokens":42,"outputTokens":156}}
data: [DONE]
GET /api/models

获取所有已配置的 AI 模型列表。

json 
{
  "models": [
    {
      "id": "model_01",
      "name": "GPT-4o",
      "provider": "openai",
      "isDefault": true,
      "isActive": true
    },
    {
      "id": "model_02",
      "name": "Claude Sonnet",
      "provider": "anthropic",
      "isDefault": false,
      "isActive": true
    }
  ]
}
GET /api/skills

获取所有技能（预置 + 自定义）。

json 
{
  "skills": [
    {
      "id": "skill_code_review",
      "name": "代码审查",
      "description": "专业代码审查...",
      "icon": "🔍",
      "isBuiltin": true,
      "isActive": false
    }
  ]
}
POST /api/skills

创建自定义技能。

json 
// 请求体
{
  "name": "我的助手",
  "description": "专注于 Python 开发",
  "icon": "🐍",
  "systemPrompt": "你是一位 Python 专家...",
  "tools": ["fs_read", "shell_exec", "python_exec"],
  "temperature": 0.3
}

// 响应
{
  "id": "skill_custom_01",
  "name": "我的助手",
  "createdAt": "2026-03-31T05:00:00Z"
}
DELETE /api/skills/:id

删除自定义技能（内置技能不可删除）。

json 
// 响应
{ "success": true, "id": "skill_custom_01" }
GET /api/conversations

获取对话历史列表。支持分页：?page=1&limit=20

json 
{
  "conversations": [
    {
      "id": "conv_01",
      "title": "代码审查任务",
      "model": "gpt-4o",
      "messageCount": 12,
      "createdAt": "2026-03-31T04:00:00Z",
      "updatedAt": "2026-03-31T05:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}
POST /api/memory

向 AI 记忆系统添加条目（AI 会在后续对话中参考这些信息）。

json 
// 请求体
{
  "content": "用户偏好：代码注释用中文，函数名用英文驼峰命名",
  "tags": ["preference", "coding-style"]
}

// 响应
{
  "id": "mem_01",
  "content": "用户偏好：代码注释用中文...",
  "createdAt": "2026-03-31T05:00:00Z"
}
DELETE /api/memory/:id

删除指定的记忆条目。

json 
{ "success": true, "id": "mem_01" }

错误处理

所有错误返回标准格式：

json 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "无效的 API Token",
    "status": 401
  }
}
状态码错误码说明
401UNAUTHORIZEDToken 无效或未提供
400BAD_REQUEST请求参数错误
404NOT_FOUND资源不存在
429RATE_LIMITED触发上游模型限流
500INTERNAL_ERROR服务内部错误

示例：curl 调用

bash 
curl -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: your-token" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

📡 API Reference

NeoWeb AI provides a complete REST API for programmatic access to conversations, models, skills, and history. Base URL: http://localhost:3001

Authentication

All API requests require an API Token in the HTTP header:

http
X-Api-Token: your-api-token

Get your token from Settings → API → Generate Token.

ℹ️ API Tokens are stored locally and never shared with any cloud service.

Endpoint Overview

MethodPathDescription
POST/api/chatSend a chat message
GET/api/statusService status
GET/api/modelsList all models
GET/api/toolsList all tools
GET/api/skillsList all skills
POST/api/skillsCreate a skill
DELETE/api/skills/:idDelete a skill
GET/api/conversationsGet conversation list
POST/api/memoryAdd a memory entry
DELETE/api/memory/:idDelete a memory entry
GET/api/status

Get service status and basic info. No auth required.

json
{
  "status": "running",
  "version": "1.0.0",
  "uptime": 3600,
  "models": 3,
  "skills": 18,
  "tools": 97
}
POST/api/chat

Send a message to AI and get a response. Supports normal and streaming (SSE) modes.

Request body:

json
{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "List files in current directory"}],
  "skillId": "skill-id-optional",
  "stream": false,
  "temperature": 0.7,
  "maxTokens": 4096
}

Response:

json
{
  "id": "msg_01abc123",
  "role": "assistant",
  "content": "The current directory contains:\n...",
  "model": "gpt-4o",
  "toolCalls": [{"tool": "fs_list", "input": {"path": "."}, "output": ["file1.txt"]}],
  "usage": {"inputTokens": 42, "outputTokens": 156},
  "createdAt": "2026-03-31T05:00:00Z"
}

Streaming response (stream: true):

text
data: {"type":"text","delta":"The current directory"}
data: {"type":"tool_use","tool":"fs_list","input":{"path":"."}}
data: {"type":"tool_result","tool":"fs_list","output":["file1.txt"]}
data: {"type":"done","usage":{"inputTokens":42,"outputTokens":156}}
data: [DONE]
POST/api/skills

Create a custom skill.

json
// Request body
{
  "name": "My Assistant",
  "description": "Focused on Python development",
  "icon": "🐍",
  "systemPrompt": "You are a Python expert...",
  "tools": ["fs_read", "shell_exec", "python_exec"],
  "temperature": 0.3
}
// Response
{
  "id": "skill_custom_01",
  "name": "My Assistant",
  "createdAt": "2026-03-31T05:00:00Z"
}

Error Handling

All errors return a standard format:

json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API Token",
    "status": 401
  }
}
StatusCodeDescription
401UNAUTHORIZEDInvalid or missing token
400BAD_REQUESTInvalid request parameters
404NOT_FOUNDResource not found
429RATE_LIMITEDUpstream model rate limited
500INTERNAL_ERRORInternal server error

Example: curl

bash
curl -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: your-token" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'