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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```json
{
  "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:**
```bash
curl "http://localhost:5000/list/generated/5"
```

**Response:**
```json
{
  "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:

```json
{
  "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
```python
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
```javascript
// 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:

```bash
python test_download_api.py
```

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