admin 管理员组

文章数量: 1184232

AI对话框接口定义文档

1. 概述

本文档定义了AI对话框(Conversation)列表接口和单个对话框中所有消息(Message)列表接口的详细规范。

2. 接口基础信息

  • 基础URL: https://api.example/v1
  • 认证方式: Bearer Token
  • 响应格式: JSON

3. 接口定义

3.1 获取对话列表接口

接口描述

获取当前用户的所有AI对话列表，支持分页和排序。

请求
  • 方法: GET
  • 路径: /conversations
  • Headers:
    • Authorization: Bearer <token>
    • Content-Type: application/json
查询参数
参数名类型必填描述示例
pageinteger否页码，从1开始1
page_sizeinteger否每页数量，默认2020
sortstring否排序字段，支持: created_at(默认), updated_atupdated_at
orderstring否排序顺序，desc(默认)或ascasc
响应

成功响应 (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "id": "conv_123456",
        "title": "关于机器学习的问题讨论",
        "created_at": "2023-05-20T10:30:00Z",
        "updated_at": "2023-05-20T11:45:00Z",
        "message_count": 15,
        "model": "gpt-4",
        "tags": ["机器学习", "AI"]
      },
      {
        "id": "conv_789012",
        "title": "Python编程问题",
        "created_at": "2023-05-19T09:15:00Z",
        "updated_at": "2023-05-19T09:30:00Z",
        "message_count": 5,
        "model": "gpt-3.5",
        "tags": ["Python"]
      }
    ]
  }
}

错误响应

  • 401 Unauthorized: 认证失败
  • 500 Internal Server Error: 服务器内部错误

3.2 获取对话消息列表接口

接口描述

获取指定对话中的所有消息列表。

请求
  • 方法: GET
  • 路径: /conversations/{conversation_id}/messages
  • Headers:
    • Authorization: Bearer <token>
    • Content-Type: application/json
路径参数
参数名类型必填描述
conversation_idstring是对话ID
查询参数
参数名类型必填描述示例
pageinteger否页码，从1开始1
page_sizeinteger否每页数量，默认2050
sortstring否排序字段，支持: created_at(默认)created_at
orderstring否排序顺序，asc(默认)或descdesc
响应

成功响应 (200 OK)

{
  "code": 0,
  "message": "success",
  "data": {
    "conversation_id": "conv_123456",
    "title": "关于机器学习的问题讨论",
    "total_messages": 15,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "id": "msg_1",
        "role": "user",
        "content": "什么是机器学习？",
        "created_at": "2023-05-20T10:30:00Z",
        "status": "success",
        "tokens": 8
      },
      {
        "id": "msg_2",
        "role": "assistant",
        "content": "机器学习是人工智能的一个分支...",
        "created_at": "2023-05-20T10:31:00Z",
        "status": "success",
        "tokens": 120,
        "model": "gpt-4"
      },
      {
        "id": "msg_3",
        "role": "user",
        "content": "有哪些主要类型？",
        "created_at": "2023-05-20T10:35:00Z",
        "status": "success",
        "tokens": 7
      }
    ]
  }
}

错误响应

  • 401 Unauthorized: 认证失败
  • 404 Not Found: 对话不存在
  • 500 Internal Server Error: 服务器内部错误

4. 数据模型

4.1 Conversation 对象

字段类型描述
idstring对话唯一ID
titlestring对话标题
created_atstring (ISO8601)创建时间
updated_atstring (ISO8601)最后更新时间
message_countinteger消息总数
modelstring使用的主要AI模型
tagsarray[string]对话标签

4.2 Message 对象

字段类型描述
idstring消息唯一ID
rolestring消息角色: user/assistant/system
contentstring消息内容
created_atstring (ISO8601)创建时间
statusstring状态: success/failed/pending
tokensinteger消息消耗的token数量
modelstring (可选)AI回复时使用的模型

5. 错误码

错误码描述
0成功
1001认证失败
1002权限不足
1003对话不存在
2001参数错误
9999服务器内部错误

6. 版本历史

版本日期描述
1.0.02023-05-20初始版本

本文标签： 接口 消息 文档 AI

版权声明：本文标题：AI对话与消息管理接口文档 内容由网友自发贡献，该文观点仅代表作者本人， 转载请联系作者并注明出处：http://www.roclinux.cn/b/1765774855a3413545.html， 本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。