Файлы

Загрузка, просмотр и получение файлов в IPFS. См. аутентификацию для настройки API-ключа и ошибки для справки по кодам статусов HTTP.

Загрузите файл в IPFS за 3 шага

POST /upload/new

1. Закодируйте файл в base64 (для изображений/PDF) или передайте JSON-объект напрямую.
2. Отправьте POST-запрос на /upload/new с вашим API-ключом в заголовке X-Api-Key.
3. Сохраните возвращённый cid — он навсегда идентифицирует ваш файл в IPFS.

Загрузите любой файл в IPFS. Файл закрепляется, и возвращается постоянный CID.

Тело запроса

Параметр	Тип	Обязательный	Описание
content	string | object	Да	JSON-объект/массив или данные файла в кодировке base64 (изображения, PDF, HTML или любой другой тип файла). Для импорта CAR — CAR-файл в кодировке base64.
car	boolean	Нет	Установите true для импорта CAR-файла (импорт DAG). Сохраняет точные CID.
description	string	Нет	Краткое описание загруженного содержимого.
metadata	object	Нет	Пользовательские пары ключ-значение для прикрепления к файлу. Максимум 10 ключей. Ключи должны быть буквенно-цифровыми или содержать символ подчёркивания, 1-64 символа. Значения должны быть строками, максимум 256 символов каждое. Общий размер метаданных не должен превышать 4 KB.

Пример запроса

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Загрузка изображения (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

Ответ 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

CIDv1 по умолчанию

Новые загрузки возвращают современный CIDv1 (bafk… для небольшого одноблочного содержимого, bafy… для файлов большего размера и каталогов) согласно профилю IPIP-0499 unixfs-v1-2025 — блоки по 1 MiB с raw-листьями. Устаревшие CID Qm… из более ранних загрузок остаются полностью разрешимыми и продолжают работать с каждой конечной точкой.

Альтернатива через панель управления

Страница /upload в панели управления принимает перетаскивание файлов, папок (упаковываются в директорию UnixFS прямо в браузере) и архивов .car — всё это проходит через ту же конечную точку. См. Импорт CAR для подробностей о пути CAR.

Поддерживаемые типы файлов

API принимает JSON-объекты и массивы напрямую, а также бинарные файлы в кодировке base64: изображения (JPEG, PNG, GIF, WebP), PDF, HTML и любые другие типы файлов. Сервер автоматически определяет тип содержимого по полезной нагрузке.

Поля ответа

cid в ответе — это постоянный идентификатор содержимого IPFS. sizeMB — сохранённый размер в мегабайтах. Объект uris содержит как нативный URI ipfs://, так и URL шлюза HTTPS для доступа из браузера.

Переименовать файл

PUT /files/:cid/name

Обновите отображаемое имя файла. CID не меняется — это хеш содержимого — меняется только метка, которую вы видите в списке файлов.

Тело запроса

Параметр	Тип	Обязательный	Описание
name	string	Да	Новое отображаемое имя. 1-200 символов. Не должно содержать разделители пути (/, \). Имена, состоящие только из пробелов, отклоняются.

Пример запроса

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Ответ 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Панель управления

На странице «Файлы» в меню действий каждой строки файла (кнопка с тремя точками) есть пункт Rename. Тот же эффект без написания кода.

Список файлов

GET /upload/list

Получите список загруженных файлов IPFS за указанный период.

Параметры запроса

Параметр	Тип	Обязательный	Описание
from	number	Да	Начало периода, временная метка Unix в миллисекундах.
to	number	Да	Конец периода, временная метка Unix в миллисекундах.

Пример запроса

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Получить файл

GET /file/:cid

Получите метаданные конкретного загруженного файла по его CID.

Параметры пути

Параметр	Тип	Обязательный	Описание
cid	string	Да	Идентификатор содержимого IPFS файла.

Пример запроса

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}