# 影片任務

提交生成任務，查詢進度，再取得影片結果。

## 選擇端點

以下適用於支援統一影片介面的模型。其他模型可能要求供應商原生端點，請以模型詳情為準，不要通用同一份請求體。

## 1. 提交任務

設定 `XINGSUAN_MODEL` 為支援該端點及 5 秒文字生成影片的模型。時長只是示範，不代表全部模型都接受。



```bash
curl 'https://api.xsopc.com/v1/videos' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "prompt": "A slow camera move through a sunlit forest",
  "seconds": "5"
}
JSON
```



保存回傳的任務 ID。提交成功代表已受理，不代表生成已完成。

## 2. 查詢進度

替換 `YOUR_TASK_ID`，使用同帳戶的有效金鑰查詢。



```bash
curl 'https://api.xsopc.com/v1/videos/YOUR_TASK_ID' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY"
```



建議從 3～5 秒間隔開始輪詢，長任務再拉長間隔。排隊、處理中、成功及失敗的名稱與結構依端點而異。

也可使用下列通用任務查詢。其 JSON 與原生影片查詢不同，不要直接共用解析器。



```bash
curl 'https://api.xsopc.com/v1/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY"
```



## 3. 取得結果

成功且支援此下載端點時可使用下列指令，否則依任務回傳的結果或素材取得。



```bash
curl --fail --location \
  'https://api.xsopc.com/v1/videos/YOUR_TASK_ID/content' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  --output result.mp4
```



連結可能過期，請及時下載並保留所需授權。不要公開帶有存取憑據的 URL。

## 參考圖片與影片

支援本地首幀圖片的統一影片模型可使用此 multipart 範例，須先確認時長及上傳支援。



```bash
curl 'https://api.xsopc.com/v1/videos' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -F "model=$XINGSUAN_MODEL" \
  -F 'prompt=A slow camera move, preserve the main subject' \
  -F 'seconds=5' \
  -F 'input_reference=@reference.png'
```



多圖、首尾幀與參考影片的欄位各異。僅接受 URL 的上游需有效連結，或已設定的物件儲存與適配，參見[檔案與參考素材](/zh-TW/files/)。

## 避免重複任務

查詢不會重新生成。提交逾時先查任務紀錄，不要反覆提交。時長、解析度、參考素材與模式可能影響費用。