Almacenamiento de medios IA: URL de carga temporales, resultados efímeros y entrega fiable por API

Si desarrollas un producto de imágenes o vídeo con IA sin censura, tres hechos determinan cómo debes diseñar el almacenamiento. Los archivos de referencia cargados duran 1 día. Los medios generados mediante tareas de API, SDK y Playground duran unos 14 días (los medios de cortometrajes de Studio tienen un límite aparte de unos 60 días), y cada enlace de descarga que recibes funciona solo unos 20 minutos. Todos son límites máximos: solo puedes reducirlos, para toda la cuenta o para una solicitud, y puedes destruir el contenido de una tarea terminada cuando lo necesites. Ningún ajuste los amplía.

Por tanto, el patrón fiable es: cargar directamente con un ticket de corta duración, confirmar el archivo, enviar una tarea asíncrona con la referencia privada spicy://, recoger el enlace del resultado al finalizar y copiarlo a un almacenamiento que controles o dejar que caduque deliberadamente. No coloques la carga de un cliente en un bucket público ni guardes una URL de descarga recibida como si fuera permanente.

Cargar una referencia en SpicyAPI es gratis; la tarea de generación que la utiliza se cobra por separado. Renovar el enlace de descarga de un resultado existente no vuelve a ejecutar ni a comprar la generación. Crear un nuevo intento de generación tiene su propio coste de modelo, mientras que el almacenamiento, las solicitudes y la transferencia de una copia en tu bucket siguen los precios de tu proveedor de almacenamiento.

Lee los plazos de conservación aceptados antes de prometer a los clientes un periodo de almacenamiento; la documentación de conservación explica los ajustes. Encontrarás un ejemplo práctico de copia local en cómo convertir medios temporales de IA en recursos duraderos para tu producto.

Pruébalo primero en Playground

1. Abre la página de z-image de texto a imagen, mantente en Workbench, en Form, escribe un Prompt, elige un Aspect ratio y selecciona Run model (inicia sesión primero; esta imagen es una generación normal de pago). Revísala en Preview y guárdala con Download.
2. En Console, abre Logs y busca esa tarea para ver cuánto tiempo se conserva su salida.
3. Abre Data protection y después Retention para ver los cuatro plazos y reducir cualquiera de ellos.
4. Cuando tengas tu propia copia, selecciona Destroy outputs en la tarea terminada para borrar su contenido.

Qué conserva SpicyAPI y durante cuánto tiempo

Reduce los plazos o destruye el contenido tú mismo

1. Plazos de conservación de la cuenta. En Retention, dentro de Data protection en la consola, hay cuatro plazos independientes:

El plazo de los archivos cargados tiene tres límites importantes:

• Delete when the job ends: una carga se elimina cuando todas las tareas que la usan llegan a un estado final, normalmente en un minuto. Una nueva generación con esa referencia borrada requiere otra carga.
• Solo archivos existentes: el interruptor se aplica a los archivos presentes al guardar. Las cargas posteriores conservan actualmente la caducidad estándar de 1 día que aparece en su respuesta de confirmación.
• Opciones de 1 hora y 24 horas: actualmente no cambian nada; la carga sigue siendo utilizable hasta su expiresAt devuelto.

Advertencia antes de reducir cualquier plazo: un ajuste más corto puede afectar a tareas ya ejecutadas. Por ejemplo, establecer Prompt text en 1 o 24 horas borra el texto del prompt y los resultados generados de todas las tareas terminadas hace más de un día, aunque Generated results siga en 14 días. El contenido borrado no se puede recuperar. Descarga primero lo que quieras conservar; ampliar un ajuste solo afecta al futuro.

2. Solicitud por solicitud. Envía la cabecera X-Spicy-Retention (segundos) al crear una tarea; la documentación de conservación muestra la solicitud. El periodo efectivo es el más corto entre la solicitud, el ajuste de tu cuenta y el límite de la plataforma. Lee los plazos aceptados en la tarea en lugar de prometer la duración solicitada.

No uses el borrado inmediato en un producto que prometa entrega o una biblioteca guardada. Puede eliminar el resultado antes de terminar tu copia. Deja un margen de recuperación después de la entrega.

3. Destruir una tarea terminada. Una vez que hayas copiado lo que necesitas, o si un cliente pide el borrado, elimina el contenido creativo de esa tarea.

La consola ofrece la misma acción como Destroy outputs en una tarea de Logs. Se aplican tres reglas:

• Solo tareas terminadas. Purge es idempotente por taskId; no necesita Idempotency-Key. No cancela la generación ni devuelve el cobro, y billingRetained sigue siendo true.
• El borrado se programa. contentState pasa a purged mientras mediaDeletionPending sigue en true hasta que finaliza la limpieza, normalmente en un minuto. Confirma que ha terminado antes de decir al cliente que los bytes ya se han eliminado.
• Una respuesta present no ha eliminado nada. Investiga la respuesta y los ajustes de preservación en lugar de informar que el borrado terminó.

contentState es expired cuando el plazo de conservación elimina el contenido y purged cuando tú lo destruyes. El estado de tarea expired significa algo totalmente distinto: la generación agotó el tiempo y no produjo nada. Reintentar solo ayuda en ese segundo caso.

Enviar archivos de referencia

Una imagen, un vídeo o un archivo de audio de referencia puede llegar a una tarea de tres formas. Una URL HTTPS pública debe devolver el propio archivo: un enlace a una página compartida (unidad en la nube, álbum de fotos o publicación social) devuelve una página web y la tarea falla con invalid_asset, así que descarga el archivo y cárgalo. Una imagen pequeña (hasta 1 MiB) se puede incluir como URI de datos en base64. Todo lo privado o grande debe cargarse mediante SDK, CLI o Playground, que devuelve una referencia privada spicy:// para la tarea.

Límites de carga: JPEG, PNG, WebP y GIF hasta 10 MiB; WAV, MP3, WebM, MP4 y MOV hasta 90 MiB y 600 segundos; un modelo puede admitir menos. Conserva una copia original si necesitarás la entrada después de su plazo de un día. Tu backend solo tiene que autorizar la carga y registrar la propiedad; el cliente puede enviar los bytes directamente. Cargar es gratis; la generación se compra por separado. La documentación de medios describe el flujo.

Resultados: recogerlos y después copiarlos o dejarlos caducar

Un manuscrito y fotogramas de paisajes convergen en una sola escena proyectada.

Envía cada nueva solicitud con su propia clave de idempotencia, conserva el ID de la tarea y recoge el resultado mediante sondeo o callback. Los recursos listos incluyen una url firmada; obtén el archivo sin clave de API y envía un User-Agent como Mozilla/5.0, porque el CDN rechaza el agente predeterminado de urllib de Python con un 403 que no significa que el enlace haya caducado. Una tarea succeeded todavía puede tener un recurso pending, así que sigue comprobando hasta que la URL esté lista. Un enlace caducado se puede renovar dentro del plazo de conservación; la documentación de medios explica cómo.

Conviene gestionar explícitamente tres estados de un recurso:

Un modelo de solo texto no tiene assets, y su texto en output.text se borra con el mismo calendario, así que léelo antes de suponer que existe un archivo.

La excepción de almacenamiento sin cobro se aplica cuando ninguna salida de una tarea pudo almacenarse inicialmente. Un recurso antiguo unavailable por sí solo no demuestra que corresponda un reembolso; comprueba la liquidación de la tarea original.

Los callbacks incluyen tu prompt y los enlaces firmados de los resultados. Tu endpoint, proxy inverso, rastreador de errores y sistema de registros reciben material que SpicyAPI borra según un calendario, así que oculta los cuerpos de los callbacks en los registros de acceso y realiza la copia en un worker. La comprobación de firmas, la deduplicación y los reintentos se explican en la documentación de webhooks.

• Tu producto promete una biblioteca, compartir o editar más tarde: transmite el resultado a un almacenamiento privado que controles en cuanto veas el éxito, registra tu propio ID de recurso y llama a Purge después si quieres eliminar la copia de la plataforma. Transmite los vídeos grandes en vez de cargarlos enteros en memoria y haz que la escritura de destino sea idempotente por tarea y recurso.
• Entrega única: no copies. Muestra el resultado, indica al cliente cuánto durará y deja que el plazo de conservación, o un X-Spicy-Retention corto, lo elimine.

Una referencia cargada por el usuario no es un recurso de marketing, y un resultado correcto no implica consentimiento para publicarlo. Marca algo como «guardado por el cliente» solo cuando hayas confirmado tu propia copia.

Cuando algo falla

Mantener registros útiles sin guardar contenido creativo

Comprueba estas vías de copias accidentales:

• Informes de errores y registros de acceso: oculta prompts, tickets y enlaces firmados; evita registrar los cuerpos de las rutas de medios.
• Analítica y colas: usa ID opacos de operación, tarea y recurso en lugar de URL o nombres de archivo, incluso en el almacenamiento de mensajes no entregables.
• Exportaciones de soporte y entrega pública: comprueba capturas, metadatos de página y correos. Dirige a los clientes a una página autenticada que emita un enlace nuevo tras comprobar el acceso.
• Tu almacenamiento y tus copias de seguridad: aplica tu propia política de borrado. Un enlace caducado no puede revocar un archivo que alguien ya descargó.

Qué no pueden prometer los ajustes de conservación

• El modelo ve el prompt. El modelo que ejecuta la solicitud lo recibe en texto claro, así que los ajustes de SpicyAPI solo controlan cuánto tiempo guarda algo la propia SpicyAPI. No envíes material que no sea necesario.
• Purge es una solicitud de borrado asíncrona. Confirma el estado del contenido devuelto y que terminó el borrado de medios. La limpieza por ciclo de vida del almacenamiento y la rotación de copias tienen plazos independientes; tus propias copias de archivos y de seguridad también necesitan su propia operación de borrado. Los registros de facturación permanecen en cualquier caso.

Si necesitas otro periodo de conservación por contrato, plantéalo antes de firmar en lugar de deducirlo de una página de documentación.

Preguntas frecuentes

¿Puedo usar una URL de carga temporal como URL de imagen en una solicitud de generación?

No. La URL de carga solo autoriza la escritura directa. Carga, confirma y coloca la URI spicy:// confirmada en un campo que el esquema vigente del modelo identifique como campo de carga.

¿Puedo conservar un vídeo generado en SpicyAPI más de 14 días?

Para resultados de API, SDK y Playground, no: el límite es de unos 14 días. Los medios de cortometrajes de Studio tienen un límite aparte de unos 60 días. Copia el archivo a tu propio almacenamiento tras el éxito para acceder durante más tiempo.

¿Purge reembolsa la tarea?

No. Purge solo elimina contenido; el cobro y el registro de la tarea permanecen.

¿Puede un webhook sustituir por completo al sondeo?

Puede ser la vía principal, con una comprobación de conciliación acotada para entregas perdidas. Usa el request_id de la entrega y el ID de la tarea como claves del gestor.

¿Puedo incluir el enlace de un resultado en un correo?

Evítalo. Los correos se reenvían y archivan mucho después de que caduque un enlace breve. Dirige a los clientes a una página autenticada que compruebe el acceso y emita un enlace nuevo.

¿Qué debe ocurrir cuando un cliente borra un resultado guardado?

Borra o revoca tu propia copia y su vía de entrega, y conserva constancia de ello. La copia de la plataforma sigue su propio calendario; usa Destroy outputs si debe desaparecer antes.

Comprobar una tarea existente mediante código

Instala spicyapi, establece SPICY_API_KEY y TASK_ID y ejecuta esta comprobación de solo lectura. No crea una generación ni borra contenido.

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 referencia de conservación describe los ajustes de solicitud y el contrato de borrado.

Deja que un Agent gestione la llamada

Delega una comprobación de almacenamiento si ya tienes un ID de tarea; no hace falta una nueva generación.

• CLI: npx @spicyapi/cli tasks get "$TASK_ID" lee los plazos actuales. Consulta la guía de CLI.
• MCP: pide a spicyapi_task_get que inspeccione esa tarea. Usa spicyapi_task_purge solo tras aprobar expresamente la destrucción de su contenido; la guía de MCP explica la confirmación.
• Skill: después de npx skills add spicyapi-ai/spicy-skill, pide a $spicyapi que examine la conservación de la tarea y explique qué caducará. Consulta la guía de Skill.