digital_human_backend/function/DOWNLOAD_API_README.md

Download API Documentation

This document describes the download APIs added to your Flask application for downloading video and audio files from the system.

Available Endpoints

1. Download Video File

Endpoint: GET /download/video/<filename>

Description: Download a video file from the system

Parameters:

• filename (path parameter): The name of the video file to download
• directory (query parameter, optional): Custom directory path (default: /mnt/docker/resource)

Example:

curl -O "http://localhost:5000/download/video/scene_one.mp4"
curl -O "http://localhost:5000/download/video/scene_one.mp4?directory=/custom/path"

Response:

• Success: File download with appropriate MIME type
• Error: JSON with error message and HTTP status code

---

2. Download Audio File

Endpoint: GET /download/audio/<filename>

Description: Download an audio file from the system

Parameters:

• filename (path parameter): The name of the audio file to download
• directory (query parameter, optional): Custom directory path (default: /mnt/docker/resource)

Example:

curl -O "http://localhost:5000/download/audio/output.wav"
curl -O "http://localhost:5000/download/audio/output.wav?directory=/custom/path"

---

3. Download Generated Video

Endpoint: GET /download/generated/video/<uuid>

Description: Download a generated video file by UUID

Parameters:

• uuid (path parameter): The unique identifier for the generated video
• task_id (query parameter, optional): Alternative task identifier

Example:

curl -O "http://localhost:5000/download/generated/video/5"
curl -O "http://localhost:5000/download/generated/video/5?task_id=123"

---

4. Download Generated Audio

Endpoint: GET /download/generated/audio/<uuid>

Description: Download a generated audio file by UUID

Parameters:

• uuid (path parameter): The unique identifier for the generated audio

Example:

curl -O "http://localhost:5000/download/generated/audio/5"

---

5. List Available Files

Endpoint: GET /list/files

Description: List available files in the system for download

Parameters:

• directory (query parameter, optional): Directory to list files from (default: /mnt/docker/resource)
• type (query parameter, optional): Filter by file type - video, audio, or all (default: all)

Example:

curl "http://localhost:5000/list/files"
curl "http://localhost:5000/list/files?type=video"
curl "http://localhost:5000/list/files?type=audio&directory=/custom/path"

Response:

{
  "directory": "/mnt/docker/resource",
  "total_files": 3,
  "files": [
    {
      "filename": "scene_one.mp4",
      "size": 1048576,
      "type": "video",
      "modified": 1691234567,
      "download_url_video": "/download/video/scene_one.mp4",
      "download_url_audio": null
    },
    {
      "filename": "output.wav",
      "size": 524288,
      "type": "audio", 
      "modified": 1691234568,
      "download_url_video": null,
      "download_url_audio": "/download/audio/output.wav"
    }
  ]
}

---

6. List Generated Files by UUID

Endpoint: GET /list/generated/<uuid>

Description: List generated files for a specific UUID

Parameters:

• uuid (path parameter): The unique identifier to search for generated files

Example:

curl "http://localhost:5000/list/generated/5"

Response:

{
  "uuid": "5",
  "total_files": 2,
  "generated_files": [
    {
      "type": "audio",
      "filename": "5output.wav",
      "path": "/mnt/docker/resource/5output.wav",
      "download_url": "/download/generated/audio/5"
    },
    {
      "type": "video", 
      "filename": "5output.mp4",
      "path": "/mnt/docker/resource/5output.mp4",
      "download_url": "/download/generated/video/5"
    }
  ]
}

Error Responses

All endpoints return JSON error responses with appropriate HTTP status codes:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes:

• 200: Success
• 400: Bad request (invalid file type, etc.)
• 404: File not found
• 500: Internal server error

File Type Support

Video formats: .mp4, .avi, .mov, .mkv, .wmv, .flv, .webm

Audio formats: .wav, .mp3, .aac, .flac, .ogg, .m4a, .wma

Security Notes

• File paths are validated to prevent directory traversal attacks
• Only files with recognized video/audio extensions are downloadable
• Files must exist in the specified directory to be downloaded

Usage Examples

Python Example

import requests

# List all files
response = requests.get("http://localhost:5000/list/files")
files = response.json()

# Download a specific video
response = requests.get("http://localhost:5000/download/video/scene_one.mp4")
if response.status_code == 200:
    with open("downloaded_video.mp4", "wb") as f:
        f.write(response.content)

# Download generated audio by UUID
response = requests.get("http://localhost:5000/download/generated/audio/5")
if response.status_code == 200:
    with open("generated_audio.wav", "wb") as f:
        f.write(response.content)

JavaScript Example

// List files
fetch('/list/files')
  .then(response => response.json())
  .then(data => console.log(data));

// Download file
fetch('/download/video/scene_one.mp4')
  .then(response => response.blob())
  .then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'scene_one.mp4';
    a.click();
  });

Testing

Use the provided test script to verify the APIs:

python test_download_api.py

Make sure your Flask server is running on port 5000 before testing.