Almacenar y servir medios generados con IA: del render a la CDN

Generar los archivos es la mitad que todo el mundo planifica. La mitad que te tiende una emboscada es lo que pasa en los noventa segundos siguientes: si recibiste bytes o un enlace, cuánto vive ese enlace, adónde va el archivo y quién paga por servírselo a cien mil personas un viernes por la noche.

Esto es lo que devuelve la API de eroq para cada tipo de medio, la diferencia entre la biblioteca de creaciones gratuita y el Store de pago, y la lista corta de cosas que deberías conservar de tu lado pase lo que pase.

Lo que la API te entrega de verdad

Tres endpoints, tres respuestas distintas.

Imágenes: POST /v1/images/generations devuelve la imagen en línea como base64 en b64_json por defecto, o una URL cuando el motor responde con una. Puedes pedir la forma URL con response_format. Detalles en /docs/images.

{
  "created": 1756118400,
  "model": "eroq-image-one",
  "data": [{ "b64_json": "UklGRl4jAABXRUJQ…" }],
  "usage": { "credits_spent": 10, "credits_remaining": 987 }
}

Video: asíncrono. Envías el trabajo, consultas su estado y el trabajo terminado trae el clip en línea como MP4 en base64. Ese payload se conserva durante 24 horas. Después, el trabajo es un registro, no un archivo. Consulta /docs/video.

Voz: POST /v1/audio/speech no devuelve JSON en absoluto. El cuerpo de la respuesta es el MP3, audio/mpeg, listo para volcarlo en un archivo o en un elemento de audio. En /docs/speech tienes los parámetros de voz.

La frase que debes llevarte de esta sección: nada de esto es una URL permanente a menos que la pidas. Un payload en base64 es un mecanismo de entrega, no un almacenamiento, y una ventana de 24 horas es un margen para que tu pipeline actúe, no una política de retención sobre la que puedas construir un producto.

La biblioteca de creaciones: gratis, y no es tu capa de almacenamiento

Cada imagen, video y render de voz hecho con /v1 también se guarda automáticamente en tu biblioteca de creaciones, sin cargo, con la receta completa en meta: modelo, ajustes del panel de dirección, segundos, referencias, todo lo necesario para reproducirlo. Cada elemento generado lleva un library_id.

curl https://eroq.ai/v1/creations \
  -H "Authorization: Bearer $EROQ_API_KEY"

{
  "folders": [{ "id": "…", "name": "Campaign A" }],
  "creations": [{
    "id": "…", "kind": "video", "url": "https://…", "model": "eroq-motion-one",
    "prompt": "slow pan over the rooftop", "meta": { "seconds": 10, "shot": "push-in" }
  }]
}

GET /v1/creations/{id} obtiene una creación con su receta completa, PATCH la mueve entre carpetas, DELETE la elimina junto con su archivo, y hay un CRUD equivalente para las carpetas. Es la misma biblioteca que muestra el estudio, lo que significa que tu equipo ve los renders que hizo tu backend y tu backend ve los renders que hizo tu equipo.

Úsala como registro de recetas y espacio de trabajo compartido, no como la CDN de tu producto. Es la respuesta a «¿qué enviamos exactamente para obtener esto?», una pregunta que te harás más a menudo de lo que crees, normalmente la semana después de que un cliente apruebe un estilo y necesites cuarenta más como ese.

El eroq Store: URLs duraderas en una CDN

Cuando quieras un enlace que sobreviva a la solicitud, sube el archivo:

curl -X POST https://eroq.ai/v1/storage/objects \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F [email protected] \
  -F name="poster.webp"

{
  "id": "0b52…",
  "object": "storage.object",
  "url": "https://store.eroq.ai/acc_…/8c1f2-poster.webp",
  "bytes": 482133,
  "content_type": "image/webp",
  "usage": { "credits_spent": 2, "credits_remaining": 880 }
}

La URL funciona al instante y se sirve a través de una CDN global. Cada objeto puede pesar hasta 100 MB, GET /v1/storage/objects lista tus objetos activos con sus URLs y DELETE /v1/storage/objects/{id} elimina uno: al instante en el origen, mientras las cachés del edge se vacían en cuestión de minutos.

El precio es un pago único de 2 créditos por cada bloque de 10 MB iniciado. «Iniciado» es la palabra clave: una imagen de 1024×1024 es un bloque, así que 2 créditos. Un clip de 4 MB es un bloque. Un clip de 11 MB son dos, así que 4 créditos. El cargo se hace una sola vez, al subir; después, el almacenamiento dura lo mismo que la cuenta, con la entrega incluida dentro de un uso razonable. Eliminar no lo reembolsa, porque el almacenamiento ya se consumió.

También hay un atajo en una sola llamada. Los dos endpoints de generación aceptan store: true, que guarda el render y responde con una URL de CDN duradera en lugar de base64, con la tarifa del Store cobrada aparte y desglosada por separado en tu registro de uso:

curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eroq-motion-one",
    "prompt": "Rain crawls down a diner window while a waitress refills a cup without looking up, street neon bleeding through the glass. Static shot, 35mm film, practicals, neon noir palette, calm tempo.",
    "seconds": 5,
    "aspect": "9:16",
    "store": true
  }'

Para un pipeline que siempre conserva lo que genera, esto es un solo viaje de ida y vuelta en lugar de dos, y elimina la ventana en la que un render solo existe en memoria.

Por qué el alojamiento sigue la misma política que la generación

La generación y el alojamiento suelen venir de dos proveedores, con dos políticas de uso aceptable, dos facturas y dos juegos de claves, y la costura entre ambos es donde los renders se pierden o se juzgan por segunda vez con reglas escritas para el producto de otro.

El Store cierra esa costura: es almacenamiento de objetos y una CDN integrados en la generación, regidos por la misma política escrita de uso aceptable que los propios modelos. Lo que la API genera para ti dentro de la política, el Store lo aloja. Esa es la verdadera razón de que exista; la CDN es lo mínimo que se le pide.

Además, es privado por defecto. Los renders llegan a tu biblioteca de creaciones, privados para tu espacio de trabajo hasta que los publicas, y el modo privado (un interruptor en el estudio, o private: true en los endpoints de imagen y video) se salta incluso eso: ni archivo, ni entrada en la biblioteca, y el prompt sustituido por asteriscos en el registro de uso. Si estás eligiendo infraestructura para un producto sin censura, los pros y contras están en la guía de la API de IA sin censura.

Qué conservar de tu lado

Elijas lo que elijas para los bytes, guarda esto en tu propia base de datos. Todo es barato de almacenar y caro de reconstruir.

• El payload completo de la solicitud. Prompt, modelo, segundos, formato, cada parámetro del panel. La biblioteca también guarda la receta, pero la tuya es la que sobrevive si cambias de proveedor.
• El id del trabajo y el cliente al que pertenecía. Con un saldo compartido, llevar el costo por cliente es cosa tuya, y es un cruce de datos que no puedes hacer a posteriori.
• usage.credits_spent, por render. Cópialo de la respuesta. Reconstruir el gasto más tarde a partir de una lista de precios es como empiezan las disputas de facturación.
• La semilla, en los motores que la respetan: es la diferencia entre «podemos hacer otra toma como esa» y «tuvimos suerte una vez». Más en /glossary/seed; los indicadores de capacidad de cada motor están en /models.
• Una copia de los bytes, si el archivo es un entregable que le debes a alguien. No porque una URL concreta vaya a romperse, sino porque un archivo por el que pagó un cliente no debería tener un único hogar.

Servirlo sin pagar dos veces

Apunta tus etiquetas <img> y <video> directamente a la URL de la CDN. No hagas pasar los archivos por tu servidor de aplicación como proxy: pagarías el ancho de banda dos veces, añadirías un salto de latencia y convertirías un recurso estático en una solicitud que tu autoescalado tiene que tener en cuenta.

Dos notas prácticas para el video. Ponle a cada clip una imagen de portada (poster), porque un elemento de video sin poster es un rectángulo gris hasta que se decodifica el primer fotograma, y en un feed eso parece una página rota. Y fija la URL duradera en el momento en que llega el render: tu manejador de webhooks o tu bucle de consulta es el lugar adecuado para copiar o guardar, no una tarea nocturna que se ejecuta cuando la ventana de 24 horas ya se cerró.

Preguntas frecuentes

¿Cuánto tiempo guarda eroq un video generado?

El clip terminado está disponible en línea en el trabajo durante 24 horas. Si necesitas una URL duradera, guárdalo antes, ya sea con store: true en la llamada de generación o subiéndolo después al eroq Store.

¿Cuánto cuesta alojar archivos en el eroq Store?

Un pago único de 2 créditos por cada bloque de 10 MB iniciado, que se cobra al subir. Una imagen típica de 1024×1024 es un bloque; un clip de 11 MB son dos. La entrega por CDN está incluida dentro de un uso razonable, y eliminar un objeto no reembolsa la subida.

¿La biblioteca de creaciones es lo mismo que el Store?

No. La biblioteca guarda cada render automáticamente y gratis con su receta completa, y está pensada para recuperar y remezclar. El Store es un alojamiento de objetos duradero y de pago, con URLs de CDN que puedes poner delante de tus usuarios.

Lee los endpoints de almacenamiento y medios en /docs y decide adónde va cada render antes de renderizarlo.