API接入

一、概述

本接口描述了AI工作流执行API接口，该接口支持流式响应，可以实时获取AI工作流的执行结果。接口支持两种工作流类型：智能体和工作流。

二、接口信息

接口地址：POST/v1/openapi/execute

请求方式：POST

内容类型：application/json响应类型：text/event- stream（服务器发送事件）

三、请求参数

3.1 请求头 (Headers)

参数名类型必填说明
Content-Typestring是固定值：application/json
Authorizationstring是格式：Bearer ApiKey

3.2 请求体 (Body)

参数名类型必填说明
sessionIdstring是会话 ID，用于标识用户每次会话，清除会话则新生成一个会话 ID，会话 ID 要保证唯一，长度 1-100 字符
flowCodestring是工作流或智能体 Code，指定要执行的工作流
flowDetailTypeinteger是工作流类型：1（智能体），2（工作流）
textInputstring否文本输入内容，最大长度 8000 字符
imageInputarray否图片输入，仅支持 URL
fileInputarray否文件输入，仅支持 URL
argsobject否自定义变量参数，键值对形式

3.3 请求示例

{
    "sessionId": "session_123456",
    "fluId": "flow_789012",
    "flowDetailType": 1,
    "textInput": "请帮我分析一下当前的市场趋势",
    "imageInput": "https://example.com/image1.jpg",
    "fileInput": "https://example.com/document.pdf",
    "args": {
        "username": "测试",
        "sex": 1,
        "model": "gpt-4"
    }
}

四、响应说明

4.1 响应头

参数名值说明
Content-Typetext/event-stream; charset=utf-8流式响应内容类型
Cache-Controlno-cache禁用缓存
Connectionkeep-alive保持连接

4.2 响应格式

接口采用服务器发送事件（SSE）进行流式响应，每个事件的格式为：

data: {JSON 数据}

4.3 事件类型

4.3.1 流式输出事件

用于智能体类型的实时输出

{
    "Type": "streaming",
    "Output": "这是AI生成的部分响应内容",
    "IsEnd": false
}
字段类型说明
Typestring事件类型，固定值"streaming"
Outputstring输出的文本内容
IsEndboolean是否为最后一个片段

4.3.2 节点完成事件

用于工作流类型的节点执行结果

{
    "nodeId": "node_001",
    "status": "completed",
    "output": "节点执行结果",
    "tokens": 150,
    "executionTime": 1230
}

4.3.3 错误事件

{
    "Type": "error",
    "Output": "执行过程中发生的错误信息"
}

4.3.4 结束事件

{
    "Type": "end"
}

4.4 完整响应示例

4.4.1 智能体响应示例

data: {"Type":"streaming","Output":"<think>","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"帮助","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"用户","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"快速","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"选择","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"方向","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"。","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"</think>","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"你好","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"!","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"选择","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"方向","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"streaming","Output":"","IsEnd":false,"IsInParagraph":false,"ParagraphEvent":null}
data: {"Type":"end"}

有分段

data: {"Type":"streaming","Output":"","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"start"}
data: {"Type":"streaming","Output":"这是","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"第一","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"段落","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"的内容","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"end"}
data: {"Type":"streaming","Output":"","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"start"}
data: {"Type":"streaming","Output":"这是","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"第二","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"段落","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"content"}
data: {"Type":"streaming","Output":"","IsEnd":false,"IsInParagraph":true,"ParagraphEvent":"end"}
data: {"Type":"end"}
字段类型说明
Typestring事件类型，固定值"streaming"，类型为end时表示结束
Outputstring输出的文本内容
IsEndboolean智能体响应时 IsEnd 无用

4.4.2 工作流响应示例

data: {"NodeId":"node-start-1754989115758","NodeType":"StartNode","CurrentType":1,"Output":null,"Type":"streaming","IsEnd":false}
data: {"NodeId":"node-1754989254214","NodeType":"CustomerServiceNode","CurrentType":2,"Output":"你好xxxx","Type":"streaming","IsEnd":true}
data: {"Type":"end"}
字段类型说明
Typestring事件类型，固定值"streaming"，类型为end时表示输出结束
Outputstring输出的文本内容
IsEndboolean工作流响应时IsEnd表示流程是否结束
NodeIdstring节点id
NodeTypestring节点类型

节点类型说明：

  • start：开始节点
  • largeModel：大模型节点
  • knowledge：知识库节点
  • intentBranch：意图分支节点
  • logicBranch：逻辑分支节点
  • application：应用节点
  • end：结束节点
  • plugin：插件节点
  • humanTransfer：转人工节点
  • fixedContent：固定内容节点
  • code：代码节点
  • database：数据库节点
字段类型说明
CurrentTypeint会话类型：1 正常，2 转人工后不回复，3 转人工后继续回复，4 转人工后延迟回复

五、错误码说明

HTTP 状态码错误码说明解决方案
400BAD_REQUEST请求参数错误检查请求参数格式和必填字段
401UNAUTHORIZED未授权访问检查 Authorization 头部的 ApiKey 是否有效
403FORBIDDEN禁止访问检查用户权限
404NOT_FOUND工作流不存在检查 flowCode 是否正确
500INTERNAL_ERR OR服务器内部错误联系技术支持

5.1 错误响应格式

{
  "code": "400",
  "message": "请求参数无效",
  "details": "flowCode 参数不能为空",
  "traceId": "trace_123456789"
}

六、客户端实现示例

6.1 cURL 示例

curl -X POST "https://api.example.com/v1/openapi/execute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "sessionId": "session_123456",
    "flowCode": "flow_789012",
    "flowDetailType": 1,
    "textInput": "请帮我分析一下市场趋势",
    "args": {
        "username": "测试",
        "sex": 1,
        "model": "gpt-4"
    }
}' \
  --no-buffer

6.2 JavaScript 示例

async function executeWorkflow(sessionId, flowId, textInput) {
    const response = await fetch('/v1/openapi/execute', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        },
        body: JSON.stringify({
            sessionId: sessionId,
            flowId: flowId,
            flowDetailType: 1,
            textInput: textInput,
            args: {
                temperature: 0.7,
                maxTokens: 2000
            }
        })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const {done, value} = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
            if (line.startsWith('data:')) {
                const data = JSON.parse(line.slice(6));
                switch(data.Type) {
                    case 'streaming':
                        console.log('流式输出：', data.Output);
                        break;
                    case 'error':
                        console.error('错误：', data.Output);
                        break;
                    case 'end':
                        console.log('执行完成');
                        return;
                }
            }
        }
    }
}

// 调用示例
executeWorkflow('session_123', 'flow_456', '分析市场趋势');

6.3 Python 示例

import requests
import json

def execute_workflow_stream(session_id, flow_id, text_input, args=None):
    """
    执行工作流并处理流式响应
    """
    url = "https://api.example.com/v1/openapi/execute"
    payload = {
        "sessionId": session_id,
        "flowId": flow_id,
        "flowDetailType": 1,
        "textInput": text_input,
        "args": args or {"temperature": 0.7, "maxTokens": 2000}
    }
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }

    try:
        response = requests.post(url, json=payload, headers=headers, stream=True)
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if line.startswith('data:'):
                try:
                    data = json.loads(line[6:])
                    if data.get("Type") == "streaming":
                        print(f"输出: {data.get('Output', '')}")
                        if data.get("IsEnd"):
                            print("流式输出完成")
                    elif data.get("Type") == "error":
                        print(f"错误: {data.get('Output', '')}")
                    elif data.get("Type") == "end":
                        print("执行结束")
                        break
                except json.JSONDecodeError:
                    continue

    except requests.exceptions.RequestException as e:
        print(f"请求失败: {e}")

# 使用示例
execute_workflow_stream(
    session_id="session_123456",
    flow_id="flow_789012",
    text_input="请帮我分析一下市场趋势"
)

6.4 Java 示例

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

public class WorkflowClient {
    private static final String API_URL = "https://api.example.com/v1/openapi/execute";
    private static final String ACCESS_TOKEN = "YOUR_ACCESS_TOKEN";

    public void executeWorkflow(String sessionId, String flowId, String textInput) {
        try {
            URL url = new URL(API_URL);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            // 设置请求头
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Bearer " + ACCESS_TOKEN);
            conn.setDoOutput(true);

            // 构建请求体
            ObjectMapper mapper = new ObjectMapper();
            String requestBody = mapper.writeValueAsString(Map.of(
                "sessionId", sessionId,
                "flowId", flowId,
                "flowDetailType", 1,
                "textInput", textInput,
                "args", Map.of("temperature", 0.7, "maxTokens", 2000)
            ));

            // 发送请求
            conn.getOutputStream().write(requestBody.getBytes());

            // 读取流式响应
            BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream())
            );

            String line;
            while ((line = reader.readLine()) != null) {
                if (line.startsWith("data:")) {
                    String jsonData = line.substring(6);
                    // 解析JSON并处理响应
                    handleStreamData(jsonData);
                }
            }

            reader.close();
            conn.disconnect();

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private void handleStreamData(String jsonData) {
        // 处理流式数据的逻辑
        System.out.println("接收到数据：" + jsonData);
    }
}

七、技术支持

如有技术问题，请联系：

  1. 邮箱：support@example.com1. 技术文档：https://docs.example.com1. 问题反馈：https://github.com/example/issues

文档版本：v1.0最后更新：2025年8月适用版本：APIv1.0

最近更新:
Contributors: zl0905