FileMoon — Dokumentacja API FileMoon

FileMoon REST API

Wprowadzenie

API FileMoon to interfejs HTTP oparty na JSON do automatyzacji przesyłania, zarządzania własnymi plikami i importowania autoryzowanych bezpośrednich adresów URL wideo.

Adres bazowy	`https://filemoon.org/api/v1`
Bieżąca wersja	`v1`
Content-Type	`application/json` / `multipart/form-data`

Security: Używaj HTTPS dla każdego żądania. Nie ujawniaj tokenu w publicznym kodzie, zrzutach ekranu, repozytoriach ani logach.

Pierwsze kroki

Uwierzytelnianie

Wyślij osobisty token FileMoon w nagłówku Authorization przy użyciu schematu Bearer.

HTTP Headers

Authorization: Bearer YOUR_FILEMOON_TOKEN
Accept: application/json

Utwórz token w Panelu Użytkownika → API & Remote Upload. Pełny token jest wyświetlany tylko raz.

Uprawnienia tokenu

files:readOdczyt konta, plików, statusu pliku i zdalnego przesyłania.

files:writePrzesyłanie, aktualizowanie i usuwanie własnych plików.

remote:writeTworzenie, anulowanie i ponawianie zadań zdalnych.

HTTP 429

Limity żądań

Limity obowiązują dla tokenu i adresu IP. Aktywny limit znajduje się w nagłówkach i nie może przekraczać 60 żądań na minutę.

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Retry-After: 12
X-Request-ID: 2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda

Po HTTP 429 odczekaj czas wskazany przez Retry-After.

Pierwsze kroki

Informacje o koncie

Zwraca konto, liczbę plików, użycie pamięci i liczniki zadań zdalnych.

GET /account

Parametry

Brak parametrów żądania.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Przykładowa odpowiedź

200 JSON

{
  "success": true,
  "data": {
    "id": "rk9zKY45m0lY",
    "username": "example_user",
    "email": "[email protected]",
    "status": true,
    "files": 20,
    "storage_bytes": 1846721934,
    "remote_jobs": {
      "pending": 0,
      "running": 0,
      "completed": 1,
      "failed": 0
    }
  }
}

Pliki

Lista plików

Zwraca stronicowaną listę plików. Parametr search filtruje według nazwy.

GET /files

Parametry

Pole	Typ	Wymagane	Opis
`search`	string	Opcjonalne	Filter by name or stored filename. Maximum 255 characters.
`page`	integer	Opcjonalne	Pagination page. Minimum 1.
`per_page`	integer	Opcjonalne	Results per page. Default 25, maximum 100.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/files?search=sample&per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Przykładowa odpowiedź

200 JSON

{
  "success": true,
  "data": [
    {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "filename": "sample-video.mp4",
      "mime": "video/mp4",
      "extension": "mp4",
      "size_bytes": 1520849,
      "visibility": "public",
      "password_protected": false,
      "allow_online_watch": true,
      "downloads": 0,
      "stream_views": 0,
      "urls": {
        "page": "https://filemoon.org/0JgG7vRZzoYW/file",
        "watch": "https://filemoon.org/0JgG7vRZzoYW/watch",
        "embed": "https://filemoon.org/0JgG7vRZzoYW/embed"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Pliki

Informacje o pliku

Zwraca własny plik na podstawie publicznego ID FileMoon.

GET /files/{id}

Parametry

Pole	Typ	Wymagane	Opis
`id`	string (path)	Tak	Public FileMoon file ID owned by the authenticated account.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Pliki

Status pliku i HLS

Zwraca informacje o pliku wraz ze statusem konwersji HLS.

GET /files/{id}/status

Parametry

Pole	Typ	Wymagane	Opis
`id`	string (path)	Tak	Public FileMoon file ID owned by the authenticated account.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Przykładowa odpowiedź

200 JSON

{
  "success": true,
  "data": {
    "file": {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "allow_online_watch": true
    },
    "conversion": {
      "status": "completed",
      "stage": "adaptive",
      "attempts": 1,
      "duration_seconds": 42,
      "error": null,
      "updated_at": "2026-07-18 19:20:00"
    }
  }
}

Pliki

Prześlij plik lokalny

Prześlij plik przez multipart/form-data. Pole file jest wymagane; visibility przyjmuje 1 lub 0.

POST /files/upload

Parametry

Pole	Typ	Wymagane	Opis
`file`	binary	Tak	Local file attached as multipart/form-data.
`visibility`	boolean	Opcjonalne	Use 1 for public or 0 for private.

Przykładowe żądanie

cURL

curl -sS -X POST "https://filemoon.org/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@/path/to/video.mp4" \
  -F "visibility=1"

Pliki

Aktualizuj plik

Zmień obsługiwane metadane. Wyślij tylko pola do zmiany.

PATCH /files/{id}

Parametry

Pole	Typ	Wymagane	Opis
`id`	string (path)	Tak	Public FileMoon file ID.
`name`	string	Opcjonalne	New file name. Maximum 255 characters.
`description`	string\|null	Opcjonalne	File description. Maximum 1000 characters.
`visibility`	boolean	Opcjonalne	Public or private visibility.
`allow_online_watch`	boolean	Opcjonalne	Enable or disable online video watch.
`password`	string\|null	Opcjonalne	Set, change or remove the file password.

Przykładowe żądanie

cURL

curl -sS -X PATCH "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-video-name",
    "description": "Updated through FileMoon API",
    "visibility": true,
    "allow_online_watch": true
  }'

Pliki

Usuń plik

Trwale usuwa plik i powiązane dane. Operacji nie można cofnąć.

DELETE /files/{id}

Parametry

Pole	Typ	Wymagane	Opis
`id`	string (path)	Tak	Public FileMoon file ID.

Przykładowe żądanie

cURL

curl -sS -X DELETE "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Zdalne przesyłanie

Utwórz zadania zdalne

Dodaj do kolejki jeden lub wiele adresów mediów. HTTP 202 oznacza przyjęcie do przetwarzania w tle.

Akceptuje publiczne bezpośrednie adresy HTTP/HTTPS do multimediów. Sieci prywatne, localhost, metadane chmury, niebezpieczne przekierowania, skrypty i odpowiedzi inne niż wideo są blokowane.

POST /remote-uploads

Parametry

Pole	Typ	Wymagane	Opis
`urls`	array<string>	Tak	One or more public direct HTTP/HTTPS media URLs.
`name`	string\|null	Opcjonalne	Custom file name. Maximum 240 characters.
`description`	string\|null	Opcjonalne	Description. Maximum 1000 characters.
`folder_id`	integer\|null	Opcjonalne	Folder ID owned by the authenticated user.
`visibility`	boolean	Opcjonalne	Public or private file.
`allow_online_watch`	boolean	Opcjonalne	Allow online video playback.
`password`	string\|null	Opcjonalne	Optional file password.
`blocked_countries`	array<string>	Opcjonalne	Two-letter country codes. Maximum 50 entries.

Przykładowe żądanie

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://cdn.example.com/video.mp4"],
    "name": "remote-video",
    "description": "Imported through FileMoon API",
    "visibility": true,
    "allow_online_watch": true,
    "blocked_countries": ["US", "GB"]
  }'

Przykładowa odpowiedź

202 JSON

{
  "success": true,
  "message": "Remote upload job(s) queued.",
  "data": [
    {
      "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
      "host": "cdn.example.com",
      "name": "remote-video",
      "status": "pending",
      "stage": "queued",
      "attempts": 0,
      "bytes_downloaded": 0,
      "bytes_total": null,
      "progress_percent": null,
      "error": null,
      "file_id": null
    }
  ]
}

Wartości statusu

pendingrunningcompletedfailedcancelled

Zdalne przesyłanie

Lista zadań zdalnych

Zwraca stronicowaną listę zadań konta.

GET /remote-uploads

Parametry

Pole	Typ	Wymagane	Opis
`page`	integer	Opcjonalne	Pagination page.
`per_page`	integer	Opcjonalne	Default 25, maximum 100.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads?per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Zdalne przesyłanie

Status zadania zdalnego

Zwraca postęp, etap, błędy oraz ID utworzonego pliku.

GET /remote-uploads/{id}

Parametry

Pole	Typ	Wymagane	Opis
`id`	UUID (path)	Tak	Remote-upload job ID.

Przykładowe żądanie

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads/d96f9d69-1d44-42eb-89e3-5a62b052e77d" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Przykładowa odpowiedź

200 JSON

{
  "success": true,
  "data": {
    "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
    "host": "cdn.example.com",
    "name": "remote-video",
    "status": "completed",
    "stage": "completed",
    "attempts": 1,
    "bytes_downloaded": 1520849,
    "bytes_total": 1520849,
    "progress_percent": 100,
    "error": null,
    "file_id": "0JgG7vRZzoYW"
  }
}

Zdalne przesyłanie

Anuluj zadanie

Anuluje zadanie oczekujące lub żąda anulowania zadania wykonywanego.

POST /remote-uploads/{id}/cancel

Parametry

Pole	Typ	Wymagane	Opis
`id`	UUID (path)	Tak	Remote-upload job ID.

Przykładowe żądanie

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Zdalne przesyłanie

Ponów zadanie

Resetuje zadanie zakończone błędem lub anulowane i umieszcza je ponownie w kolejce.

POST /remote-uploads/{id}/retry

Parametry

Pole	Typ	Wymagane	Opis
`id`	UUID (path)	Tak	Remote-upload job ID.

Przykładowe żądanie

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/retry" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

HTTP

Błędy i kody statusu

Błędy mają spójną strukturę JSON. Zachowaj request_id podczas kontaktu z pomocą.

401

UNAUTHENTICATED

Missing or invalid Bearer token.

403

TOKEN_DISABLED / TOKEN_EXPIRED

Token disabled, expired, IP blocked or missing permission.

404

NOT_FOUND

Owned file or remote job could not be found.

409

REMOTE_JOB_NOT_CANCELLABLE

The job can no longer be cancelled.

422

VALIDATION_ERROR

Request fields or uploaded file are invalid.

429

RATE_LIMITED

Too many requests. Use Retry-After.

503

API_DISABLED

The administrator temporarily disabled the API.

Przykładowa odpowiedź

Error JSON

{
  "success": false,
  "error": {
    "code": "TOKEN_ABILITY_DENIED",
    "message": "The token does not have the required permission."
  },
  "request_id": "2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda"
}

Dokumentacja

Wymagania bezpieczeństwa

Stosuj te zasady podczas integracji z API FileMoon.

Przechowuj tokeny na zaufanym serwerze i natychmiast unieważniaj ujawnione tokeny.

Nadawaj tylko minimalne wymagane uprawnienia.

Ogranicz token do zaufanych adresów IP lub CIDR, jeśli to możliwe.

Przesyłaj wyłącznie treści własne lub autoryzowane.

cURL · PHP · JavaScript

Przykłady klientów

Minimalne przykłady cURL, PHP i JavaScript po stronie serwera.

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

PHP 8+

<?php
$token = getenv('FILEMOON_API_TOKEN');

$ch = curl_init('https://filemoon.org/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400) {
    throw new RuntimeException($data['error']['message'] ?? 'API request failed');
}
print_r($data);

Node.js / Server-side JS

const token = process.env.FILEMOON_API_TOKEN;

const response = await fetch('https://filemoon.org/api/v1/account', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data?.error?.message || 'API request failed');
}
console.log(data);