メディア｜PopNow API ドキュメント

参照用の画像・動画・音声を URL、インライン、アップロードで送る方法と、タスクが作ったファイルのダウンロード。

多くのモデルはファイルを入力に取ります。動かしたい写真、延長したいクリップ、声のサンプル、曲などです。渡し方は 4 通り、結果の受け取り方は 1 通りです。

ファイルを送る 4 つの方法

手元にあるもの	送り方	向いている用途
公開 HTTPS リンク	URL をそのまま。例：`"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_…"`	多くのタスクで使い回すファイル。アセットを参照

どの方法でも、ファイルはモデルのスキーマがそのために宣言しているフィールド（image_url、image_urls、video_url、audio_url …）に入れます。

公開リンク

リンクはファイルそのものを返し、タスクの実行中はログインなしで取得できる必要があります。クラウドストレージや SNS の共有ページはファイルではなく Web ページを返すため、タスクは invalid_asset で失敗します。その場合はファイルをダウンロードしてアップロードしてください。

画像は MIME タイプ付きの標準的な Base64 data URI で送れます。JPEG、PNG、WebP、GIF で、1 枚あたりデコード後 1 MiB まで・1 辺 8,192 ピクセルまで、1 リクエスト 16 枚まで、JSON 本文全体で 2 MiB 未満です。プレフィックスのない Base64、SVG、動画や音声のインラインは受け付けません。インライン画像はアカウントのアップロードとして保存されるため、タスクの input にはバイト列ではなく popnow:// URI が表示されます。

ファイルをアップロードする

アップロードは 3 回の呼び出しです。アップロード用チケットを取得し、バイト列を 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	—

モデルによってはこれより小さい上限があり、スキーマのフィールドごとに書かれています。アップロードしたファイルは一時的なもので、コミットのレスポンスの 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 の時刻まで、またはタスクを削除するまで保存されます。それ以降も必要なものは、自分のストレージかアセットライブラリにコピーしてください。

メディア

このページの内容