WaveSpeedAI

Genjutsu API:提交一個物件替換影片

使用 Genjutsu API 處理單次物件替換請求:準備來源影片片段、提交任務,並取得編輯後的影片。

By John2 min read
Genjutsu API:提交一個物件替換影片

一個影片編輯功能可能回傳成功的任務,卻仍讓團隊拿到無法使用的素材:處理了片段中錯誤的部分、替換物件在影格之間漂移,或是沒有人儲存輸出結果。針對 Genjutsu API 的整合,我會讓每一次編輯從輸入到核准檔案都可追溯。Higgsfield 的 API quick start 說明了提交、輪詢、取回的流程;本指南將它套用到單一 Object Swap 請求上。

Higgsfield 提供模型與端點。如果你的產品使用 WaveSpeedAI,請在其模型目錄中查找這項具體操作及其自身的請求結構(schema)。不要假設其他影片替換模型能接受 Higgsfield 的請求。

一次 Genjutsu Object Swap 請求需要哪些內容?

一次請求需要一個來源影片 URL 以及一到八個參考圖片 URL。提示詞為選填。resolution 預設為 720p;另列有 480p 與 1080p。Object Swap API 參考文件將該模型標示為 higgsfield/genjutsu/object-swap/v1.0。它要求影片長度至少四秒,且每個影格至少 409,600 像素。

提交前先檢查影片片段。超過 30 秒的影片會被裁切為 30 秒,輸出結果也以裁切後的長度為準。如果想要的編輯發生在第 34 秒,即使請求成功,也無法交付該編輯。請先選定片段,並記錄你提交的是哪一段。

伺服器端請求可以採用以下格式。其中的 URL 與環境變數僅為示意:

curl -X POST \
  "https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
  -H "Authorization: Key ${HF_KEY}" \
  -H "Idempotency-Key: ${EDIT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/approved-source.mp4",
    "image_urls": ["https://example.com/approved-object.png"],
    "prompt": "Replace the featured cup with the reference cup.",
    "resolution": "720p"
  }'

請將憑證保存在你的伺服器上。為每一次邏輯上的編輯指定固定的冪等金鑰(idempotency key),這樣在提交結果不明確時可以重試,而不會刻意產生第二個任務。如果來源影片中出現可識別的人物,或使用了受保護的影片素材或美術作品,請在上傳前取得必要的權利與同意。這是正式上線時的提醒,並非法律建議。

提交編輯並追蹤狀態

POST 成功只代表任務已被接受,並不會直接回傳完成的影片。請將回應中的 request_id、status_url 與 cancel_url 儲存到你產品的編輯紀錄中。請使用回傳的這些 URL,而不要自行組合。

Higgsfield 的請求生命週期文件將 queued 與 in_progress 列為非終止狀態。當狀態變為 completed、failed、nsfw 或 canceled 時,就應停止等待。請在介面中分別顯示這些結果。當服務商已經拒絕該任務時,仍顯示「處理中」是很差的回饋。

以大約兩秒的間隔開始輪詢,等待時間較長時再逐步拉長間隔。如果狀態查詢遇到暫時性的網路錯誤,請重試狀態查詢。不要只因為某一次輪詢失敗,就再 POST 一次編輯。請將最終狀態及任何回傳的錯誤,與請求 ID 一併儲存,讓客服能分辨是生成失敗,還是瀏覽器工作階段提前結束。

取回並檢查完成的影片

當狀態為 completed 時,從結果中讀取 video.url。將檔案下載到你的產品所掌控的儲存空間,然後檢查它能否播放,以及是否符合預期的編輯。API 任務完成只代表有一個可供交付的候選檔案,並不等於核准。

檢查時不要只看縮圖。請檢查片段開頭、中段與結尾的替換效果,特別是物件移到其他主體後方,或穿過畫面邊緣的地方。將處理後的長度與你提交的片段進行比對。如果聲音對該功能很重要,也請檢查輸出的音軌;Object Swap 參考文件並未承諾保留來源音訊。

單一輸出效果良好,並不代表正式上線的工作流程已經就緒。服務商完成任務只說明檔案存在,而是否能讓該檔案進入產品,則由你的驗收檢查決定。

讓 Object Swap 在正式環境中可重現

儲存可重播的編輯清單

請將來源素材版本、選定的時間範圍、參考圖片版本、提示詞、解析度、模型 ID、冪等金鑰、請求 ID 與最終狀態放在一起。再加上核准輸出的儲存位置。一個人可以記住參數,但一個團隊不行。

當編輯人員要求「同樣的替換,但改用藍色產品」時,這份紀錄就能派上用場。團隊可以刻意只更動一項輸入,而不必從一個名為 final-v3.mp4 的檔案去重建先前的請求。

封存原始檔案與核准的輸出

請保留原始影片以便回復,並將核准的結果儲存在服務商的暫存媒體位置之外。Higgsfield 的 API 條款中關於保留與同意的部分指出,生成的媒體至少可取得七天,之後可能被刪除。這並不是永久 URL 的保證。請記錄結果是被接受、被拒絕,還是退回修改,以及原因。

常見問題

Object Swap 會保留來源影片的音訊嗎?

已發布的 Object Swap 參考文件並未說明。請不要在你的產品中承諾音訊直通。請使用已取得授權、含有可辨識音軌的影片進行測試,並在宣稱此功能之前檢查回傳的檔案。

排隊中的 Genjutsu 請求可以取消嗎?

可以,只要它仍符合在佇列中取消的條件。請向回傳的 cancel_url 發送取消請求;僅僅停止你的輪詢程式並不會取消任務。依照文件所載的生命週期,一旦開始處理,就無法再取消。

如果來源 URL 在準備期間過期會怎麼樣?

文件並未針對 Object Swap 輸入 URL 過期的情況,指明統一的失敗時間點。請在 Higgsfield 可能需要擷取來源檔案的期間,保持該來源可被存取。如果準備階段失敗,請記錄實際的請求狀態與錯誤。POST 被接受,並不能證明檔案已經被下載。

輸入準備失敗會消耗計費單位嗎?

這取決於回報的失敗類型。Higgsfield 的計費與保留指引指出,以 failed 或 nsfw 結束的請求不會收費,預留的點數也會退還。「輸入準備失敗」本身並不是一種計費狀態,因此請查看回應與計費紀錄,而不要對每一個這類錯誤套用同一條規則。

完成的影片 URL 可以維持多久?

生成的媒體至少可存取七天,之後可能被移除。請儘快下載已核准的影片。對於使用者可能數週後再回來查看的 Genjutsu API 功能,請從你自己的儲存空間提供已保存的副本。


往期文章:

分享