FileMoon — Documentação da API FileMoon

FileMoon REST API

Introdução

A API FileMoon é uma API HTTP baseada em JSON para automatizar uploads, gerenciar arquivos da conta e importar URLs diretas de vídeo autorizadas.

URL base	`https://filemoon.org/api/v1`
Versão atual	`v1`
Content-Type	`application/json` / `multipart/form-data`

Security: Use HTTPS em todas as requisições. Nunca exponha tokens em código público, capturas, repositórios ou logs compartilhados.

Primeiros passos

Autenticação

Envie um token de acesso FileMoon no cabeçalho Authorization usando o esquema Bearer.

HTTP Headers

Authorization: Bearer YOUR_FILEMOON_TOKEN
Accept: application/json

Crie o token em Painel do Usuário → API & Remote Upload. O token completo aparece apenas uma vez.

Permissões do token

files:readLer conta, arquivos e status.

files:writeEnviar, atualizar e excluir arquivos da conta.

remote:writeCriar, cancelar e repetir tarefas remotas.

HTTP 429

Limites de requisição

Os limites são aplicados por token e IP. O limite ativo aparece nos cabeçalhos e não ultrapassa 60 requisições por minuto.

Response Headers

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

Após HTTP 429, aguarde o valor de Retry-After.

Primeiros passos

Informações da conta

Retorna conta, total de arquivos, uso de armazenamento e contadores remotos.

GET /account

Parâmetros

Nenhum parâmetro de requisição.

Exemplo de requisição

cURL

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

Exemplo de resposta

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

Arquivos

Listar arquivos

Retorna uma lista paginada. Use search para filtrar por nome.

GET /files

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`search`	string	Opcional	Filter by name or stored filename. Maximum 255 characters.
`page`	integer	Opcional	Pagination page. Minimum 1.
`per_page`	integer	Opcional	Results per page. Default 25, maximum 100.

Exemplo de requisição

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"

Exemplo de resposta

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

Arquivos

Informações do arquivo

Retorna um arquivo pelo ID público FileMoon.

GET /files/{id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon file ID owned by the authenticated account.

Exemplo de requisição

cURL

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

Arquivos

Status do arquivo e HLS

Retorna arquivo e status de conversão HLS.

GET /files/{id}/status

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon file ID owned by the authenticated account.

Exemplo de requisição

cURL

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

Exemplo de resposta

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

Arquivos

Enviar arquivo local

Envie com multipart/form-data. file é obrigatório; visibility aceita 1 ou 0.

POST /files/upload

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`file`	binary	Sim	Local file attached as multipart/form-data.
`visibility`	boolean	Opcional	Use 1 for public or 0 for private.

Exemplo de requisição

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"

Arquivos

List Video Subtitles

Retrieve subtitles attached to a video owned by your account. Results include language, label, default status and creation date. Authentication is required.

GET /files/{id}/subtitles

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon video ID owned by the authenticated user.

Exemplo de requisição

cURL

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

Exemplo de resposta

200 JSON

{
  "success": true,
  "data": {
    "file_id": 12345,
    "subtitles": [
      {
        "id": 22,
        "language_code": "ar",
        "label": "Arabic",
        "is_default": true,
        "created_at": "2026-10-13T14:00:00.000000Z"
      }
    ],
    "total": 1
  }
}

Arquivos

Upload Video Subtitle

Upload an SRT or WebVTT subtitle to a video owned by your account. Maximum upload size is 2 MB. SRT files are converted to WebVTT automatically. Uploading another subtitle with the same language code replaces the existing subtitle for that language. Use a supported language code from FileMoon.

POST /files/{id}/subtitles

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon video ID owned by the authenticated user.
`subtitle`	file	Sim	SRT or VTT subtitle file, maximum 2 MB.
`language_code`	string	Sim	Supported FileMoon subtitle language code, such as ar or en.
`label`	string	Opcional	Optional display label, maximum 80 characters.
`is_default`	boolean	Opcional	Set to 1 to make this subtitle the default.

Exemplo de requisição

cURL

curl -sS -X POST "https://filemoon.org/api/v1/files/VIDEO_ID/subtitles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "subtitle=@/path/to/arabic.vtt" \
  -F "language_code=ar" \
  -F "label=Arabic" \
  -F "is_default=1"

Exemplo de resposta

201 JSON

{
  "success": true,
  "data": {
    "id": 22,
    "language_code": "ar",
    "label": "Arabic",
    "is_default": true
  }
}

Arquivos

Atualizar arquivo

Altere metadados suportados. Envie apenas os campos necessários.

PATCH /files/{id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon file ID.
`name`	string	Opcional	New file name. Maximum 255 characters.
`description`	string\|null	Opcional	File description. Maximum 1000 characters.
`visibility`	boolean	Opcional	Public or private visibility.
`allow_online_watch`	boolean	Opcional	Enable or disable online video watch.
`password`	string\|null	Opcional	Set, change or remove the file password.

Exemplo de requisição

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

Arquivos

Excluir arquivo

Exclui permanentemente o arquivo e dados relacionados.

DELETE /files/{id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon file ID.

Exemplo de requisição

cURL

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

Arquivos

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

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	string (path)	Sim	Public FileMoon video ID owned by the authenticated Premium account.

Exemplo de requisição

cURL

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

Exemplo de resposta

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

Upload remoto

Criar tarefas remotas

Adicione uma ou mais URLs à fila. HTTP 202 confirma o processamento em segundo plano.

Aceita URLs públicas e diretas de mídia HTTP/HTTPS. Redes privadas, localhost, metadados de nuvem, redirecionamentos inseguros, scripts e respostas não-vídeo são bloqueados.

POST /remote-uploads

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`urls`	array<string>	Sim	One or more public direct HTTP/HTTPS media URLs.
`name`	string\|null	Opcional	Custom file name. Maximum 240 characters.
`description`	string\|null	Opcional	Description. Maximum 1000 characters.
`folder_id`	integer\|null	Opcional	Folder ID owned by the authenticated user.
`visibility`	boolean	Opcional	Public or private file.
`allow_online_watch`	boolean	Opcional	Allow online video playback.
`password`	string\|null	Opcional	Optional file password.
`blocked_countries`	array<string>	Opcional	Two-letter country codes. Maximum 250 entries.

Exemplo de requisição

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

Exemplo de resposta

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
    }
  ]
}

Valores de status

pendingrunningcompletedfailedcancelled

Upload remoto

Listar tarefas remotas

Retorna as tarefas remotas da conta com paginação.

GET /remote-uploads

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`page`	integer	Opcional	Pagination page.
`per_page`	integer	Opcional	Default 25, maximum 100.

Exemplo de requisição

cURL

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

Upload remoto

Status do upload remoto

Retorna progresso, etapa, erros e o ID do arquivo criado.

GET /remote-uploads/{id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	UUID (path)	Sim	Remote-upload job ID.

Exemplo de requisição

cURL

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

Exemplo de resposta

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

Upload remoto

Cancelar tarefa remota

Cancela uma tarefa pendente ou solicita o cancelamento de uma tarefa em execução.

POST /remote-uploads/{id}/cancel

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	UUID (path)	Sim	Remote-upload job ID.

Exemplo de requisição

cURL

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

Upload remoto

Repetir tarefa remota

Redefine uma tarefa com falha ou cancelada e a coloca novamente na fila.

POST /remote-uploads/{id}/retry

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`id`	UUID (path)	Sim	Remote-upload job ID.

Exemplo de requisição

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

Erros e códigos de status

Os erros usam uma estrutura JSON consistente. Guarde request_id para suporte.

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.

Exemplo de resposta

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

Referência

Requisitos de segurança

Aplique estas regras na integração.

Mantenha tokens em servidor confiável e revogue tokens expostos.

Use somente as permissões mínimas.

Restrinja tokens a IPs ou CIDR confiáveis quando possível.

Envie somente conteúdo próprio ou autorizado.

cURL · PHP · JavaScript

Exemplos de clientes

Exemplos mínimos de cURL, PHP e JavaScript no servidor.

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