Chat
兼容聊天和事件流接口。
Base URL https://api.sniphunter.com
请求与响应中的 $ref 在 OpenAPI 的 components 中定义。
8 个接口
Chat
POST/api/v1/chatChat
发送聊天消息 (基于 QueryEngine) - 自动创建或使用已有会话 - 支持工具调用 - 支持上下文记忆 示例: ``` POST /api/v1/chat { "message": "帮我提取这个视频的素材 https://...", "stream": false } ```
{
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}GET/api/v1/chat/healthHealth Check
健康检查
{
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}GET/api/v1/chat/sessionsList Sessions
列出会话（基于 QueryEngine 进程内缓存）
{
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
},
"title": "Response List Sessions Api V1 Chat Sessions Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}GET/api/v1/chat/sessions/{session_key}Get Session
获取会话信息
{
"parameters": [
{
"name": "session_key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Session Key"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInfo"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}DELETE/api/v1/chat/sessions/{session_key}Delete Session
删除会话
{
"parameters": [
{
"name": "session_key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Session Key"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}GET/api/v1/chat/sessions/{session_key}/messagesGet Session Messages
获取会话消息历史
{
"parameters": [
{
"name": "session_key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Session Key"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"description": "返回消息数量",
"default": 50,
"title": "Limit"
},
"description": "返回消息数量"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "偏移量",
"default": 0,
"title": "Offset"
},
"description": "偏移量"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageInfo"
},
"title": "Response Get Session Messages Api V1 Chat Sessions Session Key Messages Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}POST/api/v1/chat/streamChat Stream
流式聊天 (基于 QueryEngine，SSE) 返回 Server-Sent Events 格式: ``` data: {"type": "session", "data": {"session_key": "..."}} data: {"type": "stream_request_start", "data": {"turn": 1}} data: {"type": "text_delta", "data": {"text": "Hello"}} data: {"type": "tool_use", "data": {"name": "video_extraction", ...}} data: {"type": "confirmation_request", "data": {"tool_call_id": "...", ...}} data: {"type": "tool_result", "data": {"success": true, ...}} data: {"type": "done", "data": {"status": "completed", ...}} ```
{
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}GET/api/v1/chat/toolsList Tools
获取可用工具列表
{
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}数据模型
展开 components
{
"schemas": {
"ChatRequest": {
"properties": {
"message": {
"type": "string",
"minLength": 1,
"title": "Message",
"description": "用户消息"
},
"session_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Key",
"description": "会话标识，不传则自动创建"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model",
"description": "指定模型"
},
"stream": {
"type": "boolean",
"title": "Stream",
"description": "是否流式返回",
"default": false
},
"images": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Images",
"description": "图片 URL 列表"
},
"context": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Context",
"description": "额外上下文"
},
"tools_allow": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools Allow",
"description": "允许的工具列表"
},
"tools_deny": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools Deny",
"description": "禁止的工具列表"
}
},
"type": "object",
"required": [
"message"
],
"title": "ChatRequest",
"description": "聊天请求",
"example": {
"message": "帮我提取这个视频 https://www.youtube.com/watch?v=xxx",
"stream": false
}
},
"ChatResponse": {
"properties": {
"session_key": {
"type": "string",
"title": "Session Key",
"description": "会话标识"
},
"run_id": {
"type": "string",
"title": "Run Id",
"description": "运行 ID"
},
"status": {
"type": "string",
"title": "Status",
"description": "状态: completed, failed, timeout"
},
"response": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Response",
"description": "助手回复"
},
"tool_calls": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls",
"description": "工具调用"
},
"tool_results": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Results",
"description": "工具结果"
},
"artifacts": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Artifacts",
"description": "生成的资产"
},
"tokens_used": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Tokens Used",
"description": "使用的 Token 数"
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "耗时 (毫秒)"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error",
"description": "错误信息"
}
},
"type": "object",
"required": [
"session_key",
"run_id",
"status",
"duration_ms"
],
"title": "ChatResponse",
"description": "聊天响应",
"example": {
"duration_ms": 5000,
"response": "我已经成功提取了视频素材...",
"run_id": "run_xyz",
"session_key": "agent:default:user:123:session:abc",
"status": "completed",
"tokens_used": 1234
}
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"MessageInfo": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"role": {
"type": "string",
"title": "Role"
},
"content": {
"type": "string",
"title": "Content"
},
"tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Tokens"
},
"tool_calls": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"role",
"content",
"tokens",
"tool_calls",
"created_at"
],
"title": "MessageInfo",
"description": "消息信息"
},
"SessionInfo": {
"properties": {
"session_key": {
"type": "string",
"title": "Session Key"
},
"agent_id": {
"type": "string",
"title": "Agent Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"message_count": {
"type": "integer",
"title": "Message Count"
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
}
},
"type": "object",
"required": [
"session_key",
"agent_id",
"user_id",
"message_count",
"total_tokens",
"created_at",
"updated_at"
],
"title": "SessionInfo",
"description": "会话信息"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
},
"securitySchemes": {
"HTTPBearer": {
"type": "http",
"scheme": "bearer"
}
}
}