¿Cómo descargo imágenes vía API?

Aclaración importante: La API no permite "descargar" en el sentido tradicional. En su lugar, proporciona URLs permanentes a contenido optimizado para web que tu aplicación sirve a los usuarios finales. Esto está regido por nuestro Acuerdo de Licencia API.

NO descargas archivos

La API de Cathopic funciona fundamentalmente diferente de las descargas tradicionales:

• Sin transferencias de archivos: Nunca recibes o almacenas los archivos de imagen/video reales

• Acceso basado en URL: La API proporciona URLs que apuntan a contenido alojado por Cathopic

• Solo optimizado para web: El contenido se sirve en resolución adecuada para visualización digital

• Sin archivos originales: Los originales de alta resolución nunca son accesibles vía API

• Siempre alojado: El contenido permanece en servidores de Cathopic o CDN autorizado

Resoluciones disponibles

La API proporciona tres tamaños optimizados para web:

• Pequeña: Adecuada para miniaturas y embebidos pequeños (típicamente ~400px de ancho)

• Mediana: Buena para contenido web estándar (típicamente ~800px de ancho)

• Grande: Mejor calidad para visualización web (típicamente ~1200px de ancho)

Restricciones críticas:

• Los archivos originales de alta resolución NUNCA se proporcionan

• Las resoluciones están optimizadas para visualización en pantalla, no impresión

• Los tamaños de archivo están comprimidos para entrega web rápida

• No puedes solicitar resoluciones personalizadas o calidad original

Para términos completos, lee el Acuerdo de Licencia API completo y revisa la documentación técnica en api.cathopic.com/docs.

Descargar imágenes involucra dos pasos: licenciar el recurso con /confirm, luego usar las URLs devueltas.

Paso 1: Licenciar el recurso

Llama a /confirm para licenciar un recurso para un usuario final específico:

POST https://api.cathopic.com/confirm
x-api-key: TU_CLAVE_API
{
  "media_id": 1234,
  "usage_type": "website",
  "client_identifier": "user_123"
}

Parámetros:

• media_id - El ID del recurso de tus resultados de búsqueda

• usage_type - "website" o "email"

• client_identifier - ID único para tu usuario final

Paso 2: Usar las URLs de descarga

La respuesta contiene URLs permanentes en múltiples formatos:

{
  "download_url": {
    "avif": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    },
    "jpeg": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    }
  }
}

Importante: Almacena las URLs

Las URLs devueltas son permanentes - almacénalas en tu base de datos:

// Después de llamar a /confirm
const response = await api.confirm(mediaId, userId);
// Guardar en tu base de datos
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// La próxima vez, recuperar de la BD en lugar de llamar a /confirm de nuevo

Elegir el formato correcto

Formato AVIF:

• Archivos más pequeños (mejor rendimiento)

• Mejor compresión

• Recomendado para navegadores modernos

• No soportado en navegadores antiguos

Formato JPEG:

• Compatibilidad universal

• Archivos más grandes

• Usar como fallback para navegadores antiguos

Recordatorio crítico

⚠️ Siempre verifica tu base de datos antes de llamar a /confirm. Llamarlo múltiples veces para el mismo usuario y recurso creará cargos duplicados.

Documentación completa en api.cathopic.com/docs.