sfappAPI 文件

圖片

圖片物件是一張存放在平台上的圖片，欄位全部唯讀。

圖片端點需要 features.media_upload 為 true，關閉時回 404 feature_unavailable。共通錯誤（validation_failed、insufficient_scope、rate_limited）見 錯誤。

端點

方法與路徑 中文名 所需權限
POST /v1/media/images 上傳圖片 write_media
DELETE /v1/media/images/{id} 刪除圖片 write_media

圖片物件

欄位 型別 必填或可為 null 用途
id 字串 必填 圖片識別碼，img_ 開頭
basename 字串 必填 伺服器產生的檔名
path 字串 必填 站內相對路徑
url 字串 必填 完整網址，填進文章的 cover_image_url 即設為封面
content_type 字串 必填 實際內容型別
width 整數 必填 輸出寬度（像素）
height 整數 必填 輸出高度（像素）
bytes 整數 必填 輸出位元組數

POST/v1/media/images

內文以 multipart/form-data 送出，欄位 file（二進位，必填）圖片檔，一次一張。

這個端點無須 Idempotency-Key。同一商店重複上傳同一份內容會回既有圖片與 200，新圖片回 201。

處理規則：

  • 接受 JPEG、PNG、GIF、WebP，格式依檔案內容判定，副檔名無效力，SVG 一律拒絕。
  • 檔案大小上限見 limits.image_max_bytes。
  • 解碼前先看檔頭宣告的尺寸，寬乘高超過 limits.image_max_pixels 即拒絕。
  • 動畫 GIF 逐格處理，影格數上限 limits.image_max_gif_frames，影格像素總和上限 limits.image_max_total_pixels。
  • 寬度超過 limits.image_max_width 會等比縮小，只縮不放。
  • 圖片一律重新編碼，EXIF 中繼資料（含 GPS 定位）會移除；色彩描述檔保留，GIF 除外。
  • 檔名由伺服器重新產生，副檔名依實際內容決定。
  • 每日張數上限見 quotas.images_per_day。
錯誤碼 狀態碼 處理動作 可重試
unsupported_media_type 415 轉成 JPEG、PNG、GIF 或 WebP 再上傳 否
image_too_large 413 縮小檔案或尺寸，上限見 限制 否
validation_failed 422 表單欄位名改成 file，或換一張可讀的圖 否
quota_exceeded 429 等每日配額重置 否

DELETE/v1/media/images/{id}

路徑 id（字串，必填）圖片識別碼，上傳回應的 id。

刪除無法復原。刪除後指向這張圖的網址都會失效。成功回 204，沒有回應內文。

文章拿它當封面或在內文引用時回 409 image_in_use。草稿計入。details 最多列 20 篇文章。先用 PATCH /v1/blog/posts/{id} 換掉封面或移除引用，再刪一次。

只刪得掉這個商店經平台上傳的圖片。找不到、屬於別的商店或已刪除都回 404。同一個刪除重送結果相同。刪除後重新上傳同一份內容會得到新的 id 與新檔名。

錯誤碼 狀態碼 處理動作 可重試
image_in_use 409 依 details 的文章識別碼移除引用 否
not_found 404 確認識別碼來自這個商店的上傳回應 否
concurrency_limited 429 稍等後重送 是
internal_error 500 稍後再試，圖片狀態已回復 是