Ressources et fichiers LoRA

Conserver des fichiers dans votre bibliothèque et les réutiliser par URI, lire vos personnages, et apporter vos propres poids LoRA.

Les envois et les résultats de tâches sont temporaires. Pour réutiliser un fichier dans de nombreuses tâches — une photo produit, le visage d’un personnage, un échantillon de voix —, enregistrez-le dans votre bibliothèque de ressources. Quand un modèle accepte des poids de style personnalisés, apportez votre propre fichier LoRA.

La bibliothèque de ressources

Une ressource enregistrée reçoit une URI stable, popnow://a/ast_…, que vous pouvez placer dans n’importe quel champ média du bon type, pour n’importe quel modèle, tant que vous la conservez :

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

L’URI est une référence, pas un lien de téléchargement : elle ne fonctionne que dans les requêtes de génération faites avec les clés de votre compte. Les ressources restent jusqu’à ce que vous les supprimiez.

Enregistrer un fichier

POST /api/v1/assets copie un fichier dans la bibliothèque. Choisissez une source ; l’en-tête Idempotency-Key est obligatoire, et enregistrer de nouveau la même source renvoie la ressource existante.

`source`	Envoyez aussi	Enregistre
`task_output`	`taskId` et la `key` ou l’`index` du résultat	Un fichier produit par l’une de vos tâches réussies
`upload`	`fileId`	Un envoi validé
`url`	`url`	Un fichier public en `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\"}"

La réponse est la ressource : id, uri, name, kind (image, video ou audio), taille et dimensions, le model qui l’a générée et une previewUrl privée valable une vingtaine de minutes. Conservez l’uri, jamais le lien d’aperçu.

Lister, renommer et supprimer

Appel	Effet
`GET /api/v1/assets`	Une page de ressources. Filtres `kind`, `source`, `favorite`, `q` (recherche par nom), `collectionId`, `entityId` ; tri avec `sort=recent\|oldest\|name\|size` ; suite avec `cursor`
`GET /api/v1/assets/{id}`	Une ressource avec un nouveau lien d’aperçu
`PATCH /api/v1/assets/{id}`	Modifier `name` et/ou `favorite`
`DELETE /api/v1/assets/{id}`	La supprimer ; son URI cesse de fonctionner dans les nouvelles requêtes
`GET /api/v1/assets/entities`	Vos personnages : des ensembles d’images nommés, organisés sur le site, chaque image avec sa propre URI
`GET /api/v1/assets/usage`	Votre offre de stockage, votre usage, ses limites et ce que débloque l’offre suivante

Offres de stockage

Le stockage s’ouvre avec votre premier achat de crédits et grandit avec ce que vous avez acheté au fil du temps ; il ne diminue jamais, et les ressources enregistrées restent toujours utilisables. GET /api/v1/assets/usage donne les chiffres de votre compte.

Erreurs

Les erreurs de la bibliothèque ajoutent un data.reason lisible par machine à l’enveloppe habituelle :

`data.reason`	HTTP	Signification
`asset_library_locked`	400	La bibliothèque s’ouvre après votre premier achat de crédits
`asset_library_full`	400	L’espace ou le nombre d’éléments de votre offre est atteint — supprimez des ressources ou passez à l’offre supérieure
`asset_file_too_large`	400	Le fichier dépasse la limite par fichier de votre offre
`asset_daily_limit`	429	Le nombre quotidien de nouvelles ressources est atteint ; attendez `Retry-After` (00:00 UTC)
`asset_storage_full`	503	Le stockage est temporairement plein de notre côté ; réessayez plus tard

Traitez une raison inconnue comme une raison absente. La lecture est limitée à 60 requêtes par minute et l’enregistrement à 30.

Apporter votre propre LoRA

Les modèles dont l’identifiant se termine par -lora acceptent un tableau loras — jusqu’à trois fichiers de poids, chacun avec un path et un scale (de 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 peut être un lien direct public vers un fichier .safetensors, ou un fichier que vous avez envoyé ou importé :

Envoyez-le comme n’importe quel fichier avec contentType: application/octet-stream (un fichier .safetensors jusqu’à 2 Gio ; le ticket est valable deux heures). La validation vérifie qu’il s’agit d’un fichier safetensors complet.
Importez-le depuis un lien quand le fichier exige une connexion, par exemple dans un dépôt Hugging Face privé :

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 accepte un identifiant de dépôt Hugging Face (owner/repo, s’il contient exactement un fichier .safetensors), une page de dépôt ou de fichier Hugging Face, ou n’importe quel lien direct HTTPS. token est facultatif — un jeton d’accès Hugging Face ou une clé API Civitai — et ne sert que pour ce téléchargement, sans jamais être stocké. La réponse a la même forme qu’une validation : placez son uri dans loras[].path.

Une LoRA doit correspondre au modèle de base pour lequel elle a été entraînée ; des poids prévus pour une autre base échouent généralement ou restent sans effet. Il vous revient d’avoir le droit d’utiliser les poids que vous apportez.