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"

Pliki

Premium Cast / HLS Playback

Create a temporary signed HLS playback URL for Google Cast, Chromecast, smart TV and external-player playback. This endpoint is available only to accounts with an active Premium subscription. The video must belong to the authenticated account and its HLS conversion must be ready. Signed playback URLs are valid for 4 hours. Premium Cast playback includes a 10 TB bandwidth allowance per account per calendar month. Cast HLS segment traffic is counted toward this allowance. When the monthly allowance is reached, new Cast sessions and signed HLS playback requests are blocked with HTTP 429 until the next calendar month.

POST /files/{id}/cast

Parametry

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

Przykładowe żądanie

cURL

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

Przykładowa odpowiedź

200 JSON

{
  "success": true,
  "data": {
    "type": "hls",
    "playback_url": "https://filemoon.org/api/v1/cast/0JgG7vRZzoYW/master.m3u8?expires=1790179002&signature=EXAMPLE_SIGNATURE",
    "expires_at": "2026-09-23T15:56:42+00:00",
    "expires_in": 14400
  }
}

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 250 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);