上傳與下載

以連結、內嵌或上傳的方式傳送參考圖片、影片與音訊，以及下載任務產生的檔案。

許多模型需要檔案作為輸入——要動起來的照片、要延長的片段、聲音樣本、一首歌。交給模型的方式有四種，取回結果的方式只有一種。

傳送檔案的四種方式

你手上有	這樣傳	適合
一個公開的 HTTPS 連結	直接傳連結，例如 `"image_url": "https://…/photo.jpg"`	已經架設好的檔案
記憶體中的一張小圖	傳 data URI，例如 `"image_url": "data:image/png;base64,…"`	快速測試、1 MiB 以內的圖片
一個本機檔案	先上傳，再傳 `"image_url": "popnow://f/fil_…"`	其他所有情況，包括影片與音訊
素材庫裡的檔案	傳 `"image_url": "popnow://a/ast_…"`	會在許多任務中重複使用的檔案。請見素材庫

不論哪種方式，檔案都要放進模型 schema 為它宣告的欄位（image_url、image_urls、video_url、audio_url …）。

公開連結

連結必須直接回傳檔案本身，且在任務執行期間不必登入就能存取。雲端硬碟或社群網站的分享頁回傳的是網頁而不是檔案，任務會以 invalid_asset 失敗；這時請先下載檔案再上傳。

圖片可以用附 MIME 類型的標準 Base64 data URI 傳送：JPEG、PNG、WebP 或 GIF，每張解碼後不超過 1 MiB、每邊不超過 8,192 像素，每個請求最多 16 張，整個 JSON 請求內容不超過 2 MiB。不支援不帶前綴的 Base64、SVG，以及內嵌的影片或音訊。內嵌圖片會以上傳檔案的形式存進你的帳戶，因此任務的 input 會顯示 popnow:// URI，不會把原始位元組原樣傳回。

上傳檔案

上傳分三步：申請上傳票證、PUT 檔案內容、確認提交。

申請票證

FILE=reference.png
CONTENT_TYPE=image/png
BYTES=$(wc -c < "$FILE" | tr -d ' ')

TICKET=$(curl -s -X POST "https://api.popnow.ai/api/v1/common/upload-url" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\": \"$CONTENT_TYPE\", \"bytes\": $BYTES}")
UPLOAD_URL=$(echo "$TICKET" | jq -r .data.uploadUrl)
FILE_ID=$(echo "$TICKET" | jq -r .data.fileId)

回應中有 fileId、uploadUrl、必須原樣送出的 headers、expiresAt（約 20 分鐘後）與 maxBytes。這裡沒有檔名：儲存路徑一律由伺服器決定。

PUT 檔案內容

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  -H "Content-Length: $BYTES" \
  --data-binary @"$FILE"

票證中的每個標頭都要原樣送出——它們都是簽章的一部分——而且不要帶 Authorization 標頭。在瀏覽器中請省略 Content-Length，送出大小與宣告完全一致的 File 或 Blob，瀏覽器會自動設定。

確認提交

curl -s -X POST "https://api.popnow.ai/api/v1/files/$FILE_ID/commit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

提交時會檢查大小、類型與檔案簽章，並回傳可使用的 URI：

{
  "code": 200,
  "msg": "success",
  "data": {
    "fileId": "fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "status": "ready",
    "uri": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "contentType": "image/png",
    "bytes": 402118,
    "width": 1024,
    "height": 1024,
    "expiresAt": "2026-10-17T09:12:00Z"
  },
  "request_id": "req_…"
}

把 uri 放進模型的欄位，例如 "image_url": "popnow://f/fil_…"。popnow:// URI 只對你自己帳戶的金鑰有效。重複提交是安全的。

上傳限制

類型	`contentType`	單一檔案上限	最長長度
圖片	`image/jpeg`、`image/png`、`image/webp`、`image/gif`	10 MiB	—
影片	`video/mp4`、`video/webm`	90 MiB	600 秒
音訊	`audio/mpeg`、`audio/wav`	90 MiB	600 秒
LoRA 權重	`application/octet-stream`（`.safetensors` 檔案）	2 GiB	—

個別模型可能接受得更少，它的 schema 會逐一欄位註明。上傳的檔案是暫時的——提交回應中的 expiresAt 會告訴你檔案何時刪除——所以請在建立任務前不久再上傳。要重複使用某個檔案，請存進素材庫。

如果提交回傳 40003，表示你送出的內容與票證不符（大小、類型或內容不同）。請申請新票證重新上傳。

下載結果

完成的任務會在 output.assets 列出檔案，每個都附有可直接使用的 url：

curl -L -o result.mp4 "$(curl -s "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY" | jq -r '.data.output.assets[0].url')"

連結經過簽名，大約 20 分鐘內有效（expiresAt）。不要儲存連結；儲存 taskId，需要時重新讀取任務取得新連結。
下載時不要附上 API 金鑰。連結本身就是授權，持有連結的人在過期前都能下載。
想在不讀取整個任務的情況下產生新連結，可以呼叫 POST /api/v1/common/download-url，請求內容為 { "taskId": "…" }（可選擇再加上檔案的 key）。

檔案本身會保留到任務的 retention.outputsExpireAt 指定的時間，或你清除該任務為止。超過這個時間仍需要的檔案，請複製到你自己的儲存空間或素材庫。

上傳與下載

本頁內容