PHPeerTube - A PHP‑based federated video platform, inspired by PeerTube.

Copyright (C) 2025 Lucentinian Works Co Ltd

API example

Single-Shot Video Upload (for small files)

This API uploads the video in one call. Ideal for small files.

curl -i -X POST \
  -H "Authorization: Bearer eyJ..." \
  -F "video=@/path/to/your/video.mp4" \
  -F "title=My Awesome Video" \
  -F "description=A short description of my video" \
  -F "force=true" \ # Optional: Set to true to overwrite an existing video with the same info_hash
  http://phpeertube.ehehdada.com/me/videos

To upload a video file, send a POST request to the /videos endpoint with the video file, title, and description. Optionally, include force=true to overwrite an existing video with the same info_hash.

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Video uploaded successfully!",
  "videoId": 14,
  "userId": 4,
  "videoTitle": "beach",
  "videoDescription": "beach view",
  "durationInSeconds": 13,
  "generatedTorrentSnippet": "d8:announce39:http://phpeertube.ehehdada.com/announce13:announce-listll39:http://phpeertube.ehehdada..."
}

Example response for duplicate video without force=true:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": "Video with this info hash already exists. Use force=true to overwrite."
}

Chunked Video Upload (for large files with progress)

This method allows you to upload large video files in smaller chunks, providing better resilience and enabling progress tracking on the client side.

Step 1: Initialize the Upload Session

Start a new chunked upload session to get a unique uploadId. This uploadId will be used for all subsequent chunk and finalize requests.

POST /me/uploads/initialize

curl -i -X POST \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ \
    "originalFilename": "my_large_video.mp4", \
    "totalChunks": 10 \
  }' \
  http://phpeertube.ehehdada.com/me/uploads/initialize

Example successful response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "uploadId": "chunk_65xxxxxxx.xxxxxxxx",
  "message": "Upload session initialized."
}

Step 2: Upload Chunks Individually

Upload each chunk of the file using the uploadId obtained from the initialization step and the current chunkNumber. The raw binary content of the chunk should be sent as the request body.

POST /me/uploads/{uploadId}/chunk/{chunkNumber}

# Example for Chunk 0
curl -i -X POST \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@/path/to/your/chunk_0_of_video.bin" \
  http://phpeertube.ehehdada.com/me/uploads/chunk_65xxxxxxx.xxxxxxxx/chunk/0

# Example for Chunk 1
curl -i -X POST \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@/path/to/your/chunk_1_of_video.bin" \
  http://phpeertube.ehehdada.com/me/uploads/chunk_65xxxxxxx.xxxxxxxx/chunk/1

# ... repeat for all chunks up to totalChunks - 1

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uploadId":"chunk_69048cb1f3b369.38168159",
  "originalFilename":"my_large_video.mp4",
  "totalChunks":9,
  "receivedChunks":4,
  "status":"pending",
  "progress":44
}

Step 3: Finalize the Upload

Once all chunks have been successfully uploaded, call the finalize endpoint to trigger the reassembly of the file, torrent generation, and video metadata storage.

POST /me/uploads/{uploadId}/finalize

curl -i -X POST \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ \
    "title": "My Final Awesome Video", \
    "description": "This is the description for my large video."
  }' \
  http://phpeertube.ehehdada.com/me/uploads/finalize

Example successful response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "Video uploaded and processed successfully!",
  "videoId": 15,
  "infoHash": "661b6068bffe3d96510e98e0ceecf3aa97b82a99",
  "videoTitle": "chunked real estate test 3",
  "videoDescription": "testing uploading chunked video file",
  "categoryIds": []
}

Step 4: Get Upload Status (Optional)

You can optionally query the status of an ongoing or completed upload at any time using its uploadId.

GET /me/uploads/{uploadId}/status

curl -i -X GET \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  http://phpeertube.ehehdada.com/me/uploads/chunk_65xxxxxxx.xxxxxxxx/status

Example successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uploadId": "chunk_65xxxxxxx.xxxxxxxx",
  "originalFilename": "my_large_video.mp4",
  "totalChunks": 10,
  "receivedChunks": 5,
  "status": "pending",
  "progress": 50.0
}