AIChat App API Reference

1. Base URLs

生产环境使用以下两个服务地址。客户端应按服务职责分流调用。

Service	Base URL
`LoginService`	https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run
`ChatService`	https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run

2. Global Conventions

所有业务接口共享同一套认证、编码和错误返回规则。建议前端先把这些基础能力封装好，再接 endpoint。

2.1 Content Types

普通接口返回 application/json; charset=utf-8。
流式聊天返回 text/event-stream; charset=utf-8。
POST 请求默认使用 Content-Type: application/json。

2.2 Authentication

Authorization: Bearer <access_token>

2.3 Default Test Account

Field	Value
`phone_number`	`10086`
`country_code`	`86`
`verify_code`	`1234`

测试账号调用 /send_code 时不会触发真实短信，调用 /login 时会绕过阿里云验证码校验，并返回 is_test_account: true。

2.4 Standard Success Response

{
  "success": true,
  "message": "ok"
}

2.5 Standard Error Response

{
  "success": false,
  "code": "ErrorCode",
  "message": "错误说明"
}

2.6 Common Error Codes

code	Description
`InvalidInput`	缺少必填参数或参数格式不正确
`InvalidPhoneNumber`	手机号格式不合法
`InvalidVerifyCode`	验证码格式不合法
`VerifyFailed`	验证码错误或已过期
`Unauthorized`	JWT 缺失、无效、过期或用户不存在
`RoleNotFound`	`role_code` 不存在
`InvalidImage`	图片 base64 非法
`MissingApiKey`	大模型 API Key 未配置
`MissingDatabaseConfig`	数据库配置缺失
`DatabaseError`	数据库异常
`UpstreamHTTPError`	上游模型 HTTP 错误
`NetworkError`	网络异常
`InternalError`	服务内部异常

3. Data Models

以下是客户端最常接触的核心数据模型。建议在客户端显式建模，避免依赖非结构化文本。

3.1 User

{
  "uid": "3ddc9f2be4efad9c2d6491bb",
  "phone_number": "13800138000",
  "country_code": "86"
}

3.2 Role

{
  "role_code": "naitang",
  "nickname": "奶糖",
  "intro": "一只会撒娇、会贴贴、会蹭蹭人的猫咪系陪伴角色。",
  "avatar_url": "https://zzz-pet.oss-cn-hangzhou.aliyuncs.com/image/chat_avatar_cat.jpg",
  "background_url": "https://zzz-pet.oss-cn-hangzhou.aliyuncs.com/image/chat_bg_cat.jpg",
  "opening_message": "喵呜，我是奶糖，今天也想黏在你身边陪你聊天呀。你想先跟我说说现在的心情，还是让我蹭蹭你再开始？"
}

3.3 HistoryMessage

{
  "id": 1,
  "sender_role": "user",
  "content": "今天有点累。",
  "has_image": false,
  "is_partial": false,
  "created_at": "2026-03-22T15:20:21"
}

3.4 Stream Chunk

{
  "id": "...",
  "choices": [
    {
      "delta": {
        "content": "你好"
      }
    }
  ]
}

4. Endpoint Index

用于快速浏览完整接口面。每个条目都对应后面的详细 Reference 段落。

LoginService

GET /health

operation_id: login_health · auth: none

POST /send_code

operation_id: send_code · auth: none

POST /login

operation_id: login · auth: none

ChatService

GET /chat/roles

operation_id: chat_roles · auth: none

POST /chat/stream

operation_id: chat_stream · auth: bearer_jwt · response: sse

GET /chat/history

operation_id: chat_history · auth: bearer_jwt

POST /chat/clear

operation_id: chat_clear · auth: bearer_jwt

5. LoginService Reference

登录服务负责短信验证码发送与验证码登录。前端集成时主要使用 `send_code` 和 `login` 两个 operation。

GET /health

Operation IDlogin_health

Authnone

Full URLhttps://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run/health

{
  "success": true,
  "service": "login",
  "message": "ok"
}

POST /send_code

Operation IDsend_code

Authnone

Content Typeapplication/json

Request Body Schema

Field	Type	Required	Default	Description
`phone_number`	string	yes	-	手机号
`country_code`	string	no	`86`	国家码
`source_ip`	string	no	server-derived	用户 IP

{
  "phone_number": "10086",
  "country_code": "86"
}

Success Response Examples

{
  "success": true,
  "message": "验证码已发送",
  "request_id": "cfe5ef7e-7b97-4ea3-bd47-bd8e38c50bfd",
  "biz_id": "685905873551347376^0"
}

{
  "success": true,
  "message": "测试账号验证码固定为 1234",
  "request_id": "TEST-LOGIN",
  "biz_id": "TEST-LOGIN",
  "is_test_account": true
}

Common Error Responses

HTTP Status	code	Description
`400`	`InvalidPhoneNumber`	手机号格式错误
`400/500`	`SendCodeFailed`	短信平台返回失败

POST /login

Operation IDlogin

Authnone

ResponseJWT

Request Body Schema

Field	Type	Required	Default	Description
`phone_number`	string	yes	-	手机号
`country_code`	string	no	`86`	国家码
`verify_code`	string	yes	-	短信验证码
`source_ip`	string	no	server-derived	用户 IP

Success Response Example

{
  "success": true,
  "message": "登录成功",
  "token_type": "Bearer",
  "access_token": "<JWT>",
  "expires_in": 604800,
  "user": {
    "uid": "<uid>",
    "phone_number": "10086",
    "country_code": "86"
  },
  "is_test_account": true
}

Common Error Responses

HTTP Status	code	Description
`400`	`InvalidPhoneNumber`	手机号格式错误
`400`	`InvalidVerifyCode`	验证码格式错误
`401`	`VerifyFailed`	验证码错误、过期或测试账号验证码错误
`500`	`DatabaseError`	数据库异常

6. ChatService Reference

聊天服务提供角色列表、流式聊天、历史记录与清空聊天能力。会话维度为“用户 + 角色”。

GET /chat/roles

Operation IDchat_roles

Authnone

Role Count4 fixed roles

当前接口只返回角色展示信息，不返回内部 Prompt，也不支持自定义角色。

Success Response Example

{
  "success": true,
  "roles": [
    {
      "role_code": "naitang",
      "nickname": "奶糖",
      "intro": "一只会撒娇、会贴贴、会蹭蹭人的猫咪系陪伴角色。",
      "avatar_url": "https://zzz-pet.oss-cn-hangzhou.aliyuncs.com/image/chat_avatar_cat.jpg",
      "background_url": "https://zzz-pet.oss-cn-hangzhou.aliyuncs.com/image/chat_bg_cat.jpg",
      "opening_message": "喵呜，我是奶糖，今天也想黏在你身边陪你聊天呀。你想先跟我说说现在的心情，还是让我蹭蹭你再开始？"
    }
  ]
}

POST /chat/stream

Operation IDchat_stream

Authbearer_jwt

Response TypeSSE

服务端会自动拼接“当前用户 + 当前角色”的历史消息。兼容旧字段 prompt，但新接入统一使用 message。

Request Headers

Authorization: Bearer <JWT>
Content-Type: application/json

Request Body Schema

Field	Type	Required	Default	Description
`role_code`	string	yes	-	角色编码
`message`	string	no	-	用户文本；纯图片请求时可为空
`prompt`	string	no	-	兼容字段，等价于 `message`
`image_base64`	string	no	-	图片 base64
`image_mime_type`	string	no	`image/jpeg`	图片 MIME 类型
`temperature`	number	no	model default	模型参数
`top_p`	number	no	model default	模型参数
`max_tokens`	number	no	model default	模型参数
`presence_penalty`	number	no	model default	模型参数
`frequency_penalty`	number	no	model default	模型参数

SSE Contract

每条事件格式为 data: <payload>\n\n。
结束标记为 data: [DONE]。
客户端始终按 JSON 解析，再从 choices[0].delta.content 中提取文本。

data: {"id":"...","choices":[{"delta":{"content":"你好"}}]}

data: {"id":"...","choices":[{"delta":{"content":"呀"}}]}

data: [DONE]

Common Error Responses

HTTP Status	code	Description
`400`	`InvalidInput`	缺少 `role_code` 或缺少 `message/image_base64`
`400`	`InvalidImage`	图片内容非法
`401`	`Unauthorized`	JWT 缺失、非法或过期
`404`	`RoleNotFound`	角色不存在
`500`	`MissingApiKey`	模型配置缺失
`500`	`DatabaseError`	数据库异常

GET /chat/history

Operation IDchat_history

Authbearer_jwt

Queryrole_code required

Query Parameters

Field	Type	Required	Description
`role_code`	string	yes	角色编码

Success Response Example

{
  "success": true,
  "role_code": "naitang",
  "messages": [
    {
      "id": 1,
      "sender_role": "user",
      "content": "今天有点累。",
      "has_image": false,
      "is_partial": false,
      "created_at": "2026-03-22T15:20:21"
    },
    {
      "id": 2,
      "sender_role": "assistant",
      "content": "那先让我陪你缓一缓，好不好？",
      "has_image": false,
      "is_partial": false,
      "created_at": "2026-03-22T15:20:25"
    }
  ]
}

POST /chat/clear

Operation IDchat_clear

Authbearer_jwt

Scope当前用户 + 当前角色

Request Body Schema

Field	Type	Required	Description
`role_code`	string	yes	角色编码

Request Example

{
  "role_code": "naitang"
}

Success Response Example

{
  "success": true,
  "message": "当前聊天已清空",
  "deleted_count": 12
}

7. Recommended Integration Flow

调用 POST /send_code
调用 POST /login 获取 JWT
调用 GET /chat/roles 获取角色列表
进入会话页后，调用 GET /chat/history?role_code=...
调用 POST /chat/stream
流式结束后，再次拉取历史刷新本地会话
用户点击清空时，调用 POST /chat/clear

8. Client Examples

7.1 Login Example

const loginRes = await fetch("https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "10086",
    country_code: "86",
    verify_code: "1234"
  })
});

const loginData = await loginRes.json();
const token = loginData.access_token;

7.2 SSE Example

const response = await fetch("https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run/chat/stream", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`
  },
  body: JSON.stringify({
    role_code: "wanqing",
    message: "杭州现在天气怎么样？",
    temperature: 0.8
  })
});

9. Machine-Readable API Catalog

用于 Codex、自动化工具或客户端生成器读取的机器可读 JSON 清单。保留 `operation_id`、`full_url_example`、schema 和响应类型等关键字段。

展开 / 收起 JSON 清单

{
  "version": "v1",
  "updated_at": "2026-03-26",
  "environment": "production",
  "services": {
    "LoginService": {
      "base_url": "https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run",
      "endpoints": [
        {
          "operation_id": "login_health",
          "method": "GET",
          "path": "/health",
          "full_url_example": "https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run/health",
          "auth": "none",
          "response_type": "json"
        },
        {
          "operation_id": "send_code",
          "method": "POST",
          "path": "/send_code",
          "full_url_example": "https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run/send_code",
          "auth": "none",
          "content_type": "application/json"
        },
        {
          "operation_id": "login",
          "method": "POST",
          "path": "/login",
          "full_url_example": "https://aichattst-login-zgtmdzmukf.cn-hangzhou.fcapp.run/login",
          "auth": "none",
          "content_type": "application/json"
        }
      ]
    },
    "ChatService": {
      "base_url": "https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run",
      "endpoints": [
        {
          "operation_id": "chat_roles",
          "method": "GET",
          "path": "/chat/roles",
          "full_url_example": "https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run/chat/roles",
          "auth": "none",
          "response_type": "json"
        },
        {
          "operation_id": "chat_stream",
          "method": "POST",
          "path": "/chat/stream",
          "full_url_example": "https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run/chat/stream",
          "auth": "bearer_jwt",
          "content_type": "application/json",
          "response_type": "sse",
          "done_marker": "[DONE]"
        },
        {
          "operation_id": "chat_history",
          "method": "GET",
          "path": "/chat/history",
          "full_url_example": "https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run/chat/history?role_code=naitang",
          "auth": "bearer_jwt",
          "response_type": "json"
        },
        {
          "operation_id": "chat_clear",
          "method": "POST",
          "path": "/chat/clear",
          "full_url_example": "https://aichattest-chat-otqjepryyc.cn-hangzhou.fcapp.run/chat/clear",
          "auth": "bearer_jwt",
          "content_type": "application/json",
          "response_type": "json"
        }
      ]
    }
  }
}

10. Notes

本文档只描述当前已经实现的接口，不包含未来规划接口。
GET /chat/roles 不需要 JWT；其余聊天业务接口都需要 JWT。
普通 JSON 返回为 UTF-8 可读中文。
流式聊天 SSE chunk 为上游透传 JSON 或本地兜底 JSON，客户端应按 JSON 解析。
prompt 是兼容字段，建议新客户端统一使用 message。