跳到主要内容

OpenAI Responses API

SkillFlaw 在 POST /api/v1/responses 提供了一个与 OpenAI Responses API 兼容的端点。

这意味着你可以在尽量少改动的前提下，复用 OpenAI 客户端库来调用 SkillFlaw：

  • 把 OpenAI 客户端的 base_url / baseURL 指向 SkillFlaw 的 /api/v1/
  • 通过 x-api-key 传递 SkillFlaw API Key
  • 把 OpenAI 的 model 值替换成 SkillFlaw 的流程 ID或已发布端点名

前置条件​

要通过 /api/v1/responses 运行流程，当前后端至少要求：

  • 流程中存在 Chat Input 节点
  • 流程中存在 Chat Output 节点
  • 请求中带有有效的 x-api-key
  • model 必须是合法的 flow UUID 或已发布端点名
  • tools 必须省略或设为 null；若传入非空值，请求会返回 tools_not_supported 风格错误

为 OpenAI 客户端做额外配置​

OpenAI SDK 自身要求提供一个 api_key 参数，即使 SkillFlaw 实际认证用的是 x-api-key。 因此在客户端代码里，应：

  • 给 SDK 传一个占位 api_key
  • 用默认请求头传递真实的 SkillFlaw API Key

_14
from openai import OpenAI
_14
_14
client = OpenAI(
_14
base_url="SKILLFLAW_URL/api/v1/",
_14
default_headers={"x-api-key": "SKILLFLAW_API_KEY"},
_14
api_key="dummy-api-key"
_14
)
_14
_14
response = client.responses.create(
_14
model="FLOW_ID",
_14
input="There is an event that happens on the second Wednesday of every month. What are the event dates in 2026?",
_14
)
_14
_14
print(response.output_text)

请求示例​


_10
curl -X POST \
_10
"$SKILLFLAW_URL/api/v1/responses" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY" \
_10
-H "Content-Type: application/json" \
_10
-d '{
_10
"model": "$FLOW_ID",
_10
"input": "Hello, how are you?",
_10
"stream": false
_10
}'

请求头​

Header必填说明示例
x-api-key是SkillFlaw API Keysk-...
Content-Type是JSON 格式application/json
X-SKILLFLAW-GLOBAL-VAR-*否请求级全局变量X-SKILLFLAW-GLOBAL-VAR-TRACE-ID: trace-123

请求体字段​

字段类型必填默认值说明
modelstring是-要执行的流程 ID 或已发布端点名
inputstring是-要处理的输入文本
streamboolean否false是否流式返回
backgroundboolean否false为兼容保留；请求仍以内联方式执行
toolslist[Any]否null必须省略或为 null
previous_response_idstring否null会话连续性 ID；参阅继续会话
includelist[string]否null额外返回内容，例如 tool_call.results

响应示例​


_23
{
_23
"id": "e5e8ef8a-7efd-4090-a110-6aca082bceb7",
_23
"object": "response",
_23
"created_at": 1756837941,
_23
"status": "completed",
_23
"model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
_23
"output": [
_23
{
_23
"type": "message",
_23
"id": "msg_e5e8ef8a-7efd-4090-a110-6aca082bceb7",
_23
"status": "completed",
_23
"role": "assistant",
_23
"content": [
_23
{
_23
"type": "output_text",
_23
"text": "Hello! I'm here and ready to help. How can I assist you today?",
_23
"annotations": []
_23
}
_23
]
_23
}
_23
],
_23
"previous_response_id": null
_23
}

一个重要细节是：响应里的 id 也会被当作会话标识使用。 如果没有传 previous_response_id，SkillFlaw 会自动生成一个新的 UUID，并将它作为响应 id 返回。

流式请求示例​

当你把 stream 设为 true 时，SkillFlaw 会返回 SSE 流。 最终会以 data: [DONE] 收尾。


_10
curl -X POST \
_10
"$SKILLFLAW_URL/api/v1/responses" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY" \
_10
-H "Content-Type: application/json" \
_10
-d '{
_10
"model": "$FLOW_ID",
_10
"input": "Tell me a story about a robot",
_10
"stream": true
_10
}'

继续会话：response ID 与 session ID​

SkillFlaw 使用 previous_response_id 作为对话连续性的会话 ID。

  • 如果省略它，SkillFlaw 会新建一个 UUID 并将其作为 id 返回
  • 如果提供它，SkillFlaw 会复用该字符串作为本次运行的 session ID
  • 因此，你可以直接复用上一条响应返回的 id，也可以传入你自己的稳定会话键

获取工具调用结果​

如果流程中产生了 tool call，你可以在请求中加入：


_10
"include": ["tool_call.results"]

这样响应中就会额外带回每个工具调用的原始结果，而不只是函数调用元数据。

通过请求头向流程传递全局变量​

你可以通过形如 X-SKILLFLAW-GLOBAL-VAR-{VARIABLE_NAME} 的请求头，把请求级变量注入流程运行时上下文。

例如：


_11
curl -X POST \
_11
"$SKILLFLAW_URL/api/v1/responses" \
_11
-H "x-api-key: $SKILLFLAW_API_KEY" \
_11
-H "Content-Type: application/json" \
_11
-H "X-SKILLFLAW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \
_11
-H "X-SKILLFLAW-GLOBAL-VAR-USER_ID: user123" \
_11
-H "X-SKILLFLAW-GLOBAL-VAR-TRACE-ID: trace-123" \
_11
-d '{
_11
"model": "your-flow-id",
_11
"input": "Hello"
_11
}'

这些变量只在当前请求有效，不会被持久化到数据库中。

如果流程引用了某个变量，而它既不在请求头里、也不在数据库里，则默认会执行失败。