Preguntas Frecuentes

Preguntas frecuentes sobre IPFS Ninja.

General

¿Qué es IPFS Ninja?

IPFS Ninja es un servicio gestionado de fijación en IPFS. Subes cualquier archivo a través de una API REST sencilla, o fijas CIDs existentes de la red IPFS. Cada archivo recibe un identificador de contenido permanente (CID) y es accesible a través de nuestro gateway en ipfs.ninja/ipfs/<CID>.

¿ipfs.ninja/ipfs/<CID> sirve cualquier CID de la red IPFS?

No. El gateway apex solo sirve CIDs que han sido subidos o fijados por un usuario de IPFS Ninja. Las solicitudes para CIDs desconocidos devuelven HTTP 410 Gone con un puntero a gateways IPFS públicos (ipfs.io, dweb.link). Para servir un CID de terceros a través de nuestro gateway, haz primero POST /pin a tu cuenta — una vez fijado, el CID será accesible tanto en la URL apex como en la de tu gateway dedicado.

¿Cuál es la diferencia entre el gateway apex y el gateway dedicado?

Aspecto	Apex ipfs.ninja/ipfs/<CID>	Dedicado <slug>.gw.ipfs.ninja/ipfs/<CID>
Alcance	Compartido entre todos los usuarios	Solo tus CIDs
Autenticación	Ninguna	Token opcional / lista de IPs / lista de orígenes
SLA	Mejor esfuerzo	SLA completo
Recomendado para	Enlaces ocasionales	Incrustación en producción (NFT, video, sitios web)
Límites de tasa	Compartido por IP + por CID	Por plan, configurable

Ambos sirven contenido idéntico. Para tráfico de producción, usa el gateway dedicado.

¿Qué tipos de archivo son compatibles?

Todos los tipos de archivo son compatibles. Los objetos y arreglos JSON pueden enviarse directamente. Todos los demás archivos (imágenes, PDFs, HTML, video, audio, binarios) se envían como contenido codificado en base64.

¿Hay un límite de tamaño de archivo?

Las subidas individuales están limitadas por la capacidad de almacenamiento de tu plan. No hay límite de tamaño por archivo más allá de tu almacenamiento disponible.

¿Puedo fijar contenido que ya existe en IPFS?

Sí. Usa POST /pin con cualquier CID válido. Nuestro cluster buscará el contenido en la red IPFS y lo fijará a tu cuenta. Consulta la documentación de la API de Fijación para más detalles.

¿Cuánto tiempo toma la fijación?

Depende del tamaño del archivo y de cuántos nodos IPFS tienen el contenido. Los archivos pequeños y bien distribuidos se fijan en segundos. El contenido grande o raramente fijado puede tomar algunos minutos. El endpoint de fijación responde inmediatamente con el estado pinning — consulta GET /pin/:cid para verificar el progreso.

¿Qué sucede si un CID no puede encontrarse?

El estado cambia a failed. Esto significa que el CID es inválido o que el contenido ya no está disponible en ningún nodo IPFS alcanzable.

¿Los datos subidos a IPFS son públicos?

Sí. Todo el contenido fijado en IPFS es accesible públicamente a través de su CID mediante cualquier gateway IPFS. Si necesitas acceso privado, usa un gateway dedicado con modo de token requerido — esto restringe el acceso a través de tu gateway, aunque el contenido permanece disponible en la red IPFS más amplia.

¿Por qué mis nuevos CIDs cambiaron de Qm... a bafy...?

Las nuevas subidas y fijaciones devuelven CIDv1 moderno (bafk… para contenido pequeño de un solo bloque, bafy… para archivos y directorios más grandes) según el perfil IPIP-0499 unixfs-v1-2025: codificación CIDv1 en base32, fragmentos de 1 MiB, raw leaves. Esto coincide con lo que producen las herramientas modernas (Helia, el último Kubo, ipfs-car) para el mismo contenido, así que un archivo subido a través de nosotros obtiene el mismo CID que calcularía cualquier cliente moderno para los mismos bytes.

Los CIDs Qm… heredados de subidas anteriores siguen siendo totalmente resolubles — el gateway, POST /pin, GET /file, IPNS y todos los demás endpoints aceptan ambos formatos indefinidamente. Nada de lo que ya tienes deja de funcionar.

¿Cómo fijo contenido que vive en un nodo privado / que no está en la DHT?

POST /pin acepta multiaddresses[] opcional (hasta 5). Si se proporciona, nuestro cluster ejecuta ipfs swarm connect <multiaddr> para cada indicación antes de que se ejecute la fijación, de modo que el contenido en peers que no se anuncian a través de la DHT pública (nodos privados, entornos de staging, máquinas locales de VPN) sea alcanzable. Consulta la guía Fijar desde un nodo IPFS privado.

¿Mis archivos permanecen en IPFS si cancelo mi cuenta?

Desfijamos tus archivos de nuestros nodos cuando cancelas. Si otros nodos IPFS han almacenado en caché tu contenido, puede seguir siendo accesible. Sin embargo, sin fijación activa, los archivos serán eventualmente eliminados por la recolección de basura en la red.

Autenticación y API

¿Cómo autentico las solicitudes a la API?

Pasa tu clave API a través del encabezado X-Api-Key. Genera claves desde la página de Claves API en tu panel de control.

¿Hay límites de tasa en la API?

No. IPFS Ninja no impone límites de tasa en las solicitudes a la API. Puedes hacer tantas solicitudes como necesites en cualquier plan.

¿Las claves API expiran?

No. Las claves API son válidas hasta que las elimines. Puedes crear múltiples claves y revocarlas individualmente.

¿Cuál es la diferencia entre claves API y tokens de gateway?

Las claves API (bws_) tienen acceso completo — subir, eliminar, listar archivos. Los tokens de gateway (gwt_) son de solo lectura y solo pueden acceder a archivos a través de tu gateway dedicado. Los tokens de gateway son seguros para incrustar en aplicaciones frontend.

Gateways Dedicados

¿Qué es un gateway dedicado?

Un gateway IPFS privado en tu propio subdominio (por ejemplo, abc123.gw.ipfs.ninja) que solo sirve archivos fijados a tu cuenta. A diferencia del gateway público, no resolverá CIDs de otros usuarios.

¿Qué planes incluyen un gateway dedicado?

Los gateways dedicados están disponibles en todos los planes de pago (Bodhi $5/mes, Karma $19/mes, Nirvana $59/mes). La cuota mensual de ancho de banda de cada plan cubre el tráfico tanto del gateway apex como del dedicado. Consulta «¿Hay cargos por ancho de banda?» más abajo para las cuotas por plan.

¿Puedo restringir quién accede a mi gateway?

Sí. Puedes habilitar el modo de token requerido (requiere un token gwt_ en cada solicitud) y/o configurar una lista blanca de IPs (hasta 100 direcciones).

¿Puedo restringir mi gateway por origen/dominio?

Sí. Configura allowedOrigins en la configuración de tu gateway con una lista de orígenes HTTPS. Solo las solicitudes de navegador desde esos orígenes serán permitidas. Las solicitudes que no son de navegador (sin encabezado Origin) pasan sin restricción. Una lista vacía permite todos los orígenes.

¿Qué son los tokens de subida firmados?

Los tokens de subida firmados son credenciales con tiempo limitado para subidas del lado del cliente. Los generas en tu servidor usando POST /upload/signed-url y los pasas a navegadores o aplicaciones móviles. El cliente se autentica con Authorization: Signed <token> en lugar de exponer tu clave API. Cada token rastrea el uso y expira automáticamente. Consulta la documentación de Tokens Firmados para más detalles.

¿Puedo optimizar imágenes servidas desde IPFS?

Sí. Usa GET /image/:cid con parámetros de consulta como w, h, format y quality para redimensionar, convertir y comprimir imágenes al vuelo. Las respuestas se almacenan en caché basándose en el CID direccionado por contenido. Esto funciona en todos los planes. Consulta Optimización de Imágenes.

¿Puedo adjuntar metadatos a los archivos?

Sí. Incluye un objeto metadata con hasta 10 pares clave-valor al subir mediante POST /upload/new o al fijar mediante POST /pin. Los metadatos se devuelven en los listados de archivos y en el endpoint de detalle del archivo. Consulta la documentación de Archivos y Fijación.

Facturación y Planes

¿Hay un plan gratuito?

Sí. El plan Dharma es gratuito para siempre — 1 GB de almacenamiento, solicitudes API ilimitadas, sin tarjeta de crédito requerida.

¿Hay cargos por ancho de banda?

No hay cargos por ancho de banda medido en ningún plan. Cada plan incluye una cuota mensual de ancho de banda del gateway que es un límite estricto — tu contenido deja de servirse en los gateways apex y dedicado una vez alcanzada la cuota, y se reanuda el día 1 del mes siguiente o tras una actualización de plan:

Plan	Ancho de banda mensual
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Recibirás correos de aviso al 80% y al 100% de tu cuota.

¿El almacenamiento se reinicia?

El almacenamiento no se reinicia. Tu plan incluye una capacidad total de almacenamiento (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Para liberar espacio, elimina archivos que ya no necesites. Actualizar tu plan aumenta tu capacidad total.

¿Puedo cancelar en cualquier momento?

Sí. Cancela tu suscripción a través del portal de facturación — sin compromiso de permanencia. Tu cuenta vuelve al nivel gratuito, y los archivos fijados existentes siguen siendo accesibles.

¿Qué pasa con mis archivos si bajo de plan?

Tus archivos permanecen fijados en IPFS, pero no podrás subir más si tu uso actual excede el límite de almacenamiento del nuevo plan. Elimina archivos para volver a estar dentro del límite.

Seguridad

¿Mis datos están cifrados?

Todos los datos están cifrados en tránsito a través de TLS/HTTPS. La autenticación usa tokens JWT (Cognito) y claves API almacenadas de forma segura. El contenido de los archivos en IPFS no está cifrado en reposo — IPFS es una red pública por diseño.

¿Es seguro usar claves API en mi código del lado del servidor?

Sí. Las claves API están diseñadas para uso del lado del servidor. Nunca las expongas en código del lado del cliente. Para acceso a archivos del lado del cliente, usa tokens de gateway (gwt_) que son de solo lectura.

Soporte

¿Cómo obtengo ayuda?

Envía un correo a info@ipfs.ninja o consulta la documentación de la Referencia de la API.

¿Hay un SLA?

Nos esforzamos por una alta disponibilidad pero no ofrecemos un SLA formal en este momento. El servicio se proporciona "tal cual".