# Chat

Base URL `https://api.sniphunter.com`

兼容聊天和事件流接口。

# Chat


## POST /api/v1/chat

Chat
发送聊天消息 (基于 QueryEngine)

- 自动创建或使用已有会话
- 支持工具调用
- 支持上下文记忆

示例:
```
POST /api/v1/chat
{
    "message": "帮我提取这个视频的素材 https://...",
    "stream": false
}
```

```json
{
  "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/health

Health Check
健康检查

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## GET /api/v1/chat/sessions

List Sessions
列出会话（基于 QueryEngine 进程内缓存）

```json
{
  "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
获取会话信息

```json
{
  "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
删除会话

```json
{
  "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}/messages

Get Session Messages
获取会话消息历史

```json
{
  "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/stream

Chat 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", ...}}
```

```json
{
  "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/tools

List Tools
获取可用工具列表

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


# Components

```json
{
  "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"
    }
  }
}
```