Cómo subir archivos a IPFS en 2026 — Guía completa

Si alguna vez has querido almacenar un archivo de forma que ninguna empresa lo controle, que cualquiera pueda verificar y que resista la censura, el InterPlanetary File System (IPFS) es la respuesta. Esta guía te lleva a través de cada forma práctica de subir archivos a IPFS — desde un dashboard simple de arrastrar y soltar hasta código listo para producción en JavaScript y Python.

¿Qué es IPFS y por qué deberías usarlo?

IPFS es un protocolo peer-to-peer para almacenar y compartir archivos. En lugar de direccionar contenido por dónde vive (una URL en un servidor específico), IPFS direcciona contenido por qué es. Cada archivo recibe un Identificador de Contenido (CID) único derivado de un hash criptográfico de sus contenidos. Este diseño te da tres propiedades que el alojamiento tradicional no puede igualar:

• Direccionamiento de contenido. Un CID garantiza que los datos que recibes son exactamente los datos que fueron subidos. Si cambia un solo byte, el CID cambia. Nadie puede manipular tu archivo sin invalidar su dirección.
• Permanencia. Mientras al menos un nodo de la red haya pineado tu archivo, este permanece disponible. Servicios de pinning como IPFS Ninja garantizan que tus archivos permanezcan en línea sin que tengas que ejecutar tu propia infraestructura. Para entender por qué importa el pinning y cómo funciona la recolección de basura, consulta ¿Qué es IPFS Pinning?.
• Resistencia a la censura. Los archivos en IPFS no están atados a un solo dominio o servidor. No hay un único punto de fallo que un gobierno o corporación pueda cerrar.

Los casos de uso comunes incluyen metadatos y medios NFT, recursos de aplicaciones descentralizadas, conjuntos de datos científicos, registros públicos y cualquier escenario donde la integridad de los datos sea importante.

Requisitos previos

Antes de subir cualquier cosa necesitas dos cosas:

1. Una cuenta de IPFS Ninja. Regístrate gratis en https://ipfs.ninja/signup. El plan gratuito te da 500 archivos y 1 GB de almacenamiento — más que suficiente para empezar.

2. Una clave API. Después de iniciar sesión, ve a la sección API Keys en tu dashboard y genera una nueva clave. Tendrá un aspecto similar a bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 (el prefijo bws_a1b2c3d4 se muestra en el dashboard para identificación). Mantén esta clave en secreto. La pasarás en el header X-Api-Key con cada solicitud API.

Si solo quieres usar el dashboard web puedes saltarte el paso de la clave API, pero tenerla desbloquea subidas programáticas desde tus propias aplicaciones.

Método 1: Dashboard web (arrastrar y soltar)

La forma más rápida de subir un archivo es a través del dashboard de IPFS Ninja.

1. Navega a https://ipfs.ninja/upload e inicia sesión.
2. Arrastra y suelta cualquier archivo — JSON, PNG, JPEG, PDF, SVG, o cualquier otro tipo — en el área de subida, o haz clic para explorar tu sistema de archivos.
3. Opcionalmente añade una descripción y metadatos (pares clave-valor) para ayudarte a organizar tus archivos más tarde.
4. Haz clic en Subir. En segundos tu archivo es pineado a IPFS y recibes un CID y una URL de gateway.

Este método soporta cualquier tipo de archivo y no requiere código. Es ideal para subidas puntuales, pruebas rápidas o miembros del equipo no técnicos que necesitan pinear contenido.

Método 2: REST API con curl

Para automatización y scripting, la REST API es el enfoque más directo. El endpoint es:

POST https://api.ipfs.ninja/upload/new

Cada solicitud requiere el header X-Api-Key y un cuerpo JSON con un campo content.

Subir JSON

Para subir un objeto JSON, pásalo directamente como el valor de content:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -d '{
    "content": {
      "name": "Astro Cat #42",
      "description": "A fearless cat exploring the cosmos.",
      "image": "ipfs://bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm",
      "attributes": [
        { "trait_type": "Background", "value": "Nebula" },
        { "trait_type": "Helmet", "value": "Gold" }
      ]
    },
    "description": "NFT metadata for Astro Cat #42",
    "metadata": { "collection": "astro-cats", "tokenId": "42" }
  }'

Los campos description y metadata son opcionales. Se almacenan junto a tu archivo en el dashboard de IPFS Ninja y en las respuestas de la API para ayudarte a identificar y filtrar subidas más tarde. No se incluyen en el contenido pineado a IPFS.

Subir una imagen (archivo binario)

Para archivos binarios como imágenes o PDFs, codifica el archivo en base64 y pasa la cadena codificada como content:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -d "{
    \"content\": \"$(base64 -w 0 photo.png)\",
    \"description\": \"Product photo for landing page\",
    \"metadata\": { \"project\": \"website-redesign\" }
  }"

La API detecta el tipo de contenido automáticamente. No hay necesidad de especificar si estás subiendo JSON, una imagen o un PDF — el servicio lo maneja por ti.

Método 3: JavaScript / Node.js

Usando la API fetch incorporada (Node.js 18+ o cualquier navegador moderno), subir a IPFS solo requiere unas pocas líneas.

Subir JSON

const API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6";

const metadata = {
  name: "Astro Cat #42",
  description: "A fearless cat exploring the cosmos.",
  image: "ipfs://bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm",
  attributes: [
    { trait_type: "Background", value: "Nebula" },
    { trait_type: "Helmet", value: "Gold" },
  ],
};

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
  },
  body: JSON.stringify({
    content: metadata,
    description: "NFT metadata for Astro Cat #42",
  }),
});

const result = await response.json();
console.log("CID:", result.cid);
console.log("Gateway URL:", result.uris.url);

Subir un archivo binario

import { readFileSync } from "node:fs";

const API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6";
const fileBuffer = readFileSync("photo.png");
const base64Content = fileBuffer.toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
  },
  body: JSON.stringify({
    content: base64Content,
    description: "Product photo",
    metadata: { project: "website-redesign" },
  }),
});

const result = await response.json();
console.log("CID:", result.cid);
console.log("IPFS URI:", result.uris.ipfs);
console.log("Gateway URL:", result.uris.url);

Subida por lotes con manejo de errores

En producción a menudo necesitas subir muchos archivos. Aquí tienes un helper reutilizable con reintentos:

import { readFileSync } from "node:fs";

const API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6";
const API_URL = "https://api.ipfs.ninja/upload/new";

async function uploadToIPFS(content, options = {}) {
  const body = { content };
  if (options.description) body.description = options.description;
  if (options.metadata) body.metadata = options.metadata;

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": API_KEY,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Upload failed (${response.status}): ${error}`);
  }

  return response.json();
}

// Upload JSON
const jsonResult = await uploadToIPFS(
  { name: "My Data", values: [1, 2, 3] },
  { description: "Sample dataset" }
);

// Upload image
const imageBase64 = readFileSync("banner.jpg").toString("base64");
const imageResult = await uploadToIPFS(imageBase64, {
  description: "Banner image",
  metadata: { format: "jpg", width: "1200" },
});

console.log("JSON CID:", jsonResult.cid);
console.log("Image CID:", imageResult.cid);

Método 4: Python

La librería requests de Python hace que las subidas a IPFS sean sencillas.

Subir JSON

import requests

API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
API_URL = "https://api.ipfs.ninja/upload/new"

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
}

payload = {
    "content": {
        "name": "Astro Cat #42",
        "description": "A fearless cat exploring the cosmos.",
        "image": "ipfs://bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm",
        "attributes": [
            {"trait_type": "Background", "value": "Nebula"},
            {"trait_type": "Helmet", "value": "Gold"},
        ],
    },
    "description": "NFT metadata for Astro Cat #42",
    "metadata": {"collection": "astro-cats", "tokenId": "42"},
}

response = requests.post(API_URL, json=payload, headers=headers)
result = response.json()

print(f"CID: {result['cid']}")
print(f"Gateway URL: {result['uris']['url']}")

Subir un archivo binario

import base64
import requests

API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
API_URL = "https://api.ipfs.ninja/upload/new"

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
}

with open("photo.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "content": encoded,
    "description": "Product photo",
    "metadata": {"project": "website-redesign"},
}

response = requests.post(API_URL, json=payload, headers=headers)
result = response.json()

print(f"CID: {result['cid']}")
print(f"Size: {result['sizeMB']} MB")
print(f"IPFS URI: {result['uris']['ipfs']}")
print(f"Gateway URL: {result['uris']['url']}")

Subida por lotes

import base64
from pathlib import Path
import requests

API_KEY = "bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
API_URL = "https://api.ipfs.ninja/upload/new"
HEADERS = {"Content-Type": "application/json", "X-Api-Key": API_KEY}


def upload_file(file_path, description=None, metadata=None):
    with open(file_path, "rb") as f:
        encoded = base64.b64encode(f.read()).decode("utf-8")

    payload = {"content": encoded}
    if description:
        payload["description"] = description
    if metadata:
        payload["metadata"] = metadata

    response = requests.post(API_URL, json=payload, headers=HEADERS)
    response.raise_for_status()
    return response.json()


# Upload all PNGs in a directory
for png in Path("./images").glob("*.png"):
    result = upload_file(png, description=f"Image: {png.name}")
    print(f"{png.name} -> {result['cid']}")

Entendiendo la respuesta

Cada subida exitosa devuelve un objeto JSON con los siguientes campos:

{
  "cid": "bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm",
  "sizeMB": 0.024,
  "uris": {
    "ipfs": "ipfs://bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm",
    "url": "https://ipfs.ninja/ipfs/bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm"
  }
}

Acceder a tus archivos

Una vez que un archivo está pineado, hay dos formas principales de recuperarlo.

Gateway dedicado

Cada cuenta de IPFS Ninja incluye un gateway dedicado con un slug personalizado:

https://your-slug.gw.ipfs.ninja/ipfs/{CID}

Los gateways dedicados son más rápidos y confiables que los gateways públicos porque se conectan directamente a la infraestructura de pinning de IPFS Ninja. Puedes acceder a tus archivos a través de tu gateway dedicado usando el CID de la respuesta de subida.

Gateways IPFS públicos

Cualquier gateway IPFS puede servir tu contenido usando el CID:

https://ipfs.ninja/ipfs/{CID}     ← tu gateway dedicado
https://dweb.link/ipfs/{CID}       ← gateway público
https://w3s.link/ipfs/{CID}        ← gateway público

Los gateways públicos son útiles cuando quieres verificar que tu contenido es accesible desde fuera de la red de IPFS Ninja. Ten en cuenta que pueden ser más lentos o tener límites de tasa comparados con tu gateway dedicado.

Desde smart contracts y dApps

Al almacenar referencias on-chain (por ejemplo en un token URI ERC-721), usa el URI ipfs://:

ipfs://bafkreigh2akiscaildc7lqnpfuh3sksq4ogrtz7tpk2aulid5fhqotmqm

Las carteras, mercados y otras aplicaciones compatibles con IPFS saben cómo resolver este URI a través de cualquier gateway disponible.

Mejores prácticas

Mantén los archivos individuales por debajo de 100 MB. Aunque la API acepta subidas más grandes, los archivos más pequeños se pinean más rápido y se replican más eficientemente en la red IPFS. Si estás trabajando con grandes conjuntos de datos, divídelos en trozos más pequeños.

Usa metadatos descriptivos. Los campos description y metadata no tienen coste y hacen mucho más fácil gestionar tus subidas más tarde. Incluye nombres de proyectos, números de versión o cualquier identificador que te ayude a buscar y filtrar.

Almacena los CIDs en tu propia base de datos. Aunque IPFS Ninja almacena tu historial de subidas, mantener tu propio mapeo de CIDs a identificadores a nivel de aplicación (IDs de usuario, números de pedido, IDs de token) hace que tu integración sea más resistente.

Usa el URI de IPFS para referencias on-chain. Siempre almacena ipfs://CID en lugar de una URL de gateway HTTPS en smart contracts o registros inmutables. Las URLs de gateway pueden cambiar; los CIDs no.

Prefiere contenido JSON para datos estructurados. Cuando tus datos están estructurados (metadatos, configuración, registros), pásalos como un objeto JSON en lugar de codificarlos como una cadena. La API los almacena más eficientemente y el contenido IPFS resultante es legible para humanos.

Maneja los errores con elegancia. Comprueba los códigos de estado HTTP e implementa reintentos con backoff exponencial para respuestas 5xx. La API devuelve mensajes de error claros para respuestas 4xx (clave API inválida, contenido faltante, créditos insuficientes) que deberías mostrar a tus usuarios.

Conclusión

Subir archivos a IPFS nunca ha sido más simple. Tanto si prefieres un dashboard visual, un rápido comando curl, o una integración de nivel de producción en JavaScript o Python, IPFS Ninja te da un único endpoint y una experiencia consistente a través de todos los tipos de contenido.

El plan Dharma gratuito incluye 50 archivos, 1 GB de almacenamiento y 2 GB de ancho de banda mensual — suficiente para construir y probar tu integración de extremo a extremo. Cuando estés listo para escalar, el plan Bodhi a $5/mes, el plan Karma a $19/mes y el plan Nirvana a $59/mes ofrecen límites más altos, gateways dedicados y (en Nirvana) soporte prioritario.

Crea tu cuenta gratuita y empieza a subir archivos a IPFS en menos de un minuto.

Para un recorrido más profundo de la API con tokens firmados y subidas del lado del cliente, consulta nuestro Tutorial de API de subida IPFS. Para una referencia completa de la API incluyendo listado de archivos, gestión de claves API y configuración de gateways, visita la documentación.