Stockage des médias IA : URL d’envoi temporaires, résultats éphémères et livraison fiable par API

Si vous développez un produit d’images ou de vidéos IA sans censure, trois faits déterminent votre architecture de stockage. Les fichiers de référence téléversés durent 1 jour. Les médias générés par les tâches API, SDK et Playground durent environ 14 jours (les médias de courts métrages Studio ont un plafond distinct d’environ 60 jours), et chaque lien de téléchargement reçu fonctionne seulement environ 20 minutes. Ce sont tous des plafonds : vous pouvez uniquement les raccourcir, pour le compte entier ou pour une requête, et détruire à la demande le contenu d’une tâche terminée. Aucun réglage ne les prolonge.

Le schéma fiable est donc le suivant : téléverser directement avec un ticket de courte durée, valider le fichier, soumettre une tâche asynchrone avec la référence privée spicy://, récupérer le lien du résultat à la fin de la tâche, puis copier le résultat dans un stockage que vous contrôlez ou le laisser expirer volontairement. Ne placez pas un fichier envoyé par un client dans un bucket public et ne conservez pas une URL de téléchargement reçue comme si elle était permanente.

Téléverser une référence vers SpicyAPI est gratuit ; la tâche de génération qui l’utilise est facturée séparément. Renouveler le lien de téléchargement d’un résultat existant ne relance ni ne rachète la génération. Chaque nouvel essai de génération a son propre coût de modèle ; le stockage, les requêtes et le transfert d’une copie dans votre bucket suivent les tarifs de votre fournisseur de stockage.

Lisez les échéances de conservation acceptées avant de promettre une durée de stockage à vos clients ; la documentation sur la conservation explique les réglages. Un exemple pratique de copie locale figure dans transformer des médias IA temporaires en ressources durables pour un produit.

Essayez d’abord dans Playground

1. Ouvrez la page texte vers image de z-image, restez dans Workbench, sur Form, saisissez un Prompt, choisissez un Aspect ratio, puis Run model (connectez-vous d’abord ; cette image est une génération payante normale). Vérifiez-la dans Preview et enregistrez-la avec Download.
2. Dans Console, ouvrez Logs et retrouvez cette tâche pour voir combien de temps sa sortie est conservée.
3. Ouvrez Data protection, puis Retention, pour consulter les quatre durées et les raccourcir.
4. Une fois votre copie obtenue, sélectionnez Destroy outputs sur la tâche terminée pour supprimer son contenu.

Ce que SpicyAPI conserve, et pendant combien de temps

Raccourcissez la conservation ou détruisez le contenu vous-même

1. Durées de conservation du compte. Dans Retention, sur la page Data protection de la console, quatre durées sont distinctes :

La durée des fichiers téléversés présente trois limites importantes :

• Delete when the job ends : un fichier téléversé est supprimé lorsque toutes les tâches qui l’utilisent atteignent un état final, normalement en une minute. Une nouvelle génération avec cette référence supprimée nécessite un nouveau téléversement.
• Fichiers déjà présents uniquement : ce commutateur s’applique aux fichiers présents à l’enregistrement du réglage. Les téléversements ultérieurs gardent actuellement l’expiration standard de 1 jour indiquée dans leur réponse de validation.
• Choix de 1 heure et 24 heures : ils ne changent actuellement rien ; le fichier reste utilisable jusqu’à la valeur expiresAt renvoyée.

Attention avant de raccourcir quoi que ce soit : un réglage plus court peut s’appliquer aux tâches déjà exécutées. Par exemple, régler Prompt text sur 1 ou 24 heures efface le texte du prompt et les résultats générés de toutes les tâches terminées depuis plus d’un jour, même si Generated results reste à 14 jours. Le contenu supprimé ne peut pas être restauré. Téléchargez d’abord ce que vous voulez garder ; prolonger un réglage ne concerne que l’avenir.

2. Une requête à la fois. Envoyez l’en-tête X-Spicy-Retention (en secondes) lors de la création d’une tâche ; la documentation sur la conservation montre la requête. La durée effective est la plus courte entre celle de la requête, le réglage du compte et le plafond de la plateforme. Lisez les échéances acceptées dans la tâche au lieu de promettre la durée demandée.

N’utilisez pas la suppression immédiate pour un produit qui promet une livraison ou une bibliothèque enregistrée. Elle peut supprimer le résultat avant la fin de votre copie. Laissez une marge de récupération après la livraison.

3. Détruire une tâche terminée. Après avoir copié le nécessaire, ou lorsqu’un client demande une suppression, retirez le contenu créatif de cette tâche.

La console propose la même action sous Destroy outputs sur une tâche dans Logs. Trois règles s’appliquent :

• Tâches terminées uniquement. Purge est idempotent par taskId ; aucun Idempotency-Key n’est nécessaire. Il n’annule pas la génération et ne rembourse pas la facturation ; billingRetained reste true.
• La suppression est planifiée. contentState devient purged, tandis que mediaDeletionPending reste true jusqu’à la fin du nettoyage, normalement en une minute. Confirmez la fin avant d’annoncer au client que les octets ont disparu.
• Une réponse present n’a rien supprimé. Examinez la réponse et les réglages de préservation au lieu de signaler une suppression terminée.

contentState vaut expired lorsque la durée de conservation a supprimé le contenu, et purged lorsque vous l’avez détruit. L’état de tâche expired signifie tout autre chose : la génération a dépassé son délai et n’a rien produit. Réessayer n’aide que dans ce second cas.

Envoyer des fichiers de référence

Une image, une vidéo ou un fichier audio de référence peut parvenir à une tâche de trois façons. Une URL HTTPS publique doit renvoyer le fichier lui-même : un lien vers une page de partage (disque cloud, album photo, publication sociale) renvoie une page web et la tâche échoue avec invalid_asset. Téléchargez donc le fichier, puis téléversez-le. Une petite image (jusqu’à 1 MiB) peut être incluse sous forme d’URI de données base64. Tout fichier privé ou volumineux doit être téléversé via le SDK, la CLI ou Playground, qui renvoie une référence privée spicy:// pour la tâche.

Limites de téléversement : JPEG, PNG, WebP et GIF jusqu’à 10 MiB ; WAV, MP3, WebM, MP4 et MOV jusqu’à 90 MiB et 600 secondes, et un modèle peut accepter moins. Gardez un original si vous aurez besoin de l’entrée après sa durée d’un jour. Votre backend doit seulement autoriser le téléversement et enregistrer le propriétaire ; le client peut envoyer les octets directement. Le téléversement est gratuit ; la génération s’achète séparément. La documentation sur les médias décrit le flux.

Résultats : récupérer, puis copier ou laisser expirer

Un manuscrit et des images de paysages convergent vers une seule scène projetée.

Soumettez chaque nouvelle requête avec sa propre clé d’idempotence, gardez l’ID de tâche et récupérez le résultat par interrogation ou rappel. Les ressources prêtes portent une url signée ; récupérez-la sans clé d’API et envoyez un User-Agent tel que Mozilla/5.0, car le CDN refuse l’agent par défaut de Python urllib avec un 403 qui ne signifie pas que le lien a expiré. Une tâche succeeded peut encore contenir une ressource pending ; continuez donc les vérifications jusqu’à ce que l’URL soit prête. Un lien expiré peut être renouvelé pendant la conservation ; la documentation sur les médias explique comment.

Trois états de ressource méritent un traitement explicite :

Un modèle exclusivement textuel n’a aucun assets, et son texte dans output.text est effacé selon le même calendrier ; lisez-le avant de supposer qu’un fichier existe.

L’exception de stockage sans facturation s’applique lorsque aucune sortie d’une tâche n’a pu être stockée initialement. Une ancienne ressource unavailable ne suffit pas à établir un remboursement ; vérifiez le règlement de la tâche d’origine.

Les rappels contiennent votre prompt et les liens signés des résultats. Votre endpoint, proxy inverse, outil de suivi d’erreurs et chaîne de journalisation reçoivent ainsi des éléments que SpicyAPI efface selon un calendrier. Masquez les corps des rappels dans les journaux d’accès et effectuez la copie dans un worker. Vérification des signatures, déduplication et nouvelles tentatives figurent dans la documentation des webhooks.

• Votre produit promet une bibliothèque, le partage ou une retouche ultérieure : transférez le résultat en flux vers un stockage privé que vous contrôlez dès que vous constatez le succès, enregistrez votre propre ID de ressource et appelez ensuite Purge si vous voulez retirer la copie de la plateforme. Transférez une grande vidéo en flux plutôt que de la charger entièrement en mémoire, et rendez l’écriture de destination idempotente pour la paire tâche–ressource.
• Livraison unique : ne copiez pas. Montrez le résultat, indiquez au client combien de temps il reste disponible et laissez la durée de conservation, ou un X-Spicy-Retention court, le supprimer.

Une référence téléversée par un utilisateur n’est pas un support marketing, et un résultat réussi ne vaut pas consentement à le publier. N’indiquez « enregistré par le client » qu’une fois votre propre copie confirmée.

En cas d’échec

Garder des journaux utiles sans garder les contenus créatifs

Vérifiez ces sources de copies accidentelles :

• Rapports d’erreurs et journaux d’accès : masquez prompts, tickets et liens signés ; évitez de journaliser les corps des routes de médias.
• Analyses et files d’attente : utilisez des ID opaques d’opération, de tâche et de ressource plutôt que des URL ou noms de fichiers, y compris dans le stockage des messages non livrables.
• Exports du support et livraison publique : vérifiez captures d’écran, métadonnées de pages et e-mails. Orientez les clients vers une page authentifiée qui émet un nouveau lien après contrôle d’accès.
• Votre stockage et vos sauvegardes : appliquez votre propre politique de suppression. Un lien expiré ne peut pas révoquer un fichier déjà téléchargé.

Ce que les réglages de conservation ne peuvent pas promettre

• Le modèle voit le prompt. Le modèle exécutant la requête le reçoit en clair ; les réglages de SpicyAPI contrôlent uniquement combien de temps SpicyAPI garde elle-même quelque chose. N’envoyez pas de contenu inutile.
• Purge est une demande de suppression asynchrone. Confirmez l’état du contenu renvoyé et la fin de la suppression des médias. Le nettoyage du cycle de vie du stockage et la rotation des sauvegardes ont des durées distinctes ; vos fichiers copiés et sauvegardes nécessitent aussi leurs propres opérations de suppression. Les enregistrements de facturation restent dans tous les cas.

Si vous avez besoin d’une durée différente dans un contrat, évoquez-la avant de signer au lieu de la déduire d’une page de documentation.

Questions fréquentes

Puis-je utiliser une URL de téléversement temporaire comme URL d’image dans une requête de génération ?

Non. L’URL de téléversement autorise uniquement l’écriture directe. Téléversez, validez, puis placez l’URI spicy:// validée dans un champ que le schéma actuel du modèle indique comme champ de téléversement.

Puis-je conserver une vidéo générée sur SpicyAPI plus de 14 jours ?

Pour les résultats API, SDK et Playground, non : leur plafond est d’environ 14 jours. Les médias de courts métrages Studio ont un plafond distinct d’environ 60 jours. Copiez le fichier vers votre stockage après succès pour un accès plus long.

Purge rembourse-t-il la tâche ?

Non. Purge retire uniquement le contenu ; la facturation et l’enregistrement de tâche restent.

Un webhook peut-il remplacer totalement l’interrogation ?

Il peut être la voie principale, avec une vérification de rapprochement limitée pour les livraisons manquées. Indexez votre gestionnaire sur le request_id de livraison et l’ID de tâche.

Puis-je mettre un lien de résultat dans un e-mail ?

Évitez-le. Les e-mails sont transférés et archivés bien après l’expiration d’un lien de courte durée. Orientez les clients vers une page authentifiée qui contrôle l’accès et émet un nouveau lien.

Que doit-il se passer lorsqu’un client supprime un résultat enregistré ?

Supprimez ou révoquez votre copie et son chemin de livraison, et gardez une trace de l’opération. La copie de la plateforme suit son propre calendrier ; utilisez Destroy outputs si elle doit disparaître plus tôt.

Vérifier une tâche existante avec du code

Installez spicyapi, définissez SPICY_API_KEY et TASK_ID, puis exécutez cette vérification en lecture seule. Elle ne crée aucune génération et ne supprime aucun contenu.

import json
import os
from spicyapi import SpicyClient

client = SpicyClient()
task = client.get_task(os.environ["TASK_ID"])
print(json.dumps({"taskId": task["taskId"], "state": task["state"],
    "contentState": task.get("contentState"), "retention": task.get("retention"),
    "mediaDeletionPending": task.get("mediaDeletionPending")}, indent=2))

La référence sur la conservation décrit les réglages des requêtes et le contrat de suppression.

Confier l’appel à un Agent

Déléguez une vérification de stockage si vous avez déjà un ID de tâche ; aucune nouvelle génération n’est nécessaire.

• CLI : npx @spicyapi/cli tasks get "$TASK_ID" lit les échéances actuelles. Consultez le guide CLI.
• MCP : demandez à spicyapi_task_get d’inspecter cette tâche. N’utilisez spicyapi_task_purge qu’après avoir expressément approuvé la destruction de son contenu ; le guide MCP explique la confirmation.
• Skill : après npx skills add spicyapi-ai/spicy-skill, demandez à $spicyapi d’examiner la conservation de la tâche et d’expliquer ce qui expirera. Consultez le guide Skill.