sfappAPI 文件

限制與配額

這一頁列的是各鍵的意思與預設值。實際適用的值以 GET /v1/me 為準。

功能開關

features 的值皆為布林值。為 true 代表商店開通了該功能。

鍵 為 false 時
features.blog 文章端點回 404 feature_unavailable
features.blog_categories 分類端點回 404，文章不可帶 category_ids
features.media_upload 圖片端點回 404 feature_unavailable
features.summary summary 送出後被忽略，讀回為 null
features.cover_image 帶 cover_image_url 回 422 validation_failed
features.published_at_sort 列表只有預設排序

內容欄位

項目 預設值 GET /v1/me 欄位 超過時的錯誤碼
標題長度 255 字 limits.title_max_chars 422 validation_failed
標題可放 emoji 依商店而異 limits.title_allows_emoji 422 title_charset_unsupported
摘要長度 1000 字 limits.summary_max_chars 422 validation_failed
內文大小 1048576 位元組 limits.body_max_bytes 413 content_too_large
封面網址長度 2048 字元 無，固定值 422 validation_failed
分類名稱長度 255 字 無，固定值 422 validation_failed
分類層數 9 層 limits.category_max_depth 422 validation_failed
分類功能是否可用 依商店而異 limits.categories_supported 404 feature_unavailable

內文算的是位元組。UTF-8 之下一個中文字佔三個位元組，HTML 標籤一併計算。1 MiB 是 1048576 位元組。

標題與內文送出前會去除前後空白，去完不可為空。同一個父分類底下同名分類回 409 category_name_conflict。

圖片

項目 預設值 GET /v1/me 欄位 超過時的錯誤碼
單張檔案大小 10485760 位元組 limits.image_max_bytes 413 image_too_large
單張像素總量 25000000 limits.image_max_pixels 413 image_too_large
動畫全部影格像素總量 50000000 limits.image_max_total_pixels 413 image_too_large
動畫影格數 100 limits.image_max_gif_frames 413 image_too_large
輸出最大寬度 1600 像素 limits.image_max_width 自動等比縮小，只縮不放
可接受格式 image/jpeg、image/png、image/gif、image/webp limits.image_formats 415 unsupported_media_type

伺服器的處理規則見 圖片，上傳流程見 圖片與封面。

每日配額

配額按商店計算，以台北時間換日。只有新增計入配額，更新、發布、下架、刪除與讀取都不計。

項目 預設值 GET /v1/me 欄位 今日用量
每日新增文章 50 篇 quotas.posts_per_day quotas.posts_created_today
每日上傳圖片 200 張 quotas.images_per_day quotas.images_uploaded_today

用完回 429 quota_exceeded，retryable 是 false。排程作業先讀一次 quotas，再決定這一輪寫幾篇。

限流

限流按金鑰計算。讀與寫是兩條獨立額度，每分鐘補滿。

項目 預設值 GET /v1/me 欄位 超過時的錯誤碼
每分鐘讀取 120 次 rate_limits.read_per_minute 429 rate_limited
每分鐘寫入 30 次 rate_limits.write_per_minute 429 rate_limited
同時處理中的請求 4 個 rate_limits.concurrent_requests 429 concurrency_limited

通過認證的回應都帶 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。被擋下時多帶 Retry-After。

請求與分頁

項目 值
每頁筆數 1 到 50，預設 20（limits.list_limit_max）
游標長度 最長 64 字元，內容不透明，原樣帶回
Idempotency-Key 1 到 255 個可列印 ASCII 字元，建議用 UUID
冪等記錄保存 24 小時
內容去重時間窗 10 分鐘
刪除確認碼有效期 5 分鐘
X-Request-Id 最長 64 字元，限英數與 _ . -
金鑰有效期 365 天，到期時間看 GET /v1/me 的 key_expires_at

讀出自己的限制

curl -sS https://api.sfec.cloud/v1/me \
  -H "Authorization: Bearer $SFAPP_KEY"
import os

import requests

response = requests.get(
    "https://api.sfec.cloud/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SFAPP_KEY']}"},
    timeout=10,
)
response.raise_for_status()
me = response.json()

for name, value in sorted(me["limits"].items()):
    print(name, value)
print("文章", me["quotas"]["posts_created_today"], "/", me["quotas"]["posts_per_day"])
print("圖片", me["quotas"]["images_uploaded_today"], "/", me["quotas"]["images_per_day"])
const response = await fetch("https://api.sfec.cloud/v1/me", {
  headers: { Authorization: `Bearer ${process.env.SFAPP_KEY}` },
});
const me = await response.json();

console.log(me.limits);
console.log(me.quotas);
console.log(me.rate_limits);