# 星火智能体Workflow Open API文档

# 1. 服务说明

本协议用于描述如何调用讯飞开放平台 Workflow OpenAPI，您需要先在星火智能体创作中心 (opens new window)完成工作流的创建，调试通过并发布后，即可调用此服务。

# 2. 接口说明

# 2.1 请求方法和URl

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

# 2.2 接口Demo

接口Demo随后提供。

# 2.3 接口要求

接口类型: 流式http(s)

接口鉴权: Bearer鉴权

# 2.4 接口权限说明

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

# 3. 请求

# 3.1 请求协议示例

{
    "flow_id": "7265177322515169282",
    "uid": "123",
    "parameters": {
        "AGENT_USER_INPUT": "你好"
    },
    "stream": true
}

# 3.2 请求参数

# 3.2.1 Header

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

# 3.2.2 Body

参数名称	参数类型	是否必须	说明
flow_id	string	是	工作流id
uid	string	否	用户id
stream	bool	是	是否启用流式返回流式：true 非流式：false
parameters	object	是	工作流开始节点的输入参数及取值，你可以在指定工作流的编排页面查看参数列表 {"input1": "xxxxx", "input2": "xxxxx"}

# 4. 响应

# 4.1 响应协议示例

# 4.1.1 流式结果示例

流式输出过程帧

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "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": ""
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 9
  }
}

# 4.1.2 非流式结果示例

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

# 4.1.3 异常结果

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

# 4.2 响应参数

# 4.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.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消耗

# 4.2.2 结果格式补充说明

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

markdown（表格、列表等）

# 5. 错误码列表

错误码	描述
0	成功
500	服务器异常
20101	三方协议参数异常
20201	未查到对应的Flow ID
20804	流式输出超时
22300	引擎构建失败
22301	引擎运行失败
22302	节点执行失败

在这篇文章中：