AI 应用开发平台

Appearance

文本生成 ​

文本生成（TextCompletion）应用的单次生成接口。每次调用独立执行一次，无对话上下文、无会话管理、无工具调用，仅接收 input 变量并按应用配置的提示词模板渲染后由 LLM 生成结果。

支持 SSE 流式响应和阻塞式响应两种模式。

  • 接口路径：POST /v1/openapi/chat/send-messages

INFO

此接口与 Agent / AgentLite 类型应用共用同一接口路径，由 app_id 对应应用的类型分发到不同执行链路。

TextCompletion 能力范围 ​

文本生成是单次输入、单次输出的应用类型，相比 Agent / AgentLite 缺失大量能力：

能力AgentAgentLiteTextCompletion
多轮对话（conversation_id）✓✓—
会话管理（会话列表 / 历史记录）✓✓—
提示词编排与变量输入（input）✓✓✓
模型选择✓✓✓
知识库增强✓✓—
工具调用（插件 / 三方服务 / 内置工具 / MCP / 工作流）✓✓—
人工介入（HITL）✓✓—
沙盒执行与文件操作✓——
Skill / Sub-agent✓——

因此本接口在 TextCompletion 场景下：

  • 不接受 query 参数：服务端会强制清空 query，输入唯一来自渲染后的提示词模板（由应用配置的提示词与 input 变量拼接生成）
  • 忽略 conversation_id：无对话上下文，每次调用独立执行
  • 不支持 action: "resume" / action: "reconnect"：无 HITL、无持久会话，不会触发 interrupt 事件，也无需恢复或重连
  • 不会推送以下事件：tool.start / tool.result / tool.call / tool.error、interrupt、sandbox.*、sub_agent.*

请求头 ​

参数名必填说明
Content-Type是application/json
Authorization是鉴权凭证，格式 Bearer sk_xxx

请求参数 ​

json
{
    "app_id": "",            // 必填-应用ID（必须为 TextCompletion 类型应用）
    "user_id": "",           // 必填-用户标识（用于记录归属与流量统计）
    "username": "",          // 用户名称（可选，用于记录展示）
    "input": {               // 必填-变量参数，key 使用 variable_name，value 须符合变量 schema
        "title": "Q1 销售周报",
        "tone": "正式"
    },
    "files": [               // 用户上传的多模态附件（可选），目前仅支持 image 类型，URL 须为公网可直接访问的完整地址
        {"type": "image", "url": "https://example.com/a.png"}
    ],
    "response_mode": "",     // 响应模式：streaming-流式（默认）、blocking-阻塞式
    "select_model_id": ""    // 自由模式（loose_status）下指定的模型ID，非自由模式忽略
}
参数名类型必填说明
app_idstring(uuid)是应用 ID，须为 TextCompletion 类型
user_idstring是业务方用户标识
usernamestring否用户名称，用于记录展示
inputobject是变量参数，key 使用提示词变量的 variable_name，value 须符合对应 schema
filesarray否多模态附件列表，每项含 type 与 url（公网可访问完整 URL）。type 目前仅支持 image，非法类型或空 URL 会被过滤
response_modestring否streaming（默认）/ blocking
select_model_idstring(uuid)否自由模式下指定模型 ID，非自由模式忽略

变量输入

可通过应用详情获取已发布变量定义。input 不提交显示名称、控件或默认值状态；必填、默认值与加密掩码的处理规则见变量协议。

WARNING

TextCompletion 应用不接受 query、conversation_id 字段，传入也会被服务端忽略；输入唯一来自 input 变量，根据应用配置的变量定义提供必填字段。同时不支持 with_tts 语音播报。

阻塞模式响应（blocking） ​

当 response_mode=blocking 时，等待文本生成完成后一次性返回 JSON 结果。

成功响应 ​

json
{
    "code": 200,
    "message": "success",
    "data": {
        "conversation_id": "",
        "message_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
        "task_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
        "status": "completed",
        "duration": 1500,
        "output": {
            "content": "生成的文本内容",
            "finish_reason": "stop",
            "tokens": 0
        }
    }
}

失败响应 ​

json
{
    "code": 0,
    "message": "错误描述",
    "data": null,
    "trace_id": ""
}

流式模式响应（streaming） ​

当 response_mode=streaming（或未传）时，接口返回 SSE 事件流。

SSE 响应头 ​

text
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

事件流格式 ​

每条 SSE 事件由 event 和 data 两行组成：

text
event: {事件类型}
data: {JSON数据}

data 为 JSON 对象，所有事件均包含以下公共字段：

字段类型说明
eventstring事件类型名称
idstring(uuid)事件唯一ID
message_idstring(uuid)消息ID（与 task_id 关联）
task_idstring(uuid)任务ID，可用于停止生成
timestampint64事件时间戳（Unix秒）

INFO

TextCompletion 不维护会话，事件中的 conversation_id 字段为空字符串。

执行生命周期事件 ​

start — 执行开始 ​

收到此事件后，SSE 连接开始每 5 秒自动发送 ping 心跳事件，直到连接结束。

json
{
    "event": "start",
    "id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "conversation_id": "",
    "message_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "task_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "timestamp": 1777018922,
    "data": {
        "conversation_id": "",
        "app_id": ""
    }
}

completed — 执行完成 ​

json
{
    "event": "completed",
    "id": "...",
    "conversation_id": "",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "content": "生成的完整文本内容",
        "finish_reason": "stop"
    }
}

failed — 执行失败 ​

json
{
    "event": "failed",
    "id": "...",
    "conversation_id": "",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "error": "错误描述"
    }
}

cancelled — 执行取消 ​

通过停止响应接口主动取消时触发。

json
{
    "event": "cancelled",
    "id": "...",
    "conversation_id": "",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922
}

流式输出事件 ​

chunk — 文本分片 ​

逐字/逐句推送生成的文本内容。

json
{
    "event": "chunk",
    "id": "...",
    "conversation_id": "",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922,
    "data": {
        "content": "生"
    }
}

thinking — 深度思考消息 ​

仅当应用配置的 LLM 启用了思考能力（enable_thinking）时推送。

json
{
    "event": "thinking",
    "data": {
        "content": "让我先分析一下输入要点..."
    }
}

thinking_start / thinking_end — 深度思考开始/结束 ​

json
{
    "event": "thinking_start",
    "id": "...",
    "conversation_id": "",
    "message_id": "...",
    "task_id": "...",
    "timestamp": 1777018922
}

message — 完整消息 ​

json
{
    "event": "message",
    "data": {
        "content": "生成的完整文本内容"
    }
}

Token 统计事件 ​

token.usage — Token 用量 ​

json
{
    "event": "token.usage",
    "data": {
        "usage": {
            "prompt_tokens": 0,
            "completion_tokens": 0,
            "total_tokens": 0,
            "first_token_duration": 0,
            "duration": 0
        }
    }
}

心跳事件 ​

ping — 心跳保活 ​

收到 start 事件后，服务端每 5 秒自动发送一次 ping 事件，直到 SSE 连接结束。

text
event: ping
data: {"timestamp":1777018922}

典型事件流示例 ​

text
event: start
data: {"event":"start","id":"...","conversation_id":"","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"conversation_id":"","app_id":""}}

event: ping
data: {"timestamp":1777018922}

event: chunk
data: {"event":"chunk","id":"...","conversation_id":"","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"生"}}

event: chunk
data: {"event":"chunk","id":"...","conversation_id":"","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"成"}}

event: token.usage
data: {"event":"token.usage","id":"...","conversation_id":"","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"usage":{"prompt_tokens":48,"completion_tokens":120,"total_tokens":168,"first_token_duration":300,"duration":1500}}}

event: completed
data: {"event":"completed","id":"...","conversation_id":"","message_id":"...","task_id":"...","timestamp":1777018922,"data":{"content":"生成的完整文本内容","finish_reason":"stop"}}

AI 应用开发平台 - 面向医疗场景的 AI 应用创新引擎

Copyright © 2023-2026 成都华西数字医疗科技有限公司 All rights reserved.