Файлове

Качване, списък и извличане на файлове в IPFS. Вижте удостоверяване за настройка на API ключ и обработка на грешки за HTTP кодовете на състоянието.

Качете файл в IPFS: 3 стъпки

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

POST /upload/new

Качете произволен файл в IPFS. Файлът се закача и се връща постоянен CID.

Тяло на заявката

Параметър	Тип	Задължителен	Описание
content	string | object	Да	JSON обект/масив, или base64-кодирани данни на файла (изображения, PDF, HTML или произволен тип файл). За CAR импорт — base64-кодиран CAR файл.
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"
  })
});

Response 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 със сурови листа. По-старите CID-ове Qm… от предишни качвания остават напълно разрешими и продължават да работят с всяка крайна точка.

Алтернатива в таблото за управление

Страницата /upload в таблото приема плъзгане и пускане (drag-and-drop) за файлове, папки (пакетирани в UnixFS директория в браузъра) и .car архиви — всички минаващи през същата крайна точка. Вижте CAR импорт за подробности за пътя през CAR.

Поддържани типове файлове

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

Полета в отговора

cid в отговора е постоянният идентификатор на съдържанието в IPFS. sizeMB е съхраненият размер в мегабайти. Обектът uris съдържа както родния ipfs:// адрес, така и HTTPS адрес към gateway за достъп от браузър.

Преименуване на файл

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" }'

Response 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"

Response 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"

Response 200 OK

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