Dosyalar

IPFS'te dosya yükleme, listeleme ve alma. API anahtarı kurulumu için kimlik doğrulama sayfasına, HTTP durum kodları için hatalar sayfasına bakın.

IPFS'e Dosya Yükleme: 3 Adım

POST /upload/new

1. Dosyanızı base64 olarak kodlayın (görseller/PDF'ler için) veya doğrudan bir JSON nesnesi gönderin.
2. X-Api-Key başlığınızda API anahtarınızla /upload/new adresine POST isteği gönderin.
3. Döndürülen cid'yi kaydedin — dosyanızı IPFS üzerinde kalıcı olarak tanımlar.

Herhangi bir dosyayı IPFS'e yükleyin. Dosya sabitlenir ve kalıcı bir CID döndürülür.

İstek gövdesi

Parametre	Tür	Zorunlu	Açıklama
content	string | object	Evet	JSON nesnesi/dizisi veya base64 kodlanmış dosya verileri (görseller, PDF'ler, HTML veya herhangi bir dosya türü). CAR içe aktarımları için base64 kodlanmış CAR dosyası.
car	boolean	Hayır	Bir CAR dosyası içe aktarmak (DAG içe aktarma) için true olarak ayarlayın. Tam CID'leri korur.
description	string	Hayır	Yüklenen içeriğin kısa açıklaması.
metadata	object	Hayır	Dosyaya eklenecek özel anahtar-değer çiftleri. Maksimum 10 anahtar. Anahtarlar alfanumerik veya alt çizgi olmalıdır, 1-64 karakter. Değerler dize olmalıdır, her biri maksimum 256 karakter. Toplam meta veri boyutu 4 KB'yi aşmamalıdır.

Örnek istek

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

Görsel yükleme (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"
  })
});

Yanıt 200 OK

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

Varsayılan olarak CIDv1

Yeni yüklemeler, IPIP-0499 unixfs-v1-2025 profiline göre modern CIDv1 (bafk… küçük tek bloklu içerik için, bafy… daha büyük dosyalar ve dizinler için) döndürür — ham yapraklarla (raw leaves) 1 MiB parçalar. Önceki yüklemelerden gelen eski Qm… CID'leri tam olarak çözümlenebilir olmaya devam eder ve her uç noktayla çalışmaya devam eder.

Dashboard alternatifi

Dashboard'un /upload sayfası, dosyalar, klasörler (tarayıcıda bir UnixFS dizinine paketlenir) ve .car arşivleri için sürükle-bırak kabul eder — hepsi bu aynı uç noktadan geçer. CAR yolu hakkında ayrıntılar için CAR İçe Aktarma bölümüne bakın.

Desteklenen dosya türleri

API, JSON nesnelerini ve dizilerini doğrudan kabul eder, ayrıca base64 kodlanmış ikili dosyaları: görseller (JPEG, PNG, GIF, WebP), PDF'ler, HTML ve diğer her türlü dosyayı. Sunucu, içerik türünü yük verisinden otomatik olarak algılar.

Yanıt alanları

Yanıttaki cid, kalıcı IPFS içerik tanımlayıcısıdır. sizeMB, depolanan boyutu megabayt cinsinden gösterir. uris nesnesi hem yerel ipfs:// URI'sini hem de tarayıcı erişimi için bir HTTPS gateway URL'sini içerir.

Bir Dosyayı Yeniden Adlandır

PUT /files/:cid/name

Bir dosyada görüntülenen adı güncelleyin. CID değişmez — içeriğin bir hash'idir — yalnızca dosya listenizde gördüğünüz etiket değişir.

İstek gövdesi

Parametre	Tür	Zorunlu	Açıklama
name	string	Evet	Yeni görüntüleme adı. 1-200 karakter. Yol ayırıcıları (/, \) içermemelidir. Yalnızca boşluktan oluşan adlar reddedilir.

Örnek istek

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

Yanıt 200 OK

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

Dashboard

Dosyalar sayfasında her dosya satırının eylem menüsünde (üç nokta düğmesi) bir Yeniden Adlandır girişi vardır. Aynı etki, kod yazmaya gerek yok.

Dosyaları Listele

GET /upload/list

Belirli bir zaman aralığındaki yüklenen IPFS dosyalarınızın listesini alın.

Sorgu parametreleri

Parametre	Tür	Zorunlu	Açıklama
from	number	Evet	Zaman aralığı başlangıcı, milisaniye cinsinden Unix zaman damgası.
to	number	Evet	Zaman aralığı bitişi, milisaniye cinsinden Unix zaman damgası.

Örnek istek

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

Yanıt 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"
    }
  }
]

Dosya Al

GET /file/:cid

CID'sine göre belirli bir yüklenen dosyanın meta verilerini alın.

Yol parametreleri

Parametre	Tür	Zorunlu	Açıklama
cid	string	Evet	Dosyanın IPFS içerik tanımlayıcısı.

Örnek istek

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

Yanıt 200 OK

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