WebYore API v1

Authentication

所有 API 請求都使用帳戶建立的 Bearer API key。請把金鑰放在 Authorization header，不要放進 URL 或公開的前端程式碼。

Authorization: Bearer wy_live_your_key

Idempotency-Key

所有 POST、PATCH 與 DELETE 請求都必須提供 8 至 128 字元的唯一 Idempotency-Key；系統保留該紀錄 24 小時。

Idempotency-Key: request-20260831-0001

相同 key 與相同 request 可安全重試；相同 key 搭配不同內容會回傳 409 conflict。

上傳與網址匯入

首次建立可使用 auto、general 或 nsfw。網址匯入必須提供直接回傳圖片檔案的公開網址；若來源以 403 拒絕伺服器，網站介面會在取得同意後提供瀏覽器匯入，API 客戶端則可自行下載後改用 multipart 上傳。

POST /images/url
Content-Type: application/json
Idempotency-Key: image-import-0001

{
  "url": "https://example.com/photo.jpg",
  "content_rating": "auto"
}

狀態、分級與交付

建立後請輪詢 status_url。ready 時即可使用 url 嵌入圖片；一般圖片為 WebP，大型動畫保留 WebP 或 GIF，請使用回傳網址與 mime_type，不要自行拼接副檔名。share_url 是含分級與檢舉入口的分享頁。自動分級會在背景完成，ready 不代表已完成分級；content_rating 可能先是 unrated，稍後透過 GET /images/{id} 或直連 HEAD 取得更新。unrated 代表尚未完成或無可用的分級結果，不代表 SFW；需要安全預設時請比照 nsfw 處理。

PATCH /images/{id}/rating
Idempotency-Key: image-rating-0001

{ "content_rating": "sensitive" }

新圖片網址使用 7 碼 ID，既有網址仍可使用。不需要 API Key，對圖片直連送出 HEAD 即可從 X-WebYore-Content-Rating 取得目前分級，不會下載圖片。值為 general、sensitive、nsfw 或 unrated；跨網站 JavaScript 也能讀取此 header。下架或尚未完成的圖片不會回傳分級 header。

curl -I "https://i.webyore.com/Ab3De7X.webp"

X-WebYore-Content-Rating: nsfw

權限不足回應

缺少必要 scope 時，API 會回傳 403 與結構化 api_scope_required 錯誤。detail 是這次操作所需的 scope。

{
  "error": {
    "code": "api_scope_required",
    "message": "The API key is missing a required scope.",
    "request_id": "req_...",
    "detail": "images:write"
  }
}