文件端点
使用 /files 端点上传、列出、下载和删除 SkillFlaw 管理的文件。
本页示例默认使用 x-api-key 认证。
/api/v1/files 与 /api/v2/files 都是受保护端点。
/v1/files 与 /v2/files 的区别
SkillFlaw 当前同时暴露两套文件 API：
/api/v1/files：工作流范围接口，按{flow_id}和文件名定位文件，适合流程相对路径与 Chat Input 图片上传场景/api/v2/files：数据库驱动的文件管理接口，按文件 UUID 管理，记录 tenant / business / workflow 作用域，并支持改名、批量下载、批量删除与追加上传
对于 POST /api/v2/files，你必须提供以下任一上下文：
flow_id查询参数（指向你拥有的流程）- scope 头，例如
tenant-id（以及可选的business-id、is-self）
如果你传了 session_id，则必须同时提供 flow_id。
Files / V1 端点
上传文件（v1）
把文件上传 到你拥有的某个流程名下：
_10curl -X POST \_10 "$SKILLFLAW_URL/api/v1/files/upload/$FLOW_ID" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -F "file=@notes.txt"
上传图片文件（v1）
你也可以先上传图片，再把返回的 file_path 传给流程运行请求：
- 先上传图片：
_10curl -X POST \_10 "$SKILLFLAW_URL/api/v1/files/upload/$FLOW_ID" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -F "file=@PATH/TO/diagram.png"
- 再在流程运行时复用
file_path：
_14curl -X POST \_14 "$SKILLFLAW_URL/api/v1/run/$FLOW_ID?stream=false" \_14 -H "Content-Type: application/json" \_14 -H "x-api-key: $SKILLFLAW_API_KEY" \_14 -d '{_14 "output_type": "chat",_14 "input_type": "chat",_14 "tweaks": {_14 "ChatInput-b67sL": {_14 "files": "92f9a4c5-cfc8-4656-ae63-1f0881163c28/2026-04-28_10-35-12_diagram.png",_14 "input_value": "Describe this image"_14 }_14 }_14 }'
列出文件（v1）
_10curl -X GET \_10 "$SKILLFLAW_URL/api/v1/files/list/$FLOW_ID" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY"
下载文件（v1）
_10curl -X GET \_10 "$SKILLFLAW_URL/api/v1/files/download/$FLOW_ID/2026-04-28_10-35-12_notes.txt" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 --output downloaded-notes.txt
删除文件（v1）
_10curl -X DELETE \_10 "$SKILLFLAW_URL/api/v1/files/delete/$FLOW_ID/2026-04-28_10-35-12_notes.txt" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY"
Files / V2 端点
/api/v2/files 会在数据库中记录文件元数据，并返回规范化文件记录。
列表操作默认只返回当前用户创建的文件。
上传文件（v2）
_10curl -X POST \_10 "$SKILLFLAW_URL/api/v2/files" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -H "tenant-id: $TENANT_ID" \_10 -F "file=@engine-manual.pdf"
可选查询参数：
| 参数 | 类型 | 说明 |
|---|---|---|
flow_id | UUID | 把文件绑定到某个流程 |
session_id | UUID | 进一步绑定到某个流程会话；仅在 flow_id 存在时有效 |
file_type | string | 覆盖存储的媒体类型 |
append | boolean | 对相同逻辑文件执行追加写入 |
上传工作流范围文件（v2）
如果你希望文件直接与某个流程或流程会话绑定：
_10curl -X POST \_10 "$SKILLFLAW_URL/api/v2/files?flow_id=$FLOW_ID&session_id=$SESSION_ID" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -F "file=@knowledge-base.csv"
在流程里使用 v2 文件
上传后，把返回的逻辑 path 传给支持文件路径的组件，例如 Read File：
_16curl -X POST \_16 "$SKILLFLAW_URL/api/v1/run/$FLOW_ID" \_16 -H "Content-Type: application/json" \_16 -H "x-api-key: $SKILLFLAW_API_KEY" \_16 -d '{_16 "input_value": "Summarize the uploaded file",_16 "output_type": "chat",_16 "input_type": "text",_16 "tweaks": {_16 "Read-File-1olS3": {_16 "path": [_16 "07e5b864-e367-4f52-b647-a48035ae7e5e/d44dc2e1-9ae9-4cf6-9114-8d34a6126c94.pdf"_16 ]_16 }_16 }_16 }'
列出文件（v2）
_10curl -X GET \_10 "$SKILLFLAW_URL/api/v2/files" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY"
下载文件（v2）
_10curl -X GET \_10 "$SKILLFLAW_URL/api/v2/files/$FILE_ID" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 --output downloaded-file.pdf
修改文件名（v2）
_10curl -X PUT \_10 "$SKILLFLAW_URL/api/v2/files/$FILE_ID?name=new-file-name" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -H "tenant-id: $TENANT_ID"
删除单个文件（v2）
_10curl -X DELETE \_10 "$SKILLFLAW_URL/api/v2/files/$FILE_ID" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -H "tenant-id: $TENANT_ID"
批量下载文件为 ZIP（v2）
_10curl -X POST \_10 "$SKILLFLAW_URL/api/v2/files/batch/" \_10 -H "Content-Type: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -d '[_10 "c7b22c4c-d5e0-4ec9-af97-5d85b7657a34",_10 "76543e40-f388-4cb3-b0ee-a1e870aca3d3"_10 ]' \_10 --output skillflaw-files.zip
批量删除文件（v2）
_10curl -X DELETE \_10 "$SKILLFLAW_URL/api/v2/files/batch/" \_10 -H "Content-Type: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -H "tenant-id: $TENANT_ID" \_10 -d '[_10 "c7b22c4c-d5e0-4ec9-af97-5d85b7657a34",_10 "76543e40-f388-4cb3-b0ee-a1e870aca3d3"_10 ]'
删除当前作用域下全部文件（v2）
_10curl -X DELETE \_10 "$SKILLFLAW_URL/api/v2/files" \_10 -H "accept: application/json" \_10 -H "x-api-key: $SKILLFLAW_API_KEY" \_10 -H "tenant-id: $TENANT_ID"
其他文件相关端点
除此之外，SkillFlaw 还提供：
GET /api/v1/files/images/{flow_id}/{file_name}：直接渲染上传图片GET /api/v1/files/profile_pictures/list：列出内置头像GET /api/v1/files/profile_pictures/{folder_name}/{file_name}：读取内置头像资源POST /api/v1/files/profile_pictures/upload：上传用户头像GET /api/v1/files/profile_pictures/uploaded/by-id/{file_id}：按 file ID 获取头像