アセットと LoRA ファイル

ファイルをアセットライブラリに保存して URI で使い回す方法、キャラクターの読み取り、自前の LoRA 重みの持ち込み。

アップロードしたファイルやタスクの結果は一時的なものです。商品写真、キャラクターの顔、声のサンプルなど、多くのタスクで同じファイルを使い回したいときはアセットライブラリに保存しましょう。カスタムのスタイル重みを受け付けるモデルには、自前の LoRA ファイルを持ち込めます。

アセットライブラリ

保存したアセットには popnow://a/ast_… という固定の URI が付きます。アセットを残している限り、どのモデルでも対応する種類のメディアフィールドに入れられます。

{ "model": "google/nano-banana-2.1/edit",
  "input": { "prompt": "Put this mug on a wooden café table, morning light",
             "image_urls": ["popnow://a/ast_01k3m8x9q2z4v7n5p6r8s0t1w3"] } }

この URI は参照であってダウンロードリンクではありません。使えるのは、自分のアカウントのキーで送る生成リクエストの中だけです。アセットは削除するまで残ります。

ファイルを保存する

POST /api/v1/assets でファイルをライブラリにコピーします。取得元を 1 つ選び、Idempotency-Key ヘッダーは必須です。同じ取得元をもう一度保存すると、既存のアセットが返ります。

`source`	あわせて送るもの	保存されるもの
`task_output`	`taskId` と、出力の `key` または `index`	成功した自分のタスクが作ったファイル
`upload`	`fileId`	コミット済みのアップロード
`url`	`url`	公開された `http`/`https` のファイル（JPEG、PNG、WebP、GIF、MP4、WebM、MP3、WAV、FLAC、Ogg）

curl -X POST "https://api.popnow.ai/api/v1/assets" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: save-$TASK_ID-0" \
  -d "{\"source\": \"task_output\", \"taskId\": \"$TASK_ID\", \"index\": 0, \"name\": \"Hero shot\"}"

レスポンスはアセットそのものです。id、uri、name、kind（image、video、audio）、サイズと寸法、生成した model、約 20 分有効な非公開の previewUrl が入っています。保存するのは uri で、プレビューのリンクではありません。

一覧・名前変更・削除

呼び出し	内容
`GET /api/v1/assets`	アセットを 1 ページ分。`kind`、`source`、`favorite`、`q`（名前検索）、`collectionId`、`entityId` で絞り込み、`sort=recent\|oldest\|name\|size` で並べ替え、`cursor` で続きを取得
`GET /api/v1/assets/{id}`	1 件のアセットと新しいプレビューのリンク
`PATCH /api/v1/assets/{id}`	`name` や `favorite` を変更
`DELETE /api/v1/assets/{id}`	削除。以後の新しいリクエストでは URI が使えなくなります
`GET /api/v1/assets/entities`	キャラクター。Web サイトで並べた名前付きの画像セットで、画像ごとに URI があります
`GET /api/v1/assets/usage`	保存プラン、使用量、上限、次のプランで増える分

保存プラン

ストレージは最初のクレジット購入で使えるようになり、これまでの購入額に応じて増えていきます。減ることはなく、保存したアセットはいつでも使えます。実際の数値は GET /api/v1/assets/usage で確認できます。

エラー

アセットライブラリのエラーには、通常の外枠に機械可読な data.reason が加わります。

`data.reason`	HTTP	意味
`asset_library_locked`	400	ライブラリは最初のクレジット購入後に開きます
`asset_library_full`	400	プランの容量か件数を使い切った。アセットを削除するかプランを上げる
`asset_file_too_large`	400	ファイルがプランの 1 ファイル上限を超えている
`asset_daily_limit`	429	今日の新規アセット数が上限に達した。`Retry-After`（UTC 00:00）まで待つ
`asset_storage_full`	503	こちらのストレージが一時的にいっぱい。あとで再試行

知らない reason は、reason がないものとして扱ってください。ライブラリの読み取りは 1 分 60 回、保存は 1 分 30 回までです。

自前の LoRA を使う

ID が -lora で終わるモデルは loras 配列を受け付けます。重みファイルは 3 つまでで、それぞれ path と scale（0〜4）を持ちます。

{ "model": "alibaba/qwen-image-2.1-lora/text-to-image",
  "input": { "prompt": "A cozy reading nook in watercolor style",
             "loras": [{ "path": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3", "scale": 1 }] } }

path には .safetensors ファイルの公開直リンクか、アップロード・インポートしたファイルを指定します。

アップロード：ほかのファイルと同じく contentType: application/octet-stream でアップロードします（.safetensors ファイル、最大 2 GiB。チケットは 2 時間有効）。コミット時に完全な safetensors ファイルかを確認します。
リンクからインポート：非公開の Hugging Face リポジトリなど、ダウンロードにサインインが必要なファイル向けです。

curl -X POST "https://api.popnow.ai/api/v1/files/import" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "your-name/your-lora-repo", "token": "hf_..."}'

url には Hugging Face のリポジトリ ID（owner/repo。.safetensors ファイルがちょうど 1 つの場合）、Hugging Face のリポジトリページやファイルページ、任意の HTTPS 直リンクを指定できます。token は任意で、Hugging Face のアクセストークンか Civitai の API キーです。このダウンロード 1 回だけに使い、保存はしません。レスポンスはコミットと同じ形なので、uri を loras[].path に入れてください。

LoRA は学習元のベースモデルと合っている必要があります。別のベース用の重みはたいてい失敗するか、効果がありません。持ち込む重みを使う権利があることは、ご自身で確認してください。