素材庫常見問題

常見問題

主控台建立的分組在介面裡看不到

主控台建立的分組會出現在 GET /api/v1/materials/groups。如果手上只有分組 ID，也可以直接在 POST /api/v1/materials/assets 裡作為 group_id 使用，平台會先確認分組存在，再把它綁定到目前帳號，之後就會出現在分組清單裡。

審核失敗的原因在哪裡看

查詢素材傳回的 data.asset.error_message 就是失敗原因，只有 status 為 Failed 時才有內容，正常和可用狀態為 null。

圖片審核需要多久

審核和前置處理是非同步的，時間取決於素材本身，平台不對所有圖片承諾統一時長。程式應輪詢同一個素材 ID，不要因為初始狀態是 Processing 就重複提交。

頻繁查詢會不會被限制

狀態查詢是輕量介面，但不要在一個輪詢週期內重複並行請求，建議 5～10 秒查詢一次同一個素材 ID。請求過於頻繁時介面傳回 HTTP 429，稍後重試即可，已提交的素材不受影響。

圖片位址有什麼要求

必須是平台伺服器端能直接下載的 http(s) 位址（http 和 https 都支援），不能依賴 Cookie、Referer、登入頁面或 IP 白名單。如果圖片在需要登入的位址後面、在內網或只有本機檔案，請先轉存到物件儲存或使用 data_url，否則會出現素材處理失敗。

只要能提供公網位址就優先使用 image_url：平台原樣透傳位址，不做下載和轉存，提審速度最快；data_url 需要上傳整張圖的 base64，明顯較慢，並且會佔用平台儲存空間。