İçeriğe geç

API belgeleri

Bir dosyayı bir kez yükleyin, seçtiğiniz dosya barındırma sitelerine gönderin ve tek bir paylaşım bağlantısı alın — kendi kodunuzdan.

Güncellendi

Sürümlü bir REST API: bir dosyayı parçalar hâlinde yükleyin, seçtiğiniz sitelere gönderin; her kopya canlı durumuyla tek bir paylaşım sayfasında toplanır.

Temel URL
https://api.mirroruploadx.com/api/v1
Kimlik doğrulama
x-api-key: mux_…
  1. 1Oturum açın

    POST /api/v1/upload-sessions

    filename + sizeBytes; sessionId ve chunkSize alın

  2. 2Parçaları gönderin

    PATCH /api/v1/upload-sessions/{id}/chunks

    sırayla ham baytlar; dosyayı tamamlayan yanıtta fileId bulunur

  3. 3Dağıtın

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; ardından işi sorgulayın

Bir anahtarı API anahtarları sayfasında oluşturun. Kod içeren tam anlatım Yükleme ve dağıtım bölümündedir.

Kimlik doğrulama

Panelinizdeki API anahtarları sayfasında bir anahtar oluşturun. Anahtarın tamamı (mux_ ile başlar) yalnızca bir kez gösterilir, bu yüzden hemen saklayın. Her istekte anahtarı x-api-key başlığında gönderin; yalnızca bearer token kullanabilen istemciler için Authorization: Bearer mux_… de aynı şekilde kabul edilir.

Anahtarlar kapsamlıdır: bir anahtar yalnızca kapsamlarının kapsadığı uç noktalara ulaşır ve yanlış kapsamla yapılan bir çağrı, mesajda gereken kapsamla birlikte 403 INSUFFICIENT_SCOPE döndürür. Hesap ayarlarına, anahtar yönetimine ve webhook’lara API anahtarıyla hiç ulaşılamaz (API_KEY_NOT_ALLOWED).

KapsamErişim
upload:writeYükleme oturumları (oluşturma, parçalar, tamamlama, iptal), yükleme kotanız, bir yüklemenin otomatik dağıtımını bekletme veya değiştirme (hold-distribution, distribution-intent), uzak URL yüklemeleri, dağıtımı başlatma
file:readDosyaları listeleme, dosya ayrıntıları, ayna ve iş durumu
file:writeBir dosyanın paylaşım ayarları
file:deleteBir dosyayı ve aynalarını silme

Uç noktalar

Bir API anahtarının ulaşabildiği her şey ve anahtar gerektirmeyen herkese açık uç noktalar. Kapsam sütununda iki kapsam yazıyorsa ikisinden biri yeterlidir. Her birinin istek ve yanıt şemaları API başvurusunda yer alır.

YöntemYolKapsamNe yapar
POST/api/v1/upload-sessionsupload:writeBir yükleme oturumu açar (isteğe bağlı olarak bir dağıtım planıyla)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeSonraki bayt parçasını gönderir
HEAD/api/v1/upload-sessions/{id}upload:writeNereden devam edileceği: Upload-Offset başlığı
GET/api/v1/upload-sessions/{id}upload:writefile:readOturum durumu: alınan baytlar, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readYükleme sınırlarınız, kullanımınız ve tamamlanmamış oturumlarınız
POST/api/v1/upload-sessions/{id}/completeupload:writeSon yanıtı kaybolan bir yüklemeyi tamamlar (yeniden denemesi güvenlidir)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeErtelenmiş bir dağıtımın kendiliğinden başlamasını durdurur
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeBir yüklemenin dağıtım planını değiştirir
DELETE/api/v1/upload-sessions/{id}upload:writeTamamlanmamış bir yüklemeyi iptal eder ve yerini boşaltır
POST/api/v1/remote-uploadsupload:writehttp(s) URL’lerinden dosyaları hesabınıza getirir
POST/api/v1/mirror-tasks/startupload:writeBir dosyayı seçtiğiniz sitelere gönderir
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readİş durumu, her site ve paylaşım bağlantısı (shareTakenDown kaldırılmış bir sayfayı işaretler)
GET/api/v1/filesfile:readDosyalarınızı listeler (imleçle sayfalama, arama, filtreler)
GET/api/v1/files/{id}file:readTek dosya: boyut, sağlama toplamı, iş, paylaşım ayarları, istatistikler
GET/api/v1/files/{id}/mirrorsfile:readBir dosyanın her kopyası: site, bağlantı, sağlık, tıklamalar
PATCH/api/v1/files/{id}/sharefile:writePaylaşım parolası, bitiş tarihi, görünürlük
DELETE/api/v1/files/{id}file:deleteBir dosyayı ve (varsayılan olarak) sitelerdeki kopyalarını siler
GET/api/v1/platformyok (herkese açık)Güncel sınırlar: en büyük dosya, dosya başına site sayısı, URL yükleme sınırları
GET/api/v1/providersyok (herkese açık)providerSlugs içinde gönderdiğiniz slug’larla birlikte site kataloğu
GET/api/v1/providers/statusyok (herkese açık)Site başına ölçülen yükleme başarısı
GET/api/v1/stats/publicyok (herkese açık)Son 30 günün platform toplamları: dosyalar, canlı aynalar, başarı oranı

Bir dosyayı yükleyin ve dağıtın

  1. POST /api/v1/upload-sessions ile bir oturum açın. filename ve sizeBytes (tam bayt uzunluğu) zorunludur; mimeType ve bir UUID idempotencyKey isteğe bağlıdır — aynı anahtarla bir isteği tekrarlamak ikinci bir oturum açmak yerine mevcut oturumu döndürür. Yanıtta data.sessionId (id değil) ve data.chunkSize bulunur.
  2. PATCH /api/v1/upload-sessions/{id}/chunks ile baytları gönderin: ham baytlar, içerik türü application/offset+octet-stream ve parçanın başlangıç konumu upload-offset başlığında. Parçalar sırayla ya da en fazla maxChunksAhead parça ileriden gider; sırayla gönderirken her yanıttaki data.uploadedBytes değerini sonraki ofset olarak kullanın. chunkSize baytlık parçalar gönderin; sonuncusu dışındaki her parça en az 5 MiB olmalıdır ve bir yükleme en fazla 10 000 parçadan oluşabilir. Dosyayı tamamlayan yanıtta data.fileId bulunur. Daha fazla hız için aynı dosyanın 2–3 parçasını aynı anda gönderebilirsiniz. İlk parçayı tek başına gönderin; yanıtı gerçek data.maxChunksAhead değerini verir (ilk parça tam bir chunkSize dilimiyse 4, 0 = yalnızca sırayla). İlk parça tam bir chunkSize dilimiyse sonraki her parça da (sırayla ya da ileriden) öyle olmalıdır: chunkSize değerinin bir katında başlar ve tam olarak chunkSize bayttır (sonuncusu: dosyanın geri kalanı). uploadedBytes değerinin ilerisinden gönderilen bir parça böyle bir dilim olmalı ve en fazla data.maxChunksAhead parça ileride başlamalıdır; aksi hâlde 409 CHUNK_MISALIGNED veya 409 CHUNK_OUT_OF_WINDOW alır. uploadedBytes yalnızca boşluksuz alınan baytları sayar ve dosyayı hangi parça tamamlarsa fileId içeren yanıtı o alır. Zaten ulaşmış bir parçayı yeniden göndermek zararsız bir başarıdır.
  3. POST /api/v1/mirror-tasks/start ile dağıtın: fileId ve providerSlugs zorunludur (slug’lar GET /api/v1/providers ile alınır). İsteğe bağlı: minSuccess (varsayılan 1 — işin başarısız olmaması için dosyayı kaç sitenin kabul etmesi gerektiği; yalnızca her site de dosyayı aldığında completed, aksi hâlde partially_completed olur. Bu dosya türünü reddeden siteler sayılmaz), sharePassword, expiresInDays veya expiresAt. Yanıtta uploadJobId, taskCount, shareSlug, alreadyStarted ve skipped[] bulunur — bu dosyayı alamayan bir site başarısız değil, atlanmış sayılır; bu yüzden skipped[] alanını okuyun (nedenler aşağıda listelenmiştir). Bir dosya şu anda en fazla 50 siteye gönderilebilir.
  4. data.terminal değeri true olana kadar birkaç saniyede bir GET /api/v1/mirror-tasks/{uploadJobId} ile bitişini izleyin. Yanıt her siteyi tasks[] içinde (providerSlug, status, mirrorUrl, errorCode), paylaşım bağlantısını ise data.shareUrl içinde listeler. O paylaşım sayfası kaldırılmışsa ve artık açılmıyorsa data.shareTakenDown değeri true olur.

Şu anda kabul edilen en büyük dosya boyutu: 5,00 GB.

bash, jq gerekir

set -euo pipefail
API=https://api.mirroruploadx.com
FILE=clip.mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')

# 1. Open an upload session
SESSION_JSON=$(curl -sS --fail-with-body -X POST "$API/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"filename":"clip.mp4","sizeBytes":'"$SIZE"',"mimeType":"video/mp4"}')
SESSION=$(echo "$SESSION_JSON" | jq -r .data.sessionId)
CHUNK=$(echo "$SESSION_JSON" | jq -r .data.chunkSize)

# 2. Send the bytes in order, one chunk per request
OFFSET=0
while [ "$OFFSET" -lt "$SIZE" ]; do
  dd if="$FILE" of=part.bin bs="$CHUNK" skip=$((OFFSET / CHUNK)) count=1 status=none
  REPLY=$(curl -sS --fail-with-body -X PATCH "$API/api/v1/upload-sessions/$SESSION/chunks" \
    -H "x-api-key: $MUX_API_KEY" \
    -H "upload-offset: $OFFSET" \
    -H "content-type: application/offset+octet-stream" \
    --data-binary @part.bin)
  OFFSET=$(echo "$REPLY" | jq -r .data.uploadedBytes)
done
FILE_ID=$(echo "$REPLY" | jq -r .data.fileId)

# 3. Distribute to the hosts you pick
JOB=$(curl -sS --fail-with-body -X POST "$API/api/v1/mirror-tasks/start" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"fileId":"'"$FILE_ID"'","providerSlugs":["gofile","pixeldrain"],"minSuccess":1}' \
  | jq -r .data.uploadJobId)

# 4. Poll until the job is terminal, then print the share link
until curl -sS --fail-with-body "$API/api/v1/mirror-tasks/$JOB" \
        -H "x-api-key: $MUX_API_KEY" > job.json \
      && [ "$(jq -r .data.terminal job.json)" = "true" ]; do
  sleep 5
done
jq -r '.data.status, .data.shareUrl' job.json

Örnek yanıtlar

Oturum açma 201 ile yanıt verir. Sonuncusu dışındaki her parça { uploadedBytes, completed: false, expiresAt } ile yanıt verir; sonuncusu dosyayı taşır. distribution yalnızca oturumu açarken bir plan verdiyseniz bulunur (aşağıya bakın).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (dosyayı tamamlar) → 200
{
  "success": true,
  "data": {
    "uploadedBytes": 10485760,
    "completed": true,
    "fileId": "…",
    "scan": "skipped",
    "distributable": true,
    "distribution": {
      "started": true,
      "uploadJobId": "…",
      "taskCount": 2,
      "shareSlug": "…",
      "skipped": []
    }
  }
}
POST /mirror-tasks/start → 202
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "taskCount": 2,
    "shareSlug": "…",
    "skipped": [],
    "alreadyStarted": false
  }
}
GET /mirror-tasks/{uploadJobId} → 200
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "status": "completed",
    "terminal": true,
    "shareSlug": "…",
    "shareUrl": "https://mirroruploadx.com/f/…",
    "shareTakenDown": false,
    "minSuccess": 1,
    "scan": "skipped",
    "tasks": [
      {
        "provider": "Gofile",
        "providerSlug": "gofile",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://gofile.io/d/…",
        "mirrorHidden": false
      },
      {
        "provider": "Pixeldrain",
        "providerSlug": "pixeldrain",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://pixeldrain.com/u/…",
        "mirrorHidden": false
      }
    ]
  }
}

İlk ve başarılı bir start 202 ile yanıt verir; zaten çalışan bir iş için yeniden çağırmak alreadyStarted: true ile 200 döndürür. Bir sitenin bağlantısı politika gereği gizli tutulduğunda mirrorUrl değeri null ve mirrorHidden değeri true olur — paylaşım sayfası onu yine de listeler.

İkinci çağrıyı atlayın

Oturumu açarken distribution verirseniz sunucu, dosya tamamlanır tamamlanmaz dağıtıma başlar. Dosyayı tamamlayan yanıttaki data.distribution alanını kontrol edin: started: true, işin kuyruğa alındığı anlamına gelir (uploadJobId, shareSlug). started: false ve deferred: true ile henüz bilerek hiçbir şey kuyruğa alınmamıştır — aşağıya bakın. started: false olup deferred yoksa yükleme yine de başarılı olmuştur ancak dağıtım başlatılamamıştır (error nedenini söyler): fileId ile POST /api/v1/mirror-tasks/start çağırın. deferred: true ile birlikte bir error, geçici bir hata anlamına gelir (örneğin tüm siteler yoğun veya bakımda): start çağırmayın veya dosyayı yeniden yüklemeyin — sunucu dağıtımı başlatmayı autoStartAt zamanından itibaren kendisi yeniden dener (en fazla 5 deneme). Durdurmak için hold-distribution çağırın.

curl
curl -sS -X POST "https://api.mirroruploadx.com/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "sizeBytes": 10485760,
    "mimeType": "video/mp4",
    "distribution": { "providerSlugs": ["gofile", "pixeldrain"], "minSuccess": 1 }
  }'
# The reply to the final chunk then carries data.distribution:
#   { "started": true, "uploadJobId": "…", "taskCount": 2, "shareSlug": "…", "skipped": [] }
#   or { "started": false, "error": { "code": "…", "message": "…" } }

Bir bekleme süresi için distribution alanına deferred: true ekleyin: son yanıt { started: false, deferred: true, autoStartAt } olur ve siz önce start çağırmazsanız sunucu dağıtımı autoStartAt zamanında (yaklaşık 2 dakika sonra) kendisi başlatır. Otomatik başlatmayı durdurmak için POST /api/v1/upload-sessions/{id}/hold-distribution çağırın (gövde yok; autoStartAt değeri null olur ve dağıtımı siz başlatırsınız). Bunun yerine planı değiştirmek için distribution ile aynı alanlarla (providerSlugs, minSuccess, expiresInDays, sharePassword) PUT /api/v1/upload-sessions/{id}/distribution-intent çağırın: planı değiştirir ve beklemeyi kaldırır; yükleme bittiyse otomatik başlatma, çağrıdan en az 2 dakika sonrasına kayar. Dağıtım zaten başladıysa ikisi de 200 ile yanıt verir ve distribution-intent alreadyStarted: true döndürür.

30 dakika içinde başlatın. Bir yükleme bittiğinde ve hiçbir dağıtım başlatılmadığında, dosyanın bizdeki kopyası 30 dakika sonra kaldırılır (sitelerin kullanılabilir hâle gelmesini bekleyen bir dağıtım planı varsa en fazla 72 saat sonra; uzak URL yüklemeleri etkilenmez). Bundan sonra start ve distribution-intent 409 SOURCE_GONE ile yanıt verir ve dosyanın yeniden yüklenmesi gerekir.

Son yanıt kaybolursa

GET /api/v1/upload-sessions/{id} çağırın: bir fileId dosyanın var olduğu anlamına gelir; finalizable: true her baytın ulaştığı ve POST /api/v1/upload-sessions/{id}/complete çağrısının yüklemeyi tamamlayacağı anlamına gelir. Bu çağrıyı yeniden denemek güvenlidir ve asla ikinci bir dosya oluşturmaz. Uyuşmayan bir ofset 409 CHUNK_OFFSET_CONFLICT alır — oturuma HEAD gönderin ve Upload-Offset başlığından devam edin. Çalışan bir iş için start çağrısını yinelemek hata değildir: alreadyStarted: true ile 200 alırsınız.

Bir URL’den yükleme

POST /api/v1/remote-uploads, { "urls": [...] } alır ve her dosyayı sizin için getirir (kapsam upload:write). Yalnızca http ve https bağlantıları getirilir, özel ağ adresleri reddedilir ve yalnızca sınırlı sayıda yönlendirme izlenir. Tek bir istek en fazla 10 URL taşır (GET /api/v1/platform tarafından döndürülür); daha uzun listeleri bölün.

Dosya başına boyut sınırı kaynağa bağlıdır. Kaynak dosyanın boyutunu bildiriyorsa her dosya en fazla 5,00 GB (limits.remoteUploadPassthroughMaxBytes), bildirmiyorsa en fazla 100,0 MB (limits.remoteUploadMaxBytes) olabilir. Dosya adı, gönderdiğinde kaynağın Content-Disposition başlığından alınır; uzantısız bir ada dosyanın türüne göre bir uzantı eklenir.

İstek, dosyalar indirilirken bekler. Bağlantı önce koparsa dosya yine de hesabınıza ulaşır — onu GET /api/v1/files ile bulun. Her fileId ardından yukarıdaki gibi POST /api/v1/mirror-tasks/start ile dağıtılır.

Geçici depolama alanı dolu olduğunda isteğin tamamı details.reason: "staging_full" ve bir Retry-After başlığıyla birlikte 503 TEMPORARILY_UNAVAILABLE alır. Yalnızca bir URL sığmıyorsa results[] içindeki o girdide ok: false ve aynı kod bulunur; URL başına bir sonuçta başlık olmadığından saniye cinsinden bekleme süresi details.retryAfter içindedir.

curl -sS -X POST "https://api.mirroruploadx.com/api/v1/remote-uploads" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"urls":["https://example.com/files/archive.zip"]}'

# One result per URL, in order. A failed URL does not fail the batch:
# {"success":true,"data":{"results":[
#   {"url":"https://example.com/files/archive.zip","ok":true,
#    "fileId":"…","scan":…,"distributable":true}
# ]}}
# or {"url":"…","ok":false,"code":"REMOTE_TOO_LARGE","error":"…"}
#
# Then distribute each fileId with POST /api/v1/mirror-tasks/start.

Dosya yönetimi

Dosyalarınız yüklemeden sonra hesabınızda kalır. Onları GET /api/v1/files ile listeleyin (limit en fazla 100; sonraki sayfa için yanıttaki nextCursor değerini cursor olarak verin, q ada göre arar). GET /api/v1/files/{id} tek bir dosyayı işi, paylaşım ayarları ve görüntüleme istatistikleriyle döndürür; GET /api/v1/files/{id}/mirrors her kopyayı bağlantısı, sağlığı ve tıklamalarıyla listeler.

PATCH /api/v1/files/{id}/share (kapsam file:write) paylaşım sayfasını değiştirir: password (4–128 karakter, null kaldırır — asla döndürülmez, yalnızca passwordProtected döner), expiresAt (ISO tarih, bitiş olmaması için null), visibility ve hideDownloadCount. Yalnızca değiştirmek istediğiniz alanları gönderin. DELETE /api/v1/files/{id} (kapsam file:delete) dosyayı kaldırır ve sitelerdeki kopyalarını silinmek üzere kuyruğa alır; onları tutmak için ?keepMirrors=true ekleyin. Bazı siteler silmeyi desteklemez, bu yüzden orada bir kopya kalabilir.

bash, jq gerekir; FILE_ID ayarlayın

API=https://api.mirroruploadx.com
H="x-api-key: $MUX_API_KEY"

# List your files, newest first (20 per page; pass ?cursor=<nextCursor> for more)
curl -sS "$API/api/v1/files?limit=20" -H "$H" | jq '.data.items[] | {id, name, mirrorCount, shareSlug}'

# One file, then every copy of it
curl -sS "$API/api/v1/files/$FILE_ID" -H "$H"
curl -sS "$API/api/v1/files/$FILE_ID/mirrors" -H "$H" | jq '.data.mirrors[] | {providerSlug, status, url}'

# Share settings: a password and an expiry date (null removes either)
curl -sS -X PATCH "$API/api/v1/files/$FILE_ID/share" -H "$H" -H "content-type: application/json" \
  -d '{"password":"correct-horse","expiresAt":"2026-12-31T23:59:59Z"}'

# Delete the file and its copies on hosts (?keepMirrors=true keeps the copies)
curl -sS -X DELETE "$API/api/v1/files/$FILE_ID" -H "$H"
DELETE /files/{id} → 200
{
  "success": true,
  "data": {
    "stagingDeleted": true,
    "mirrorsQueued": true,
    "mirrorsPurgeDeferred": false,
    "note": "File removed. Copies on providers are being deleted; some may remain on providers that do not support deletion."
  }
}

Webhook’lar

Webhook’lar sayfasında bir uç nokta ekleyin. URL https:// kullanmalıdır; imzalama sırrı (whsec_…) oluşturduğunuzda bir kez gösterilir. Hiçbir olay seçilmemiş bir uç nokta tüm olayları alır.

OlayNe zaman
upload.completedHer site dosyayı kabul etti ve en az minSuccess kadarı kabul etti — bu dosyayı reddeden (rejected) veya iptal edilen siteler sayılmaz
upload.partially_completedEn az minSuccess kadar site dosyayı kabul etti, ancak en az bir başka site başarısız oldu
upload.failedDosyayı minSuccess değerinden az site kabul etti (minSuccess 0 ise 1 sayılır)
upload.quarantinedZararlı yazılım taraması dosyayı işaretledi (yalnızca tarama etkinken)
provider.upload_succeededBir site dosyayı kabul etti — her site için bir kez gönderilir
provider.upload_failedBir site dosyadan vazgeçti — her site için bir kez gönderilir
webhook.testWebhook’lar sayfasında Test et düğmesine bastınız

Her teslimat, JSON gövdeli ve X-MUX-Event ile X-MUX-Signature başlıklarını içeren tek bir POST isteğidir. 10 saniye içinde gelen herhangi bir 2xx yanıtı teslim edildi sayılır; yönlendirmeler izlenmez. Başarısız bir teslimat (ağ hatası, zaman aşımı, 408, 425, 429 veya 5xx) aynı gövdeyle 1, 5 ve 30 dakika sonra yeniden denenir; diğer 4xx yanıtları ve yönlendirmeler denenmez. Her deneme X-MUX-Delivery-Attempt (1–4) ve yeni bir imza taşır, bu yüzden tekrarları gövdeye göre ayıklayın. Teslimat sırası garanti edilmez (yeniden denenen bir olay daha yeni bir olaydan sonra gelebilir); üzerine işlem yapmadan önce data ve createdAt değerlerini karşılaştırın. Eksikleri tamamlamak için GET /api/v1/mirror-tasks/{uploadJobId} kullanın. Son denemesi başarısız olan art arda 15 teslimattan veya tek bir başarı olmadan geçen bir saatlik hatalardan sonra uç nokta duraklatılır; yeniden açmak sayacı sıfırlar. Bir webhook.test teslimatı (Test et düğmesi) X-MUX-Delivery-Attempt: 1 ile bir kez gönderilir ve asla yeniden denenmez.

Gövde
{
  "event": "provider.upload_succeeded",
  "createdAt": "2026-09-25T12:00:00.000Z",
  "data": {
    "uploadJobId": "…",
    "fileId": "…",
    "provider": "gofile",
    "providerName": "Gofile",
    "status": "succeeded",
    "mirrorUrl": "https://…"
  }
}

upload.* olayları uploadJobId, fileId ve status taşır; provider.upload_failed ise mirrorUrl yerine errorCode taşır.

İmzayı doğrulama

Başlık t=1727265600,v1=5f2b… biçimindedir: t Unix saniyesi cinsinden imzalama zamanı, v1 ise uç nokta sırrınızla anahtarlanmış <t>.<raw body> değerinin onaltılık HMAC-SHA256 özetidir. Ham baytları tam olarak alındığı gibi özetleyin, sabit sürede karşılaştırın ve 5 dakikadan eski zaman damgalarını reddedin.

Express

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((kv) => {
      const i = kv.indexOf('=');
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // too old: replay
  const expected = createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest();
  const got = Buffer.from(parts.v1, 'hex');
  return got.length === expected.length && timingSafeEqual(got, expected);
}

const app = express();
// Raw bytes, not parsed JSON: the signature covers the body exactly as sent.
app.post('/hooks/mirroruploadx', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('x-mux-signature') ?? '', process.env.MUX_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const { event, data } = JSON.parse(req.body);
  console.log(event, data.uploadJobId);
  res.sendStatus(204); // any 2xx counts as delivered
});
app.listen(3000);

İstek sınırları

Sınırlar IP adresi başına değil, API anahtarı başına sayılır. Sınırlı bir uç noktadaki her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset (epoch saniyesi) taşır. Sınırın aşılması bir Retry-After başlığıyla birlikte 429 RATE_LIMITED döndürür — o kadar saniye bekleyin. Parça yüklemelerine geniş bir bütçe ayrılır; dar sınırlar oturum açma ve dağıtım başlatma üzerindedir.

GrupUç noktalarAnahtar başınaAralık
Yükleme başlatmaPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 dakika
Parça yüklemePATCH /api/v1/upload-sessions/{id}/chunks6001 dakika
İlerleme sorgulamaGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 dakika
Bir yüklemenin dağıtım ayarlarıPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 dakika
Dağıtım başlatmaPOST /api/v1/mirror-tasks/start301 dakika
Uzak (URL) yüklemelerPOST /api/v1/remote-uploads2010 dakika
Dosya okumaGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 dakika
Dosya değiştirmePATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 dakika
Herkese açık katalogGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 dakika

Bunlar varsayılan değerlerdir. İşletici bunları değiştirebilir, bu yüzden yukarıdaki başlıklar her zaman esas alınacak kaynaktır. Anahtarlarınız için kesin değerler ve şu anda her birinden ne kadar kullandığınız API anahtarları sayfasındadır. Anahtarsız istekler IP adresi başına sayılır; bunlar için yükleme başlatma (60 yerine 10), parça yükleme (600 yerine 300), ilerleme sorgulama (600 yerine 300), bir yüklemenin dağıtım ayarları (300 yerine 60), dağıtım başlatma (30 yerine 10) için daha küçük bütçeler uygulanır; uzak (URL) yüklemeler ve herkese açık katalog için aynı bütçe uygulanır. Dosya okuma ve dosya değiştirme için her zaman anahtar gerekir.

Hatalar

Başarılı yanıtlar { "success": true, "data": … } biçimindedir. Hatalar, HTTP durumunun yanında tek bir biçim kullanır. code kararlıdır — dallanmayı ona göre yapın; message insanlar içindir ve değişebilir. Daha fazla bağlam olduğunda details eklenir, retryable aynı isteği yeniden denemenin işe yarayıp yaramayacağını söyler ve destek ekibiyle iletişime geçerseniz requestId isteğinizi bulmamıza yardımcı olur.

Hata
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
KodHTTPYeniden?Anlamı
NO_TOKEN401HayırAPI anahtarı gönderilmedi
INVALID_API_KEY401HayırAnahtar yanlış veya iptal edilmiş
INSUFFICIENT_SCOPE403HayırAnahtarda bu uç noktanın gerektirdiği kapsam yok
API_KEY_NOT_ALLOWED403HayırBu uç nokta API anahtarıyla kullanılamaz
EMAIL_NOT_VERIFIED403HayırÖnce hesabın e-posta adresini doğrulayın; açık oturumlar çalışmaya devam eder
SESSION_REVOKED401HayırOturum sonlandırıldı (parola sıfırlama veya değiştirme, çıkış); yeniden giriş yapın
ACCOUNT_INACTIVE403HayırHesap askıya alınmış veya silinmek üzere planlanmış
ACCOUNT_DISABLED401 / 409HayırHesap askıya alındı: anahtar kontrolünde 401, istek sürerken değiştiyse 409
ACCOUNT_PENDING_DELETION409Hayırİstek sürerken hesap silinmek üzere planlandı; yeni hiçbir şey başlatılmaz
VALIDATION_ERROR400HayırGövde veya bir parametre geçersiz; details alanına bakın
FILE_REJECTED400HayırDosya türüne veya boyutuna izin verilmiyor; hangisi olduğunu details.reason söyler
TOO_MANY_MIRRORS400HayırBir dosyanın sahip olabileceğinden fazla site
NO_CONNECTED_PROVIDERS400HayırSeçilen her site kendi hesabınızı gerektiriyor ve hiçbiri bağlı değil
PROVIDER_REJECTS_FILE400HayırSeçilen sitelerin hiçbiri bu dosya türünü veya boyutunu kabul etmiyor
NO_AVAILABLE_PROVIDERS400HayırSeçilen sitelerin hiçbiri şu anda yükleme kabul etmiyor; başkalarını seçin veya sonra deneyin. `details.waiting` yalnızca duraklatılmış siteleri listeler (örneğin 24 saat içinde kalkan günlük sınır): `retryable` false olsa da bunlar için sonra yeniden denemek işe yarar
NO_VALID_PROVIDERS400HayırHiçbir providerSlugs değeri etkin bir siteyle eşleşmiyor; GET /api/v1/providers yanıtına bakın
INVALID_JOB_STATE400Hayırİş mevcut durumunda başlatılamaz
JOB_NOT_READY400HayırDosyanın henüz bir dağıtım işi yok
FILE_TOO_LARGE_FOR_UPLOAD400HayırDosya, oturumun parça boyutunda 10 000 parçaya sığmıyor; details.limitBytes
MISSING_OFFSET400HayırBir parça sayısal bir upload-offset başlığı olmadan gönderildi
RAW_BODY_REQUIRED400HayırParça gövdesi, content-type application/offset+octet-stream olan ham baytlardan oluşmalıdır
TOO_MANY_URLS400HayırTek bir remote-uploads isteğinde izin verilenden fazla URL
FILE_NOT_FOUND404HayırHesabınızda böyle bir dosya yok (veya silinmiş)
JOB_NOT_FOUND404HayırHesabınızda böyle bir dağıtım işi yok
SESSION_NOT_FOUND404HayırHesabınızda böyle bir yükleme oturumu yok
SHARE_NOT_FOUND404HayırDosyanın henüz bir paylaşım sayfası yok
QUOTA_EXCEEDED409HayırGünlük veya eşzamanlı bir yükleme sınırı; ne zaman boşalacağını details.retryAt söyler
CHUNK_OFFSET_CONFLICT409Hayırupload-offset alınan baytlarla eşleşmiyor; HEAD ile öğrenip devam edin
CHUNK_TOO_SMALL409HayırSonuncusu dışındaki bir parça 5 MiB’ın altında
CHUNK_TOO_MANY_PARTS409Hayır10 000’den fazla parça; daha büyük parçalar gönderin
CHUNK_MISALIGNED409HayırParça, chunkSize değerinin bir katında başlayan tam bir chunkSize dilimi değil: bu, ileriden gönderilen bir parça için ve ilk parça tam bir chunkSize dilimiyse sonraki her parça için de (sırayla ya da ileriden) zorunludur; ya da parçaları yalnızca sırayla kabul eden bir oturumda bir parça ileriden gönderildi
CHUNK_OUT_OF_WINDOW409HayırBir parça uploadedBytes değerinin maxChunksAhead parçadan daha ilerisinde ya da ilk parça kabul edilmeden önce hiç ilerisinde başlıyor; öncekilerden sonra yeniden gönderin
CHUNK_EXCEEDS_DECLARED_SIZE409HayırParça, oturum oluşturulurken bildirilen dosya boyutunu aşıyor
CHUNK_EMPTY409HayırParçada hiç bayt yok
CHUNK_NOT_RECEIVABLE409HayırOturum artık veri kabul etmiyor (tamamlandı, iptal edildi veya süresi doldu); yeni bir oturum açın
SESSION_EXPIRED409HayırYükleme oturumunun süresi doldu; yeni bir oturum açın
SESSION_NOT_RECEIVABLE409HayırOturum iptal edildi veya süresi doldu ve başka değişiklik kabul etmiyor
SESSION_COMPLETED409HayırYükleme zaten tamamlandı; bunun yerine dosyayı silin
UPLOAD_INCOMPLETE409HayırBaytların hepsi ulaşmadı; önce kalan parçaları gönderin (sayılar details içindedir)
IDEMPOTENCY_KEY_CONFLICT409HayırBu idempotencyKey başka bir yükleme tarafından kullanılıyor; her yükleme için benzersiz bir anahtar kullanın
SOURCE_GONE409HayırDosyanın bizdeki kopyası zaten kaldırıldı, bu yüzden henüz denenmemiş olduğu sitelere gönderilemez; o siteler için yeniden yükleyin. Kopyamız bir dağıtım işi biter bitmez (tamamlandı, kısmen tamamlandı veya başarısız) kaldırılır ve dağıtımı hiç başlatılmayan bir yükleme, bittikten 30 dakika sonra kaldırılır (dağıtım planı hâlâ siteleri bekliyorsa en fazla 72 saat; uzak URL yüklemeleri hariç). Bitmiş bir iş için yalnızca zaten denenmiş sitelerle mirror-tasks/start çağrısını yinelemek yalnızca paylaşım ayarlarını uygular (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409Hayırİş başarısız oldu, iptal edildi veya artık dağıtılamayacak bir durumda
SHARE_TAKEN_DOWN409HayırDosyanın paylaşım sayfası kaldırıldı, bu yüzden daha fazla siteye gönderilemez
FINALIZING409EvetBaşka bir istek dosyayı birleştiriyor; birkaç saniye sonra yeniden sorun
CONFLICT409EvetDevam eden başka bir değişiklikle çakıştı; aynı isteği yeniden deneyin
TEMPORARILY_UNAVAILABLE503Evet, Retry-After sonrasındaSunucu şu anda yoğun; Retry-After süresinden sonra yeniden deneyin. details.reason "staging_full": geçici depolama alanı dolu, yeni yükleme kabul edilmedi (Retry-After yaklaşık 10 dakika); devam eden yüklemeler çalışmayı sürdürür
PAYLOAD_TOO_LARGE413Hayırİstek gövdesi (veya bir parça) sunucunun kabul ettiğinden büyük
REMOTE_TOO_LARGEURL başınaHayırBir remote-uploads sonucunda: dosya URL yükleme sınırını aşıyor
RATE_LIMITED429Evet, Retry-After sonrasındaBu grup için çok fazla istek
INTERNAL_ERROR500EvetSunucu hatası; ayrıntılar günlüğe kaydedilir, asla döndürülmez
MAINTENANCE503Evet, Retry-After sonrasındaYeni yüklemeler şimdilik duraklatıldı; okumalar çalışmaya devam eder
UPLOADS_TEMPORARILY_UNAVAILABLE503Evet, Retry-After sonrasındaYükleme sayacımız okunamadı; oturum açılmadı
SHUTTING_DOWN503Evet, Retry-After sonrasındaSunucu yeniden başlatılıyor (Retry-After 5 saniye); bekleyin ve aynı isteği yeniden gönderin — hiçbir şey işlenmedi

Bir site neden atlandı

Bunlar hata değildir: başarılı bir start yanıtının (ve dosyayı tamamlayan yanıttaki distribution alanının) skipped[].reason alanında gelirler. Diğer siteler dosyayı yine de alır. Çağrı yalnızca seçilen sitelerin hiçbiri dosyayı alamadığında başarısız olur: PROVIDER_REJECTS_FILE (hiçbiri bu dosyayı kabul etmiyor), NO_CONNECTED_PROVIDERS (hepsi kendi hesabınızı gerektiriyor), NO_AVAILABLE_PROVIDERS (hiçbiri şu anda yükleme kabul etmiyor) veya NO_VALID_PROVIDERS (hiçbir slug etkin bir siteyle eşleşmiyor).

NedenAnlamı
UNKNOWN_PROVIDERBu slug’a sahip bir site yok — yazımı GET /api/v1/providers ile karşılaştırın
PROVIDER_DISABLEDSite şu anda kapalı veya bakımda
ACCOUNT_REQUIREDSite yalnızca kendi hesabınıza yükleme kabul ediyor — onu Bağlantılar sayfasından bağlayın
GUEST_UPLOAD_OFFSite şu anda yükleme kabul etmiyor ve bir hesaba bağlanamıyor
DAILY_LIMIT_REACHEDSitenin hesapsız yüklemeler için günlük sınırı şimdilik doldu (en fazla 24 sa) — yine de yükleyebilmesi için kendi hesabınızı bağlayın
FILE_TOO_LARGEDosya bu sitenin boyut sınırını aşıyor
MIME_NOT_ALLOWEDSite bu dosya türünü kabul etmiyor
ALREADY_ATTEMPTEDBu host bu dosya için zaten denendi, bu yüzden dosya oraya yeniden gönderilmez

API başvurusu, her uç noktanın döndürebileceği kodları listeler.