多圖與參考影片說明

本頁回答「多張參考圖 + 一個參考影片」的程式接入問題，包括能力邊界、順序規則、深度影片、音訊、任務恢復和計費。請求內容的完整欄位表和可複製範例見影片生成介面，素材入庫見素材庫介面。

先看結論

• 多張圖片和一個參考影片使用同一個 content 陣列：每張圖片佔一個 image_url 元素，影片佔一個 video_url 元素。
• 「深度影片」沒有獨立的 deep_video 欄位，依一般參考影片提交，role 使用 reference_video。
• 陣列順序就是素材順序。建議在提示詞裡明確寫「圖片1、圖片2、圖片3、參考影片」，不要依賴伺服器端依檔名猜順序。
• generate_audio: false 表示關閉生成結果的音訊輸出，它不等於保留輸入參考影片的原聲音軌，也不等於把輸入音訊複製到成片。
• 精確的圖片數量、影片數量、檔案大小、編碼和並行上限以模型目錄和實際介面回應為準，平台沒有為所有 Seedance 變體承諾一套統一上限。
• 如果必須保留原片的動作、機位和切鏡，參考影片只能作為模型參考。目前公開請求沒有「在第 N 秒強制切鏡」的通用參數，精確時序不能僅靠介面欄位保證。

一、確認目前模型能力

先讀取目前 Key 可見的模型目錄：

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

目錄只確認「模型是否可見、可用於哪些介面」，data[].id 才是請求時要填的 model。參考圖片數量、參考影片、參考音訊、輸出比例、時長和解析度等具體限制，以模型詳細頁和介面傳回的參數錯誤為準；目錄沒有列出的限制，平台不會替模型猜測。

二、參考素材的入庫與引用

虛構人物設定圖、角色多視圖和無人場景圖都不是真人授權素材，依一般虛擬素材入庫：

POST /api/v1/materials/groups
POST /api/v1/materials/assets
GET  /api/v1/materials/assets/{asset_id}

素材狀態變成 Active 後，影片請求裡的圖片 URL 可以改成：

asset://asset-20260911035115-etexu

圖片逐張入庫時，每一張都會得到獨立的 asset_id。人物圖和場景圖可以放在同一個虛擬分組，也可以分別建立分組；提交影片時透過不同的 content 元素引用。入庫、輪詢和錯誤回應見素材庫介面。

提交成功時 status 通常是 Processing，處理完成後變成 Active；失敗時 status 為 Failed、error_message 給出原因。審核是非同步處理，平台不對所有圖片承諾統一時長，程式應查詢同一個 asset_id，不要在 Processing 時重複提交。

三、多圖 + 一個參考影片

下面的請求表達「1 張人物圖 + 2 張場景圖 + 1 個參考影片」。陣列索引從 1 開始解釋：

1. content[1] 是圖片1，人物圖；
2. content[2] 是圖片2，場景圖1；
3. content[3] 是圖片3，場景圖2；
4. content[4] 是參考影片。

content[0] 是文字提示詞，不計入圖片編號。

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    {
      "type": "text",
      "text": "图片1是人物身份参考，图片2和图片3是场景参考。参考视频用于动作、机位和镜头节奏参考；保持人物身份和场景关系一致。"
    },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://人物素材ID" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID1" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID2" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://你的对象存储域名/reference-depth.mp4" } }
  ],
  "duration": 7,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}

建立成功後傳回任務 ID，隨後只查詢這個任務：

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

如果回應明確提示目前模型不支援素材庫，應改用該模型支援的公網 HTTPS 圖片位址或更換模型，不要繞過素材審核。完整的建立、查詢回應範例見影片生成介面。

四、參考影片、聲音和深度影片的邊界

參考影片不是精確控制軌道

灰階深度影片在公開介面結構裡仍是普通 reference_video。除非目前模型詳細單獨宣告深度控制能力，否則平台不會把灰階值解釋成深度約束，也不會保證嚴格複製原影片的深度、動作軌跡或切鏡。

參考影片可以幫助模型理解動作、機位、構圖和節奏，但成片仍由模型重新生成。目前公開請求沒有通用的時間碼軌道或強制切鏡欄位，需要接近某個時間點切鏡時，只能在提示詞裡說明，並在生成後檢查成片；如果必須達到影格級精確，應在外部剪輯或合成階段完成。

輸入音軌與 generate_audio

參考影片帶原聲音軌時，模型是否讀取該聲音軌取決於目前模型的參考影片實作。generate_audio: false 的確定含義是關閉生成結果的音訊輸出，它不承諾複製輸入影片音軌，也不承諾把輸入音軌作為獨立參考音訊使用。

• 目標是「生成無聲影片」時，可以傳 generate_audio: false；
• 目標是「保留原片聲音」時，不要只依賴這個欄位，應在成片下載後用你自己的影音合成流程處理，或選擇模型詳細明確支援參考音訊和輸出音訊的設定；
• 模型詳細沒有宣告支援參考音訊時，不要額外提交 reference_audio。

五、目前不能統一承諾的限制

關於「目前分組是否支援這組請求」

呼叫分組和素材庫分組是兩個概念，不能僅憑主控台分組名稱判斷是否支援多圖或參考影片。實際判斷順序是：

1. /v1/models 中選定模型存在；
2. 模型詳細明確允許參考圖和參考影片；
3. 引用素材狀態為 Active；
4. 建立介面傳回 queued，說明請求已受理；
5. 若最終 failed，讀取 error.code 和 error.message 判斷組合或素材問題。

平台不會把一個不支援參考影片的模型靜默切換到另一個模型，以免產生不可預期的費用和結果。

六、任務恢復、限流、冪等和計費

查詢和恢復

建立介面傳回 id 後必須立即儲存，網路中斷但已經取得任務 ID 時只查詢原任務。目前公開介面沒有依「提示詞 + 素材 + 參數」反查任務的通用方式；如果連線在建立回應傳回前中斷且沒有任務 ID，平台無法保證僅憑請求內容找回原任務。因此呼叫方應在自己的資料庫裡儲存業務請求，並在收到受理回應後立即寫入任務 ID。

輪詢、限流和保留

平台沒有對所有呼叫分組統一公布並行數和每個 API Key 的查詢頻率，用戶端應遵循 429 回應並使用退避輪詢，建議 5～15 秒查詢一次。成片生成後應盡快下載或轉存，不能把傳回 URL 當作永久位址；如果任務仍可查詢但 metadata.url 已過期，先再次查詢原任務，連結無法恢復時公開介面不保證能重新生成同一個位址。

冪等與用戶端請求號

目前公開影片介面沒有承諾使用者可控制的正規冪等欄位，也不承諾自訂請求號可以依請求內容去重。呼叫方可以用自己的業務請求號記錄關聯，但不要把它當作平台一定會識別的冪等鍵；平台端只有在傳回任務 ID 後才有可靠的恢復依據。

更換 API Key

任務和素材的歸屬以平台帳號為準，同一帳號下更換 Key 後可以繼續查詢原任務，使用建立任務時的 Key 重試查詢即可。如果更換後的 Key 不屬於同一帳號，查詢會傳回 401 或 404，此時不要重新建立任務來規避查詢失敗。

計費、失敗和退款

素材入庫、審核、參考影片下載和影片生成是否計費，取決於目前模型和平台價格設定。影片任務在完成時依實際用量結算，建立成功不會預先扣費，完成後帳單只出現一筆實際扣費記錄；提交前會驗證餘額是否涵蓋預估，不足時直接傳回可讀提示且不建立任務。費用資料只在結算完成後出現在查詢回應裡：

• 建立回應只代表任務已被受理，此時沒有任何結算資料，因此不傳回扣費欄位，不要依建立回應判斷本次費用；
• 查詢回應在任務完成結算後傳回 usage：usage.total_tokens 是本次計費的影片 token 數（上游只上報一個 token 數，依平台帳單規則記在 usage.prompt_tokens，usage.completion_tokens 為 0），usage.quota 是消耗的點數，usage.amount 是同一點數折算的人民幣金額（usage.currency 固定為 CNY）；
• 參數驗證失敗（HTTP 400 / 403）表示請求未被受理，不會產生生成任務費用；
• 已傳回任務 ID 後，是否收費和失敗退款依該模型與平台計費規則處理；
• 審核失敗、生成失敗、取消任務的扣費和退款規則不能僅由任務狀態推斷；
• 需要核對費用時，儲存任務 ID、模型 ID、建立時間和 API Key 所屬帳號，用查詢回應的 usage.quota / usage.amount 在主控台帳單核對，或聯絡平台支援。

七、常見錯誤回應

{
  "error": {
    "code": "invalid_parameter",
    "message": "当前模型不支持参考视频，或参考素材数量超出限制",
    "type": "invalid_request_error",
    "param": "content"
  }
}