API 文档
API 仅对有效的 Pro / Premium 订阅开放。使用密钥鉴权后,上传的图片会进入与工作台相同的资源库,额度与网页付费套餐一致。
上传图片
向 /api/v1/upload 发起 POST(multipart/form-data)。
参数
Authorization- 必填。请求头,格式 Bearer 你的 API 密钥。
file- 必填。二进制文件,或 base64 数据。
name- 可选。文件名;用 multipart 上传本地文件时会自动识别。
示例调用
二进制文件
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=@./product.jpg"
Base64
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \ -F "name=pixel.gif"
上传本地文件请始终使用 POST。本接口不支持用 GET 上传。
返回字段
id- 资源库中的图片 id。
url- 可直接用在商品页的 CDN 链接。
fileName- 原始文件名。
fileSize- 文件大小(字节)。
mimeType- 上传文件的 MIME 类型。
createdAt- 上传时间(UTC),格式 YYYY-MM-DD HH:mm:ss。
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileName": "product.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}列出图片
GET /api/v1/images,可用 page、pageSize(最大 100)。
curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
返回字段
resources- 图片数组:id、fileName、url、fileSize、mimeType、createdAt。
page- 当前页码。
pageSize- 每页条数。
total- 资源库图片总数。
{
"resources": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fileName": "product.jpg",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}
],
"page": 1,
"pageSize": 20,
"total": 1
}删除图片
DELETE /api/v1/images/:id。会同时删除存储文件与资源库记录。
curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
返回字段
success- 删除成功时为 true。
{ "success": true }额度说明
免费账号不可用 API。Pro / Premium 按套餐的上传次数、存储与单文件上限执行。超限时 API 返回错误,并可能包含 upgradeUrl。
错误说明
失败时返回 error 字段;额度类错误可能带 upgradeUrl。
dailyLimitReached— 达到每日上传上限(HTTP 429)。storageLimitReached— 存储空间不足(HTTP 413)。fileTooLarge— 文件超过套餐单文件上限(HTTP 400)。401— 缺少、无效或已吊销的 API 密钥。
{
"error": "dailyLimitReached",
"errorParams": { "limit": 1000 },
"plan": "paid",
"limit": 1000,
"upgradeUrl": "https://www.phototourl.com/pricing"
}