API 文件

生成影片

POST /v1/video/generations

送出出片任務。非同步回傳：送出即拿 task_id，出片一般要 1~5 分鐘，實際取決於模型、長度與解析度。路徑與回傳形狀對齊 new-api 的影片通道，可直接掛到中轉閘道上當影片通道用。

請求參數

參數型別說明
promptstring必填。影片描述
modelstring模型 id，取自 /v1/models。不傳用平台預設
modestringtext=文生影片（預設）| image=圖生影片
durationinteger長度秒數。會被夾到所選規格檔的 min_sec ~ max_sec
resolutionstring480p | 720p | 1080p | 4k。傳了 spec 時以規格檔為準
ratiostringadaptive | landscape | portrait | 16:9 | 9:16 | 4:3 | 3:4 | 1:1 | 21:9。不傳則依 width/height 推橫豎，都沒有就是 adaptive；傳了這幾個以外的值會直接報錯。所選模型支援其中哪幾個見 /v1/models 的 aspect_ratios
width / heightinteger像素寫法，僅在沒傳 ratio 時用來定橫豎。寬高相等按 adaptive 處理
specstring規格檔位鍵，決定解析度與每秒單價
imagestring首影格位址。mode=image 時使用
image_laststring尾影格位址。與 image 搭配即首尾影格模式
reference_imagesstring[]參考圖位址，用於保持主體一致性
reference_videosstring[]參考影片公開位址；與 reference_video_durations 依索引一一對應
reference_video_durationsnumber[]各參考影片的長度（秒）；必須是可探測的正數
reference_audiosstring[]參考音訊公開位址；與 reference_audio_durations 依索引一一對應
reference_audio_durationsnumber[]各參考音訊的長度（秒）；必須是可探測的正數
mode=image 時，image 與 reference_images 至少要給一個，兩個都空會直接報錯。參考影片與音訊依模型能力開放；所選規格 reference_media_max_sec>0 時，每段相關媒體都必須提交可探測的正數長度，參考影片按秒計價時也必須提交 reference_video_durations。不支援或超限會被明確拒絕。n 大於 1 同樣直接報錯：出片按條計費、按條限並行，請分多次送出。

請求範例

bash
curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "鏡頭緩慢推進，少女回頭微笑",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

回傳範例

json
{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "processing",
  "url": "",
  "format": "",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "鏡頭緩慢推進，少女回頭微笑"
}

status 為 processing 表示已送給算圖方，用回傳的 task_id 去下面的查詢端點輪詢即可。出片失敗時算力會自動退還。

查詢出片任務

GET /v1/video/generations/{task_id} —— 出片任務走這個端點輪詢，不是 /v1/tasks/{id}（那個只服務出圖）。回傳結構與送出時一致，完成後 url 是成片位址、format 是容器格式。

bash
curl https://open.pikpikgo.com/v1/video/generations/2608101915300490318827 \
  -H "Authorization: Bearer $PIKPIK_API_KEY"
json
{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "succeeded",
  "url": "https://cdn.pikpikgo.com/video/2608101915300490318827.mp4",
  "format": "mp4",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "鏡頭緩慢推進，少女回頭微笑"
}
error 在成功時是 null 而不是空字串，判失敗請用 status 或 error !== null。任務只能被建立它的那個帳號查詢，查別人的與查不存在的回傳完全一樣的 404。