Médias

Envoyer des images, vidéos et audios de référence par URL, en ligne ou par envoi de fichier, et télécharger les fichiers produits par une tâche.

Beaucoup de modèles prennent des fichiers en entrée : une photo à animer, un clip à prolonger, un échantillon de voix, une chanson. Il existe quatre façons d’en fournir un, et une seule pour récupérer les résultats.

Quatre façons d’envoyer un fichier

Vous avez	Envoyez-le sous forme de	Idéal pour
Un lien HTTPS public	L’URL elle-même, par ex. `"image_url": "https://…/photo.jpg"`	Les fichiers que vous hébergez déjà
Une petite image en mémoire	Une data URI, par ex. `"image_url": "data:image/png;base64,…"`	Les tests rapides, les images de moins de 1 Mio
Un fichier local	Un envoi, puis `"image_url": "popnow://f/fil_…"`	Tout le reste, vidéo et audio compris
Un fichier de votre bibliothèque	`"image_url": "popnow://a/ast_…"`	Les fichiers réutilisés dans de nombreuses tâches. Voir Ressources

Quelle que soit la méthode, le fichier va dans le champ que le schéma du modèle prévoit pour lui (image_url, image_urls, video_url, audio_url…).

Liens publics

Le lien doit renvoyer le fichier lui-même et rester accessible sans connexion pendant toute la tâche. Une page de partage d’un service de stockage ou d’un réseau social renvoie une page web, pas le fichier, et la tâche échoue avec invalid_asset ; téléchargez alors le fichier et envoyez-le.

Images en ligne

Les images peuvent être envoyées en data URI Base64 standard avec leur type MIME : JPEG, PNG, WebP ou GIF, 1 Mio décodé et 8 192 pixels par côté au maximum chacune, jusqu’à 16 images par requête, et l’ensemble du corps JSON sous 2 Mio. Le Base64 sans préfixe, le SVG et la vidéo ou l’audio en ligne ne sont pas acceptés. Les images en ligne sont stockées comme des envois de votre compte : l’input de la tâche affiche donc une URI popnow:// au lieu de renvoyer les octets.

Envoyer un fichier

L’envoi se fait en trois appels : demander un ticket, faire un PUT des octets, puis valider.

Demander un ticket

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)

La réponse contient fileId, uploadUrl, les headers exacts à envoyer, expiresAt (dans une vingtaine de minutes) et maxBytes. Pas de nom de fichier : les chemins de stockage sont toujours choisis par le serveur.

Faire un PUT des octets

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"

Envoyez chaque en-tête du ticket exactement tel quel — tous font partie de la signature — et pas d’en-tête Authorization. Dans un navigateur, omettez Content-Length et envoyez un File ou un Blob de la taille exacte déclarée ; le navigateur le définit pour vous.

Valider

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

La validation vérifie la taille, le type et la signature du fichier, puis renvoie l’URI à utiliser :

{
  "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_…"
}

Placez uri dans le champ du modèle, par exemple "image_url": "popnow://f/fil_…". Une URI popnow:// ne fonctionne qu’avec les clés de votre propre compte. Valider deux fois est sans risque.

Limites d’envoi

Type	`contentType`	Taille maximale	Durée maximale
Image	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 Mio	—
Vidéo	`video/mp4`, `video/webm`	90 Mio	600 secondes
Audio	`audio/mpeg`, `audio/wav`	90 Mio	600 secondes
Poids LoRA	`application/octet-stream` (un fichier `.safetensors`)	2 Gio	—

Un modèle peut accepter moins ; son schéma le précise champ par champ. Les fichiers envoyés sont temporaires — l’expiresAt de la réponse de validation indique quand le fichier est supprimé —, alors envoyez-les peu avant de créer la tâche. Pour réutiliser un fichier, enregistrez-le dans votre bibliothèque de ressources.

Si une validation répond 40003, les octets envoyés ne correspondent pas au ticket (taille, type ou contenu différents). Demandez un nouveau ticket et renvoyez le fichier.

Télécharger les résultats

Une tâche terminée liste ses fichiers dans output.assets, chacun avec une url prête à l’emploi :

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')"

Le lien est signé et fonctionne une vingtaine de minutes (expiresAt). Ne le stockez pas ; stockez le taskId et relisez la tâche pour obtenir un nouveau lien.
N’ajoutez pas votre clé API au téléchargement. Le lien est lui-même l’autorisation : quiconque le détient peut télécharger le fichier jusqu’à son expiration.
Pour créer un lien sans relire toute la tâche, appelez POST /api/v1/common/download-url avec { "taskId": "…" } (et éventuellement la key du fichier).

Les fichiers eux-mêmes sont conservés jusqu’à l’heure indiquée dans retention.outputsExpireAt, ou jusqu’à ce que vous purgiez la tâche. Copiez tout ce dont vous aurez besoin au-delà dans votre propre stockage ou dans votre bibliothèque de ressources.

Médias

Sur cette page