接入與認證
兩個 API 域名的資料一樣嗎？
兩個 API 域名的資料一樣嗎？
是。
api.heizhu.lol 和 api.heizhu.lol 連線同一套使用者、餘額、Token、模型與任務資料。新接入推薦使用 https://api.heizhu.lol。API Token 可以放在網頁前端嗎？
API Token 可以放在網頁前端嗎？
不可以。Token 應只儲存在服務端環境變數或金鑰管理服務中。網頁和客戶端應請求你自己的後端，再由後端呼叫黑豬AI。
影片任務
任務提交後多久完成？
任務提交後多久完成？
沒有固定完成時間。模型、時長、素材複雜度和實時排隊情況都會影響處理速度。請使用任務 ID 查詢最終狀態。
queued 或 in_progress 是失敗嗎？
queued 或 in_progress 是失敗嗎？
不是。它們分別表示排隊中和生成中。只有狀態變為
failed 才是最終失敗。查詢介面超時後需要重新建立任務嗎？
查詢介面超時後需要重新建立任務嗎？
不需要。查詢超時不改變任務狀態，請保留原任務 ID，稍後繼續查詢。直接重建可能產生重複任務和重複計費。
為什麼提示詞相同，生成結果仍然不同？
為什麼提示詞相同，生成結果仍然不同？
影片生成具有隨機性。模型版本、參考素材、提示詞表達和內容安全策略都可能影響結果。正式生產前應先進行小規模測試。
參考素材
可以直接傳本地檔案路徑嗎？
可以直接傳本地檔案路徑嗎？
不可以。請先將素材上傳至公網可訪問的物件儲存或 CDN，再傳入 HTTP/HTTPS URL。
為什麼瀏覽器能開啟素材，上游卻讀取失敗？
為什麼瀏覽器能開啟素材，上游卻讀取失敗？
瀏覽器可能帶有登入狀態或快取。請確認 URL 無需 Cookie、Referer 或賬號登入，並且不會在任務處理期間過期。
平臺會先把素材下載到本地嗎？
平臺會先把素材下載到本地嗎？
介面以 URL 方式接收並傳遞參考素材，不要求客戶端或平臺外掛先下載一份本地檔案。模型服務會透過該 URL 讀取素材。
計費與退款
按次和按秒計費有什麼區別？
按次和按秒計費有什麼區別？
按次模型每個任務按固定價格計費；按秒模型按每秒售價乘實際秒數計費。以模型廣場顯示的
/次 或 /秒 為準。為什麼建立任務時先扣費？
為什麼建立任務時先扣費？
影片生成是非同步任務，平臺會在建立時根據模型和時長鎖定計費規則並預扣，等待任務最終完成或失敗後結算。
任務失敗會退款嗎？
任務失敗會退款嗎？
任務最終狀態為
failed 時，平臺按失敗退款規則退還該任務費用。排隊或處理中尚未得到最終結果，需要繼續等待。主動重試會再次收費嗎？
主動重試會再次收費嗎？
會。主動重試會建立新的獨立任務，並按照新任務的模型與時長規則計費。