相关方案
      社区内容

        # API 接入

        调用 API 需经过以下几个流程：

        # 1. 准备工作

        需要将工作流智能体发布为 API 后，才能通过 API 调用。具体发布流程如下：

        # 1.1 工作流发布为 API

        工作流完成开发和调试后，点击工作流画布页面的右上角的发布按钮进行发布。

        在弹出的页面中，点击"发布为 API"栏右侧的"配置"按钮，即可跳转到发布为 API 的配置页面。

        # 1.2 实名认证

        工作流发布为 API 前需要进行实名认证。如果您之前没有做过实名认证，则可以找到页面中"完成实名认证"栏中的"去认证"，点击即可跳转到用户认证中心页面，开发者可在此页面按照提示进行实名认证。如果您之前已成功实名认证，则可跳过此步骤。

        # 1.3 创建应用

        如果您之前没有创建过应用，或者期望把该工作流绑定到一个新的应用上，则需要通过此步骤创建一个新的应用。如果您已创建过应用且希望把该工作流绑定到已有的应用上，则可以跳过此步骤。

        步骤一：当您希望创建一个新应用时，找到"绑定应用"栏中"立即创建"按钮，点击后即可跳转到创建应用页面。

        步骤二：在创建页面中，填写应用的相关信息，点击"提交"按钮完成创建。

        # 1.4 绑定应用

        重新回到发布 API 的配置页面，找到"服务接口认证信息"选项卡，在该选项卡中完成工作流和应用的绑定。具体步骤如下：

        步骤一：点击"选择您的要绑定的应用"下拉框，此时会显示当前账号中所有的应用名称。从中选择您需要绑定的应用。

        注意事项：

        • 如果在下拉框中没有找到刚刚创建的应用名称，则需要刷新一下配置页面。
        • 应用一旦绑定后无法修改，请谨慎选择。

        步骤二：选择完应用后，点击"立即绑定"按钮，完成应用绑定。此时，会显示调用 API 所需要的接口信息，APIKey，API Secret 和 API Flowid。

        注意：如果您的工作流有了新的改动，在 API 调用前，请先点击"更新绑定"按钮重新发布为 API，新的改动才会在 API 调用中生效。

        # 1.5 获取大模型授权

        在使用 API 接口调用前，需要确保绑定的 APPID 拥有您工作流中所使用的大模型授权。开发者可在星火官网-星火 API 栏 (opens new window)领取一些免费的额度进行体验。

        当发布完工作流以及获取到相关大模型授权后，即可进行智能体 API 调用。

        # 2. 工作流 API 集成

        # 2.1 基本信息

        # 2.1.1 接口说明

        请求方式 POST
        请求地址 https://xingchen-api.xf-yun.com/workflow/v1/chat/completions (opens new window)

        # 2.1.2 接口 Demo

        Demo 类型 下载地址
        Java Demo https://oss-beijing-m8.openstorage.cn/aee-sdk/custom-made/java/workflow_openapi_demo_java.java.zip
        Python Demo https://oss-beijing-m8.openstorage.cn/aee-sdk/custom-made/python/workflow_openapi_demo_python.py.zip

        # 2.1.3 接口要求

        接口类型: 流式 http(s)

        接口鉴权: Bearer 鉴权

        # 2.1.4 接口权限说明

        鉴权不通过或 APPID 与当前工作流不匹配，会返回相关流控错误。

        # 2.2 发起会话请求

        # 2.2.1 请求协议示例

        {
    "flow_id": "7265177322515169282",
    "uid": "123",
    "parameters": {
        "AGENT_USER_INPUT": "你好"
    },
    "ext": {
        "bot_id": "workflow",
        "caller": "workflow"
    },
    "stream": true,
    "chat_id": "xxx",
    "history": [
      {
        "role": "user",
        "content_type": "text",
        "content": "你好"
      },
      {
        "role": "assistant",
        "content_type": "text",
        "content": "你好,我是你的工作助手，请问有什么可以帮您？"
      }
    ]
}

        # 2.2.2 请求参数

        2.2.2.1 Header

        参数名称 参数值 是否必填 说明
        Authorization Bearer $API_KEY 是 鉴权 key 鉴权码组成：Bearer {API_KEY}:{API_SECRET}

        2.2.2.2 Body

        参数名称 参数类型 是否必须 说明
        flow_id string 是 工作流 id
        uid string 否 用户 id
        stream bool 是 是否启用流式返回 流式：true 非流式：false
        ext object 否 用于指定一些额外字段，比如一些插件隐藏字段 暂时用不到
        parameters object 是 工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表 {"input1": "xxxxx", "input2": "xxxxx"}
        chat_id string 否 会话 id，用于区分不同的工作流会话，长度不超过 32 位
        history array of history_message object 否 历史对话信息[history_message object]集合 例如 [{"role": "user", "content_type": "text", "content": "你好" },{"role": "assistant", "content_type": "text", "content": "你好,我是你的工作助手，请问有什么可以帮您？" }]

        2.2.2.3 history_message Object

        参数名称 参数类型 是否必须 取值范围 默认值 说明
        role string 是 user, assistant 发送这条消息的实体 user: 代表该消息是用户发送的。 assistant: 代表该消息是工作流回复的。
        content_type string 否 text, image text 消息内容的类型，当前只支持两种类型。若不填写，则默认类型为 text text：表示普通文本。 image：表示图片类型。
        content string 是 消息内容，如果是 image 类型这里需要填写图片 url

        在处理 history_message object 时，首个元素的 role 必须为 user。交互历史应按照 user -> assistant -> user -> assistant 的顺序进行拼接，默认情况下，user 与 assistant 之间的一对交互视为一轮对话。按对话时间从先到后依次填充。如[{第一次},{第二次}...]

        [
  // 拼接对话历史信息:
  {"role": "user", "content_type" : "text", "content": "湖南有哪些美食"},              // 用户第一个问题   role是user,表示是用户的提问
  {"role": "assistant", "content_type" : "text", "content": "湖南有xxxxxx"},        // AI的第一个回复  role是assistant，表示是AI的回复
]

        # 2.3 响应

        # 2.3.1 响应协议示例

        2.3.1.1 流式结果示例

        流式输出过程帧

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ]
}

        流式输出结束帧

        {
  "code": 0,
  "message": "Success",
  "id": "spf0016609f@dx193193f43cba44d782",
  "created": 123412324431,
  "workflow_step": {
    "seq": 6,
    "progress": 1
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 9
  }
}

        2.3.1.2 非流式结果示例

        {
  "code": 0,
  "message": "Success",
  "id": "cha000b0003@dx1905cd86d6bb86d552",
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方，请随时告诉我！我会尽力为你提供解答和支持。请问有什么可以帮到你的吗？",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop",
      "finish_reason": ""
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 42,
    "total_tokens": 48
  }
}

        2.3.1.3 中断事件

        当工作流中有问答节点时，工作流会被中断

        问答节点中断帧（直接回答）

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": true,
        "value": {
            "type": "direct",
            "content": "你想购买以下哪个套餐？"
        }
    }
}

        问答节点中断帧（选项回答）

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": false,
        "value": {
            "type": "option",
            "content": "请选择你的套餐",
            "option": [
                {
                    "id": "A",
                    "text": "年度套餐"
                },
                {
                    "id": "B",
                    "text": "月度套餐"
                }
            ]
        }
    }
}

        2.3.1.4 异常结果

        {
    "code": 20805,
    "message": "flow id : 7265177322515169282 状态为草稿，请发布",
    "id": "spf00dc0001@hf193621572a96806782",
    "created": 1732517393,
    "choices": [
        {
            "delta": {
                "role": "assistant",
                "content": "",
                        "reasoning_content": ""
            },
            "finish_reason": "stop"
        }
    ],
    "workflow_step": {
        "seq": 0,
        "progress": 1.0
    },
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

        # 2.3.2 响应参数

        2.3.2.1 响应数据参数

        参数名称 类型 是否必须 参数说明
        code int 是 错误码，0 为成功，非 0 表示报错
        message string 是 错误信息描述
        id string 是 服务端会话 id
        created int 是 对话创建时间戳, 单位: s
        workflow_step object 是 工作流步骤
        workflow_step.seq int 是 返回的数据序号，取值为 [0,9999999]
        workflow_step.progress float 是 工作流进度
        choices array 是
        choices.delta object 是
        choices.delta.role string 是 工作流的角色
        choices.delta.content string 是 工作流输出的内容
        choices.delta.reasoning_content string 是 工作流的思维链内容
        choices.index int 是 工作流的结果序号，在多候选中使用
        choices.finish_reason string 是 当工作流到达自然停止点或用户提供的停止序列时，它将将 finish_reason 设置为 “stop”
        usage object 否 token 计量，只在工作流结束帧才会给出
        usage.prompt_tokens int 是 工作流请求大模型的 token
        usage.completion_tokens int 是 工作流大模型回复
        usage.total_tokens int 是 工作流总的 token 消耗
        event_data object 否 事件数据
        event_data.event_id str 是 事件 id，用于 resume 接口恢复事件的标志
        event_data.event_type str 是 事件类型，中断时为"interrupt"
        event_data.need_reply bool 是 问答节点是否必须要求回答
        event_data.value object 是 中断数据详情
        event_data.value.type str 是 问题类型，枚举值 - direct: 直接回答 - option: 选项回答
        event_data.value.content str 是 用户提问内容
        event_data.value.option array 否 选项回答时的选项内容

        2.3.2.2 结果格式补充说明

        模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

        • markdown（表格、列表等）

        # 2.4 恢复运行工作流

        当您的工作流执行到问答节点时，工作流会被暂时中断，并返回相应的事件 ID 和工作流中设定的问题。此时开发者应调用此接口把用户的答复以及事件 ID 等信息进行上传，重新恢复工作流的运行。

        # 2.4.1 基础信息

        2.4.1.1 接口说明

        请求方式 POST
        请求地址 https://xingchen-api.xf-yun.com/workflow/v1/resume (opens new window)

        2.4.1.2 接口 Demo

        Demo 类型 下载地址
        Python Demo https://oss-beijing-m8.openstorage.cn/aee-sdk/custom-made/python/workflow_openapi_resume_demo_python.py.zip

        2.4.1.3 接口要求

        接口类型: 流式 http(s)

        # 2.4.2 请求

        2.4.2.1 请求协议示例

        {
    "event_id": "123456789012345",
    "event_type": "resume",
    "content": "我的姓名是:xxxx, 年龄：xxxx"
}

        2.4.2.2 请求参数

        1. Header
        参数名称 参数值 是否必填 说明
        Authorization Bearer $API_KEY 是 鉴权 key 鉴权码组成：Bearer {API_KEY}:{API_SECRET}
        1. Body
        参数名称 参数类型 是否必须 说明
        event_id string 是 事件 id，中断类事件发生时由 chat 和 resume 接口返回，用于标识同一工作流中一次请求产生的多个事件，值保持一致。
        event_type string 否 用于处理事件，默认走恢复。 resume: 恢复 ignore: 忽略 abort: 结束
        content string 是 回答内容, 如果是选项回答，只需传选项信息 A-Z

        # 2.4.3 响应

        2.4.3.1 响应协议示例

        1. 流式结果示例

        流式输出过程帧

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ]
}

        流式输出结束帧

        {
  "code": 0,
  "message": "Success",
  "id": "spf0016609f@dx193193f43cba44d782",
  "created": 123412324431,
  "workflow_step": {
    "seq": 6,
    "progress": 1
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 9
  }
}
        1. 非流式结果示例
        {
  "code": 0,
  "message": "Success",
  "id": "cha000b0003@dx1905cd86d6bb86d552",
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方，请随时告诉我！我会尽力为你提供解答和支持。请问有什么可以帮到你的吗？",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop",
      "finish_reason": ""
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 42,
    "total_tokens": 48
  }
}
        1. 中断事件

        当工作流中有问答节点时，工作流会被中断

        问答节点中断帧（直接回答）

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": true,
        "value": {
            "type": "direct",
            "content": "你想购买以下哪个套餐？"
        }
    }
}

        问答节点中断帧（选项回答）

        {
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": false,
        "value": {
            "type": "option",
            "content": "请选择你的套餐",
            "option": [
                {
                    "id": "A",
                    "text": "年度套餐"
                },
                {
                    "id": "B",
                    "text": "月度套餐"
                }
            ]
        }
    }
}
        1. 异常结果
        {
    "code": 20805,
    "message": "flow id : 7265177322515169282 状态为草稿，请发布",
    "id": "spf00dc0001@hf193621572a96806782",
    "created": 1732517393,
    "choices": [
        {
            "delta": {
                "role": "assistant",
                "content": "",
                        "reasoning_content": ""
            },
            "finish_reason": "stop"
        }
    ],
    "workflow_step": {
        "seq": 0,
        "progress": 1.0
    },
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

        2.4.3.2 响应参数说明

        1. 响应数据参数
        参数名称 类型 是否必须 参数说明
        code int 是 错误码，0 为成功，非 0 表示报错
        message string 是 错误信息描述
        id string 是 服务端会话 id
        created int 是 对话创建时间戳, 单位: s
        workflow_step object 是 工作流步骤
        workflow_step.seq int 是 返回的数据序号，取值为 [0,9999999]
        workflow_step.progress float 是 工作流进度
        choices array 是
        choices.delta object 是
        choices.delta.role string 是 工作流的角色
        choices.delta.content string 是 工作流输出的内容
        choices.delta.reasoning_content string 是 工作流的思维链内容
        choices.index int 是 工作流的结果序号，在多候选中使用
        choices.finish_reason string 是 当工作流到达自然停止点或用户提供的停止序列时，它将将 finish_reason 设置为 “stop”
        usage object 否 token 计量，只在工作流结束帧才会给出
        usage.prompt_tokens int 是 工作流请求大模型的 token
        usage.completion_tokens int 是 工作流大模型回复
        usage.total_tokens int 是 工作流总的 token 消耗
        event_data object 否 事件数据
        event_data.event_id str 是 事件 id，用于 resume 接口恢复事件的标志
        event_data.event_type str 是 事件类型，中断时为"interrupt"
        event_data.need_reply bool 是 问答节点是否必须要求回答
        event_data.value object 是 中断数据详情
        event_data.value.type str 是 问题类型，枚举值 - direct: 直接回答 - option: 选项回答
        event_data.value.content str 是 用户提问内容
        event_data.value.option array 否 选项回答时的选项内容
        1. 结果格式补充说明

        模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

        • markdown（表格、列表等）

        # 2.5 文件上传

        # 2.5.1 基础信息

        2.5.1.1 接口说明

        请求方式 POST
        请求地址 https://xingchen-api.xf-yun.com/workflow/v1/upload_file (opens new window)

        2.5.1.2 接口 Demo

        curl -X POST 'https://xingchen-api.xf-yun.com/workflow/v1/upload_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif]

        2.5.1.3 接口要求

        接口类型: 流式 http(s)

        接口鉴权: Bearer 鉴权

        # 2.5.2 请求参数

        2.5.2.1 Header

        参数名称 类型 是否必须 参数说明
        Authorization string 是 鉴权 key。鉴权 key 鉴权码组成：Bearer {API_KEY}:{API_SECRET}
        Content-Type string 是 multipart/form-data

        2.5.2.2 Body

        参数名称 类型 是否必须 参数说明
        file file 是 要上传的文件

        # 2.5.3 响应

        2.5.3.1 响应协议示例

        {
  "code": 0,
  "message": "success",
  "sid": "spf001b23c7@dx1939b17d9e3a4f3700",
  "data": {
      "url": "xxxxxxxxxx"
  }
}

        2.5.3.2 响应参数说明

        参数名称 类型 参数说明
        code integer 错误码
        message string 错误描述
        sid string 会话 id
        data object 错误码
        data.url string 文件的访问外链

        # 3. 错误码列表

        # 3.1 工作流错误

        错误码 描述
        20201 未查找到对应 Flow ID
        20202 Flow ID 非法
        20204 工作流未发布
        20207 工作流为草稿状态

        # 3.2 模型错误

        错误码 描述
        20303 模型请求失败
        20350 升级为 ws 出现错误
        20351 通过 ws 读取用户的消息出错
        20352 通过 ws 向用户发送消息出错
        20353 用户的消息格式有错误
        20354 用户数据的 schema 错误
        20355 用户参数值有错误
        20356 用户并发错误：当前用户已连接，同一用户不能多处同时连接。
        20357 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题）")
        20358 服务容量不足，联系工作人员
        20359 和引擎建立连接失败
        20360 接收引擎数据的错误
        20361 发送数据给引擎的错误
        20362 引擎内部错误
        20363 输入内容审核不通过，涉嫌违规，请重新调整输入内容
        20364 输出内容涉及敏感信息，审核不通过，后续结果无法展示给用户
        20365 appid 在黑名单中
        20366 appid 授权类的错误。比如：未开通此功能，未开通对应版本，token 不足，并发超过授权 等等
        20367 清除历史失败
        20368 表示本次会话内容有涉及违规信息的倾向；建议开发者收到此错误码后给用户一个输入涉及违规的提示
        20369 服务忙，请稍后再试
        20370 请求引擎的参数异常 引擎的 schema 检查不通过
        20371 引擎网络异常
        20372 token 数量超过上限。对话历史+问题的字数太多，需要精简输入
        20373 授权错误：该 appId 没有相关功能的授权 或者 业务量超过限制
        20374 授权错误：日流控超限。超过当日最大访问量的限制
        20375 授权错误：秒级流控超限。秒级并发超过授权路数限制
        20376 授权错误：并发流控超限。并发路数超过授权路数限制
        20380 外部大模型请求失败

        # 3.3 API 授权

        错误码 描述
        20900 鉴权失败：授权限制，服务未授权或授权已到期
        20901 计量鉴权失败：服务超限，业务会话总量超限或日流控超限
        20902 鉴权失败：服务超限，QPS 秒级流控超限
        20903 并发鉴权失败：服务超限，并发路数超限

        # 3.4 文生图

        错误码 描述
        21200 图片生成失败
        21201 图片存储失败
        21203 用户的消息格式有错误
        21204 用户数据的 schema 错误
        21205 用户参数值有错误
        21206 服务容量不足
        21207 输入审核不通过
        21208 模型生产的图片涉及敏感信息，审核不通过
        21209 文生图超时

        # 3.5 工具错误

        错误码 描述
        21800 工具请求失败
        21801 工具初始化失败
        21802 工具 json 协议解析失败
        21803 工具协议校验失败
        21804 工具 openapi 协议解析失败
        21805 工具 body 类型不支持
        21806 工具 server 不存在
        21807 官方工具请求失败
        21808 工具不存在
        21809 工具 Operation 不存在
        21810 工具请求失败，连接异常
        21811 三方工具执行失败
        21812 三方工具请求失败

        # 3.6 节点执行错误

        错误码 描述
        20500 知识库请求异常
        20501 知识库节点执行异常
        20502 知识库参数异常
        22500 开始节点协议有误
        22600 结束节点协议有误
        22601 结束节点执行失败
        22701 消息节点执行失败
        21900 参数提取失败
        21600 代码执行失败
        21601 代码解释器节点构建失败
        21602 代码节点返回结果类型不符合要求
        21603 代码执行超时
        22801 工作流节点执行失败
        22802 工作流节点执行相应结果格式错误
        22900 变量节点执行失败
        23100 分支节点执行失败
        23200 迭代节点执行失败
        23300 大模型节点执行失败
        23400 工具节点执行失败
        23500 文本拼接节点执行失败
        23700 Agent 节点执行失败
        23800 问答节点执行失败

        # 3.7 会话

        错误码 描述
        20804 OpenAPI 输出超时
        23900 该对话已超时或不存在
        在这篇文章中：
        在线咨询
        体验中心