Assets und LoRA-Dateien

Dateien in der Asset-Bibliothek ablegen und per URI wiederverwenden, Charaktere lesen und eigene LoRA-Gewichte mitbringen.

Uploads und Task-Ergebnisse sind temporär. Willst du eine Datei in vielen Tasks wiederverwenden – ein Produktfoto, das Gesicht einer Figur, eine Stimmprobe –, speichere sie in deiner Asset-Bibliothek. Nimmt ein Modell eigene Stilgewichte an, bring deine eigene LoRA-Datei mit.

Die Asset-Bibliothek

Ein gespeichertes Asset bekommt eine feste URI, popnow://a/ast_…, die du in jedes passende Medienfeld jedes Modells setzen kannst, solange du das Asset behältst:

{ "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"] } }

Die URI ist ein Verweis, kein Download-Link: Sie funktioniert nur in Generierungsanfragen mit Schlüsseln deines Kontos. Assets bleiben, bis du sie löschst.

Eine Datei speichern

POST /api/v1/assets kopiert eine Datei in die Bibliothek. Wähl eine Quelle; der Header Idempotency-Key ist Pflicht, und dieselbe Quelle erneut zu speichern liefert das vorhandene Asset.

`source`	Zusätzlich senden	Gespeichert wird
`task_output`	`taskId` und `key` oder `index` der Ausgabe	Eine Datei aus einem deiner erfolgreichen Tasks
`upload`	`fileId`	Ein committeter Upload
`url`	`url`	Eine öffentliche `http`/`https`-Datei (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\"}"

Die Antwort ist das Asset: id, uri, name, kind (image, video oder audio), Größe und Abmessungen, das erzeugende model und eine private previewUrl, die etwa 20 Minuten gilt. Speichere die uri, nie den Vorschau-Link.

Auflisten, umbenennen und löschen

Aufruf	Wirkung
`GET /api/v1/assets`	Eine Seite Assets. Filter: `kind`, `source`, `favorite`, `q` (Namenssuche), `collectionId`, `entityId`; Sortierung mit `sort=recent\|oldest\|name\|size`; weiter mit `cursor`
`GET /api/v1/assets/{id}`	Ein Asset mit frischem Vorschau-Link
`PATCH /api/v1/assets/{id}`	`name` und/oder `favorite` ändern
`DELETE /api/v1/assets/{id}`	Löschen; die URI funktioniert in neuen Anfragen nicht mehr
`GET /api/v1/assets/entities`	Deine Charaktere: benannte Bildsätze, auf der Website angeordnet, jedes Bild mit eigener URI
`GET /api/v1/assets/usage`	Dein Speicherplan, deine Nutzung, die Grenzen und was der nächste Plan freischaltet

Speicherpläne

Speicher wird mit deinem ersten Credit-Kauf freigeschaltet und wächst mit dem, was du insgesamt gekauft hast; er schrumpft nie, und gespeicherte Assets bleiben immer nutzbar. GET /api/v1/assets/usage zeigt die Zahlen für dein Konto.

Fehler

Fehler der Asset-Bibliothek ergänzen die übliche Hülle um ein maschinenlesbares data.reason:

`data.reason`	HTTP	Bedeutung
`asset_library_locked`	400	Die Bibliothek öffnet sich nach deinem ersten Credit-Kauf
`asset_library_full`	400	Platz oder Anzahl deines Plans sind ausgeschöpft – Assets löschen oder Plan erhöhen
`asset_file_too_large`	400	Die Datei überschreitet das Dateilimit deines Plans
`asset_daily_limit`	429	Die Tageszahl neuer Assets ist erreicht; warte auf `Retry-After` (00:00 UTC)
`asset_storage_full`	503	Der Speicher ist bei uns vorübergehend voll; versuch es später

Behandle einen unbekannten Grund wie einen fehlenden. Lesen ist auf 60 Anfragen pro Minute begrenzt, Speichern auf 30 pro Minute.

Eigene LoRA mitbringen

Modelle, deren ID auf -lora endet, nehmen ein Array loras an – bis zu drei Gewichtsdateien, jede mit path und scale (0 bis 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 kann ein öffentlicher Direktlink auf eine .safetensors-Datei sein oder eine Datei, die du hochgeladen oder importiert hast:

Hochladen wie jede andere Datei mit contentType: application/octet-stream (eine .safetensors-Datei bis 2 GiB; das Ticket gilt zwei Stunden). Der Commit prüft, ob es eine vollständige safetensors-Datei ist.
Per Link importieren, wenn die Datei eine Anmeldung braucht, etwa in einem privaten Hugging-Face-Repository:

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 akzeptiert eine Hugging-Face-Repo-ID (owner/repo, wenn es genau eine .safetensors-Datei enthält), eine Hugging-Face-Repo- oder Dateiseite oder einen beliebigen HTTPS-Direktlink. token ist optional – ein Hugging-Face-Zugriffstoken oder ein Civitai-API-Key – und wird nur für diesen einen Download genutzt, nie gespeichert. Die Antwort entspricht einem Commit: Setz ihre uri in loras[].path.

Eine LoRA muss zum Basismodell passen, für das sie trainiert wurde; Gewichte für eine andere Basis scheitern meist oder bewirken nichts. Du bist dafür verantwortlich, die mitgebrachten Gewichte nutzen zu dürfen.