建立影片任務

影片生成是非同步任務：建立成功只表示任務已受理，需要儲存回應中的 id，再查詢任務讀取進度與結果。一次建立請求對應一個任務，查詢與頁面重新整理不會重複建立或重複計費。

共用約定（基礎位址、驗證、回應結構、限流、冪等）請見驗證與基礎規範。

介面一覽

用途	方法	路徑	詳細文件
建立影片任務	POST	`/v1/video/generations`	本頁
建立影片任務（OpenAI 相容寫法）	POST	`/v1/videos`	本頁
查詢影片任務	GET	`/v1/video/generations/{task_id}`	查詢影片任務
查詢影片任務（OpenAI 相容寫法）	GET	`/v1/videos/{task_id}`	查詢影片任務

兩種寫法的請求內容、回應內容與任務 ID 完全相同，任選一種即可；同一個任務 ID 在兩組路徑下都能查詢。

舊有用戶端繼續使用 /v1/video/generations 即可，平台會在入口層將它視為 /v1/videos 的影片任務外掛處理，不需要變更欄位或路徑。

準備變數

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_API_ORIGIN="https://locopalai.com"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/reference.png"
export LOCOPAL_VIDEO_URL="https://你的对象存储域名/reference.mp4"
export LOCOPAL_AUDIO_URL="https://你的对象存储域名/reference.mp3"
export LOCOPAL_TASK_ID="创建视频后响应中的 id"

建立影片任務

POST/v1/video/generations

驗證方式

Authorization: Bearer <API_KEY>，使用於主控台「API 金鑰」建立的平台 API Key。

請求內容 · application/json

Prop

Type

prompt 與 content 至少需提供一種文字輸入：只提交 content 時，平台會將第一個 type: "text" 元素的 text 作為提示詞。缺少 model 時會傳回 HTTP 400，不要向模型傳入詳情頁未宣告支援的參數。

content 元素

`type`	內容欄位	`role`	說明
`text`	`text`	省略	文字提示詞
`image_url`	`image_url.url`	`reference_image`	一般參考圖片，可提交多張
`image_url`	`image_url.url`	`first_frame`	影片首幀
`image_url`	`image_url.url`	`last_frame`	影片尾幀
`video_url`	`video_url.url`	`reference_video`	動作、運鏡、節奏或畫面參考影片
`audio_url`	`audio_url.url`	`reference_audio`	聲音或節奏參考

公開網路素材必須使用可直接下載的 HTTPS URL，不能依賴 Cookie、Referer 或登入頁面；圖片也可以依模型支援情況使用 data:image/...;base64,...。素材庫中狀態為 Active 的素材使用 asset://<asset_id>；真人素材只能提交到支援真人素材庫的模型。

content 陣列中的 image_url、video_url、audio_url 會依原類型傳給上游；duration、ratio、resolution、seed、watermark、generate_audio 等頂層參數也會隨任務提交，不需要額外包裝到 metadata。

如果只需要一張一般參考圖片，也可以使用頂層 image_url 簡寫：

{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "prompt": "镜头缓慢推进",
  "image_url": "https://your-object-storage.example/reference.png",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

平台會將頂層 image_url 轉換為單一參考圖片的內容項目。需要多張圖片、首尾幀、參考影片或參考音訊時，請使用 content 陣列。

請求範例

文字轉影片

content 是一個陣列：文字使用 { "type": "text", "text": "..." }，參考圖片使用 type: "image_url"。純文字生成時只要放一個 text 項目即可。

resolution、ratio、duration 必須落在目前模型支援的級距內。 generate_audio 與 watermark 並非所有模型都接受。

提交成功後只需依傳回的 id / task_id 查詢，不要重新建立任務。

純文字生成影片

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    { "type": "text", "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
JSON

單圖生影片

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/reference.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

首尾幀

首幀與尾幀必須分別標記為 first_frame 與 last_frame，並使用兩份不同的圖片。

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://你的对象存储域名/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://你的对象存储域名/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

多圖與參考影片

業務中常說的「深度影片」在公開介面裡沒有獨立的 deep_video 欄位，而是以參考影片提交：type 使用 video_url，role 使用 reference_video。每張參考圖片各佔一個 content 元素，不能將多個 URL 放進同一個 image_url.url。

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "$LOCOPAL_IMAGE_URL" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://你的素材ID" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/scene.png" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "$LOCOPAL_VIDEO_URL" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 7,
  "generate_audio": false,
  "watermark": false
}
JSON

陣列順序就是素材順序。建議在提示詞中明確寫出「圖片1、圖片2、圖片3、參考影片」，不要依賴伺服器端依檔名猜測順序。參考圖片數量、參考影片、參考音訊、輸出解析度與時長由模型能力決定，詳見多圖與參考影片說明。

多圖、參考音訊與固定種子

seed 可以固定取樣結果；reference_audio 作為聲音或節奏參考；duration、generate_audio、ratio、resolution、watermark 都是頂層參數。以下範例對應客戶常用的 9:16 影片參數：

{
  "model": "doubao-seedance-2.0-D",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物和服装为主体，参考图片2的另一名角色，参考音频的情绪和节奏生成电影感画面，保持角色身份一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917114312-cyele" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917111324-mquys" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://your-object-storage.example/reference.mp3" }
    }
  ],
  "duration": 9,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

建立成功後，回應中的 id / task_id 仍依非同步任務流程查詢；參考音訊必須是平台可存取的 HTTPS 位址，asset:// 素材必須先處於 Active。

回應參數

參數	類型	說明
`id`	string	公開任務 ID，查詢任務時使用
`task_id`	string	與 `id` 相同的相容欄位
`model`	string	本次請求使用的模型 ID
`status`	string	受理成功時為 `queued`
`created_at`	integer	任務建立時間（Unix 秒）
`object`	string	選填；建立回應可能省略，查詢成功後通常為 `video`
`progress`	integer	選填；建立回應可能省略，查詢後會傳回目前進度

回應內容

{
  "created_at": 1789567067,
  "id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu"
}

建立回應並非固定的欄位全集。用戶端應以 id / task_id 是否非空為依據，不要把 object 或 progress 是否存在當成受理成功的必要條件。

收到 HTTP 200 與任務 ID 後，即使本機等待逾時，也只查詢原任務，不要自動重新建立。

錯誤回應

參數驗證未通過時會傳回 HTTP 400，code 為 invalid_request，message 會直接說明缺少或寫錯的內容：

{
  "code": "invalid_request",
  "message": "缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述",
  "data": null
}

餘額或目前 API Key 額度不足以涵蓋本次預估費用時，會傳回 HTTP 403，不會建立任務，也不會產生費用：

{
  "code": "insufficient_user_quota",
  "message": "余额不足：本次预计需要 ＄11.500000，当前可用 ＄0.002000，请充值或调整参数后重试",
  "data": null
}

HTTP	常見原因	處理
`400`	缺少 `model`、JSON 格式錯誤、缺少提示詞、參考素材角色或位址寫錯	依 `message` 修正後重新提交
`401`	API Key 缺少、失效或無權使用	更換為有效的 Key
`403`	餘額或目前 Key 額度不足以涵蓋預估費用（`insufficient_user_quota`）	儲值或調低時長/清晰度等參數後重新提交，此時不會建立任務
`429`	進行中的任務達到並行上限（`task_concurrency_exceeded`）	依提示中的「目前 N 個 / 上限 M」等待既有任務完成後再提交
`429`	目前分組的上游負載已飽和或請求頻率受限	稍後重試，避免並行重複提交
`500`	任務建立失敗	讀取錯誤碼；已有任務 ID 時繼續查詢原任務
`503`	目前模型無法使用	重新查詢 `/v1/models`，切換可用模型或稍後再試

並行與提交節奏

生成任務會在背景並行執行，提交與結果下載都會佔用平台對外頻寬，因此平台對同時在處理中的任務數量設有上限：每個帳號同時最多 2000 個。達到上限後再提交會傳回：

{
  "code": "task_concurrency_exceeded",
  "message": "当前账号有 2000 个生成任务正在处理中，已达到并发上限 2000，请等待任务完成后再提交",
  "data": null
}

建議以下列方式組織批次任務：

先提交一批，待任務進入 completed / failed 終態後再提交下一批，不要用迴圈連續重試同一個請求；
單次提交的參考圖片越多、解析度越高，佔用對外頻寬的時間越久，同時提交的任務數量應相應減少；
需要同時產出多部影片時，請依任務 ID 記錄進度，等待上一批完成後再繼續，避免重複提交導致重複計費。

計費與參數驗證

影片任務完成時依實際用量結算：建立成功只代表任務已受理，提交階段不會預先扣費，也不會產生任何帳單記錄；任務完成後，帳單中只會出現一筆實際扣費記錄。
提交時會驗證帳戶餘額（或目前 API Key 額度）是否足以涵蓋本次預估額度。不足時會傳回 HTTP 403 與 insufficient_user_quota，錯誤訊息會提供「本次預計需要 …，目前可用 …」，補足餘額或調整參數後重新提交即可；此時不會建立任務，也不會產生費用。
提交前會驗證請求內容，缺少內容時會直接傳回可讀的提示，不需要依賴上游錯誤來定位：

提示	原因	處理
`缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述`	沒有文字描述	補上 `prompt`，或在 `content` 中加入一個 `type: "text"` 元素
`content[0].role 不支持 "xxx"，可用值：reference_image、first_frame、last_frame、reference_video、reference_audio`	參考素材角色寫錯	依提示改用允許的角色
`content[0].image_url.url 不能为空`	參考素材位址為空	填入 `asset://<素材ID>`、可公開下載的 HTTPS 位址或 `data:` 內嵌資料
`content[0] 参考素材不可用：地址需要是 https:// 公网地址、asset://<素材ID> 或 data: 内联数据`	素材位址通訊協定不受支援	改為平台素材 ID、HTTPS 直連或 `data:` 內嵌資料，不要使用 `ftp://`、`file://` 或內網位址
`content[0] 参考素材不可用：素材库中找不到素材 xxx`	`asset://` 素材不存在，或不屬於目前帳號	先在素材庫提交並等待狀態變為可用，或核對帳號
`duration 必须大于 0`	時長參數不合法	改為模型支援的時長

本頁目錄