云存图床

DEVELOPER DOCUMENTATION

把上传能力接入
你的工作流。

基于 API Key 的文件上传服务。图片、视频、压缩包和任意文件都通过 FTP/FTPS 写入 NAS，并返回可直接使用的访问链接。

快速开始配置 Typora
BASE URL
{{BASE_URL}}
FTP storage online
5 GB单文件上限20单次最多文件10 GB默认用户空间
当前访问地址本页的 Base URL 和示例接口随当前页面地址自动变化；用哪个地址请求上传或文件列表，返回的文件链接就使用哪个地址。HTTP、HTTPS 和端口会一并保留。保存到 Typora 的脚本使用其中的 ENDPOINT 地址，切换入口时请修改该项。
01

快速开始

三步拿到第一个文件链接。

1

创建 API Key

进入图床首页的“开发接口”，生成并立即保存 Key。密钥只显示一次，每个 Key 可以绑定不同的默认上传目录。

2

携带认证请求

在请求头中加入 Authorization: Bearer YOUR_API_KEY，也支持 X-API-Key。

3

读取返回链接

单文件使用 url；多文件使用 urls 或 files[i].url。

02

上传文件

支持任意文件类型，服务端直接流式写入 NAS。

POST/api/uploadmultipart/form-data

请求参数

file 必填，可多个
要上传的文件，字段名固定为 file。
folderId 可选
临时指定目录。不传时使用 Key 的默认目录；没有 Key 目录时使用 default。

curl

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "folderId=FOLDER_ID" \
  -F "file=@image.png" \
  {{BASE_URL}}/api/upload
03

目录与文件管理

用接口读取目录，上传时按需覆盖默认目录。

方法路径用途
GET/api/folders读取当前用户的全部目录与文件数量
POST/api/folders创建目录，JSON：{"name":"screenshots"}
GET/api/files?page=1&pageSize=20&folderId=...分页读取上传记录
DELETE/api/files/:id删除自己的文件，同时删除 NAS 上的文件
04

返回值与错误

所有接口返回 JSON，并包含 success 字段。

上传成功

{
  "success": true,
  "url": "{{BASE_URL}}/f/id/photo.png",
  "urls": ["{{BASE_URL}}/f/id/photo.png"],
  "data": ["{{BASE_URL}}/f/id/photo.png"],
  "files": [{
    "id": "...", "name": "photo.png",
    "size": 48321, "mime": "image/png",
    "folderName": "default", "url": "{{BASE_URL}}"
  }]
}

常见状态码

  • 401未登录或 API Key 无效
  • 413文件超过上限或用户空间不足
  • 429达到每日次数或每分钟频率限制
  • 502NAS FTP 连接或读写失败
05

Typora 配置

使用自定义命令，让 Typora 自动上传并把返回 URL 插入文档。

01打开 Typora → 偏好设置 → 图像。
02上传服务选择“自定义命令”。
03命令填写本机上传脚本的绝对路径。
04点击“验证图片上传选项”，脚本最后输出每个文件一行 URL。
nas-typora-upload.shmacOS / Linux
#!/bin/bash
set -euo pipefail
API_KEY='YOUR_API_KEY'
ENDPOINT='{{BASE_URL}}/api/upload'

for file in "$@"; do
  response=$(curl -fsS -X POST \
    -H "Authorization: Bearer ${API_KEY}" \
    -F "file=@${file}" "$ENDPOINT")
  python3 -c 'import json,sys; print(json.load(sys.stdin)["url"])' \
    <<< "$response"
done
目录规则不传 folderId 时自动进入当前 Key 绑定的默认目录；如果需要临时切换目录，在脚本中追加 -F "folderId=目录ID"。目录 ID 可从 GET /api/folders 获取。
06

开发示例

将 YOUR_API_KEY 替换为创建时保存的 Key。密钥仅在创建时显示一次，服务器不保存可恢复的明文。

Node.js 18+

import fs from "node:fs";
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("image.png")]), "image.png");
const res = await fetch(
  "{{BASE_URL}}/api/upload",
  { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY" }, body: form }
);
console.log((await res.json()).url);

Python

import requests

r = requests.post(
    "{{BASE_URL}}/api/upload",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"file": open("image.png", "rb")},
)
print(r.json()["url"])