跳到主要内容

开始使用 SkillFlaw API

你可以通过 SkillFlaw API 以编程方式与 SkillFlaw 交互，例如：

  • 创建和编辑流程
  • 在应用中调用你的流程
  • 开发自定义组件
  • 将 SkillFlaw 作为更大系统中的运行时能力接入
  • 为 SkillFlaw 仓库本身做开发与贡献

如需查看和测试所有可用端点，请打开你部署实例的 OpenAPI 说明页 /docs，例如 http://localhost:7860/docs。

试试看

如果你想先看一个可运行脚本示例，请参阅快速开始。

组织 SkillFlaw API 请求​

虽然不同端点的参数各不相同，但 SkillFlaw API 请求通常都由以下部分组成：

  • 基础 URL
  • HTTP 方法
  • 路径参数 / 查询参数 / 请求体
  • 认证头
  • 对资源管理类端点而言，常常还需要显式 scope 头

例如，下面这个请求调用 /v1/run 并向流程中的 Chat Output 组件传入运行时覆盖值：


_14
curl --request POST \
_14
--url "$SKILLFLAW_URL/api/v1/run/$FLOW_ID?stream=false" \
_14
--header "Content-Type: application/json" \
_14
--header "x-api-key: $SKILLFLAW_API_KEY" \
_14
--data '{
_14
"input_value": "hello world!",
_14
"output_type": "chat",
_14
"input_type": "chat",
_14
"tweaks": {
_14
"ChatOutput-6zcZt": {
_14
"should_store_message": true
_14
}
_14
}
_14
}'

基础 URL​

本地部署默认会把 SkillFlaw API 暴露在：


_10
http://localhost:7860/api

远程部署则取决于你的域名与反向代理，例如：

  • https://UUID.ngrok.app/api
  • http://IP_OR_DNS/api
  • http://IP_OR_DNS:PORT/api

认证​

大多数 /api/v1 端点都要求以下任一认证方式：

  • 活跃用户会话
  • SkillFlaw API Key

更多信息请参阅 API Key 与认证。

很多资源管理端点还要求显式 scope 头。 例如，项目类端点至少要求 tenant-id，有时还会同时使用 business-id 和 is-self。

方法、路径与参数​

SkillFlaw API 会用到不同的：

  • HTTP 方法
  • 路径参数
  • 查询参数
  • 请求体参数

例如：

  • 创建流程：POST /v1/flows
  • 运行流程：POST /v1/run/$FLOW_ID

API 版本​

当前 SkillFlaw 同时暴露 /v1 与 /v2 端点。

有些端点只存在于单个版本下，也有些能力在两个版本下都存在，但语义不完全相同。 如果请求结果异常，请先检查路径版本是否正确。

设置环境变量​

你可以把常用值存进环境变量，便于复用、轮换凭据以及安全地引用敏感信息。

例如：


_22
# 设置环境变量
_22
export SKILLFLAW_API_KEY="sk..."
_22
export SKILLFLAW_URL="https://localhost:7860"
_22
export FLOW_ID="359cd752-07ea-46f2-9d3b-a4407ef618da"
_22
export PROJECT_ID="1415de42-8f01-4f36-bf34-539f23e47466"
_22
export TENANT_ID="3c0f3b3d-4d37-4f35-9a4a-b0f2db7c9f10"
_22
_22
# 在 API 请求中复用这些变量
_22
curl --request POST \
_22
--url "$SKILLFLAW_URL/api/v1/run/$FLOW_ID?stream=false" \
_22
--header "Content-Type: application/json" \
_22
--header "x-api-key: $SKILLFLAW_API_KEY" \
_22
--data '{
_22
"input_value": "hello world!",
_22
"output_type": "chat",
_22
"input_type": "chat",
_22
"tweaks": {
_22
"ChatOutput-6zcZt": {
_22
"should_store_message": true
_22
}
_22
}
_22
}'

在 SkillFlaw API 请求中最常见的环境变量包括：

  • 服务 URL
  • API Key
  • Flow ID
  • Project ID
  • tenant-id / business-id

你可以从以下位置获取 Flow ID：

试几个 SkillFlaw API 请求​

健康检查​

返回数据库与聊天服务的健康状态：


_10
curl -X GET \
_10
"$SKILLFLAW_URL/health_check" \
_10
-H "accept: application/json"

结果

_10
{
_10
"status": "ok",
_10
"chat": "ok",
_10
"db": "ok"
_10
}

SkillFlaw 还提供 GET /health。 不过该端点可能在应用尚未完全初始化前就返回，因此 GET /health_check 更适合作为 readiness 检查。

获取版本​

返回当前 SkillFlaw API 版本：


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/version" \
_10
-H "accept: application/json"

结果

_10
{
_10
"version": "1.6.0",
_10
"main_version": "1.6.0",
_10
"package": "SkillFlaw"
_10
}

获取配置​

返回当前 SkillFlaw 部署配置。需要认证。


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/config" \
_10
-H "accept: application/json" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY"

结果

_20
{
_20
"feature_flags": {
_20
"mvp_components": false
_20
},
_20
"serialization_max_items_length": 1000,
_20
"serialization_max_text_length": 6000,
_20
"frontend_timeout": 0,
_20
"auto_saving": true,
_20
"auto_saving_interval": 1000,
_20
"health_check_max_retries": 5,
_20
"max_file_size_upload": 1024,
_20
"webhook_polling_interval": 5000,
_20
"public_flow_cleanup_interval": 3600,
_20
"public_flow_expiration": 86400,
_20
"event_delivery": "streaming",
_20
"webhook_auth_enable": false,
_20
"voice_mode_available": false,
_20
"default_folder_name": "Starter Project",
_20
"hide_getting_started_progress": false
_20
}

获取全部组件​

返回已注册组件的字典。需要认证。


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/all" \
_10
-H "accept: application/json" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY"

可用端点概览​

由于 SkillFlaw 同时支持“可视化编辑器应用”与“偏运行时后端”两类部署形态，因此 API 同时包含：

  • 面向应用集成的运行接口
  • 面向前端编辑器的内部编排接口
  • 面向项目、资源、调试、日志和 Playground 的辅助接口

除非你是在为 SkillFlaw 仓库本身做开发，否则通常不会直接调用大多数内部编排端点。

对应用集成而言，最常用的是：

其中最常用的仍然是 /run 与 /webhook。

下一步​