Developer & AI Automation

开发者接入与 AI 自动化指南

为 AI 编程助手（Cursor、Claude Code 等）、发布流水线与本地脚本提供图片资产管理能力。支持标准 REST API、OpenAPI 规范与最小权限 Agent Key。

/openapi.json /llms.txt Base URL: https://slnt.dev

1 快速接入 (cURL)

设置环境变量 SILENTFLOW_API_KEY，使用 multipart 上传图片（公开 v1 API 当前仅管理图片）：

bash

export SILENTFLOW_API_KEY="sf_agent_your_scoped_key_here"

curl -X POST https://slnt.dev/v1/files   -H "Authorization: Bearer $SILENTFLOW_API_KEY"   -F "file=@./screenshot.png"

成功响应 (200 OK)

{
  "url": "https://sf-cdn.cc/s/2026/08/screenshot_a7b9.webp",
  "key": "2026/08/screenshot_a7b9.webp",
  "product": "images",
  "usage": {
    "used": 15482910,
    "limit": 53687091200,
    "percent": "0.03%"
  }
}

⚠️ 交付域名说明： 默认生产交付域名为 https://sf-cdn.cc（专业版支持自定义域名），主站 slnt.dev 明确拒绝 /s 路径文件读取。客户端必须始终直接使用响应中的 url 字段，严禁根据 API host 自行拼接交付地址。

2 认证机制与 Scoped Agent Key

所有 API 请求必须在 HTTP Header 中携带 Bearer 令牌： Authorization: Bearer <TOKEN>。

安全须知：避免硬编码与凭证泄露

请始终通过环境变量（如 SILENTFLOW_API_KEY）注入凭证。严禁将密钥直接写入命令参数、聊天提示词或公开代码仓库中。

使用账号主密钥（sk_live_...）可以签发权限受限的 Agent Key（sf_agent_...）。服务端仅保存令牌的 SHA-256 哈希摘要，原始令牌在创建成功时仅展示一次。

Agent Key 权限范围 (Scopes)

files:write

允许上传新图片资产并计入存储用量。

files:read

允许查询配额用量与检索个人文件列表。

files:delete

允许删除名下已上传文件并释放存储空间。

3 SilentFlow CLI 本地命令行

适用于终端流水线与 Coding Agent 本地任务。零第三方依赖，自动读取环境变量，所有结果输出为 JSON。CLI 源码位于 silentflow-client。

0. 获取 CLI

git clone https://github.com/weidlu/skills.git
cd skills/silentflow-client

1. 上传本地图片

python3 scripts/silentflow.py upload ./docs/assets/architecture.png

2. 查看当前配额与流量使用率

python3 scripts/silentflow.py usage

3. 列出最新上传的文件

python3 scripts/silentflow.py list --limit 10

4. 删除指定 Key 的文件

python3 scripts/silentflow.py delete 2026/08/screenshot_a7b9.webp --dry-run
# 核对 exact key 后再执行：
python3 scripts/silentflow.py delete 2026/08/screenshot_a7b9.webp --yes

5. 用账号主密钥签发最小权限 Agent Key

python3 scripts/silentflow.py keys create   --name codex-local   --scope files:read   --scope files:write

4 REST API 接口规范

POST https://slnt.dev/v1/files

上传二进制图片文件，服务端校验 MIME 类型与文件魔数并返回公开链接。

curl -X POST https://slnt.dev/v1/files   -H "Authorization: Bearer $SILENTFLOW_API_KEY"   -F "file=@./diagram.png"

GET https://slnt.dev/v1/usage

获取当前用户的套餐类型、存储使用量与本月已用流量。

curl -X GET https://slnt.dev/v1/usage   -H "Authorization: Bearer $SILENTFLOW_API_KEY"

GET https://slnt.dev/v1/files?limit=20&cursor=...

分页检索用户已上传的图片列表及公开链接。

curl -X GET "https://slnt.dev/v1/files?limit=20"   -H "Authorization: Bearer $SILENTFLOW_API_KEY"

DELETE https://slnt.dev/v1/files/{public_key}

删除指定图片并释放配额；对象存储暂时不可用时返回 202，并由持久清理队列继续重试。

curl -X DELETE "https://slnt.dev/v1/files/2026/08/screenshot_a7b9.webp"   -H "Authorization: Bearer $SILENTFLOW_API_KEY"

5 错误结构与状态码

v1 接口在鉴权失败或参数错误时返回标准 application/problem+json 结构：

{
  "type": "https://slnt.dev/problems/invalid_file_type",
  "title": "invalid_file_type",
  "status": 400,
  "code": "invalid_file_type",
  "detail": "The file content does not match a supported type."
}

HTTP 状态码	含义说明	错误 code 标识
401 Unauthorized	Bearer Token 缺失或无效	`unauthorized`
403 Forbidden	Agent Key 缺少当前操作所需权限	`insufficient_scope`
404 Not Found	文件不存在或已被删除	`file_not_found`
413 Payload Too Large	单文件尺寸超出当前套餐上限	`file_size_invalid`
400 Bad Request	非允许图片类型或魔数校验失败	`invalid_file_type`
415 Unsupported Media Type	v1 接口明确拒绝音频或播客格式	`unsupported_product`

6 协议选择与生态路线

为什么当前优先提供 REST API 与本地 JSON CLI？

REST API 与零依赖本地 CLI 具备确定性、高通用性与最小开销，能够被各类编程助手、发布流水线与终端脚本直接调用，避免了在远端运行非必要长期协议服务的复杂性。

Model Context Protocol (MCP) 说明

当前未发布公开远端 MCP Server，也未提供官方本地 stdio 适配层。需要 MCP 的宿主必须另行实现本地适配层；当前官方交付只有 REST API、OpenAPI 规范与本地 JSON CLI。