Spaces:

thanhkt
/

t2m

Configuration error

t2m

File size: 34,768 Bytes

50a7bf0

# T2M API Documentation

## Overview

This document provides comprehensive documentation for the T2M (Text-to-Media) API endpoints. The API is organized into several modules: Authentication, Files, Jobs, System, and Videos.

## Base URL

```

https://your-api-domain.com/api/v1

```

## Authentication

Most endpoints require authentication. Include the authorization token in the request headers:

```

Authorization: Bearer <your-token>

```

**Public endpoints** (no authentication required):

- `GET /auth/health`
- `GET /system/health`

**Optional authentication** (enhanced data for authenticated users):

- All other `/system/*` endpoints

## Common Response Formats

### Success Response

```json

{

  "success": true,

  "data": {

    "id": "12345",

    "status": "completed"

  },

  "message": "Operation completed successfully"

}

```

### Error Response

```json

{

  "success": false,

  "error": {

    "code": "AUTH_INVALID",

    "details": "Token has expired or is malformed"

  }

}

```

### Pagination Format

```json

{

  "success": true,

  "data": {

    "items": [...],

    "pagination": {

      "page": 1,

      "items_per_page": 20,

      "total_items": 150,

      "total_pages": 8,

      "has_next": true,

      "has_previous": false,

      "next_page": 2,

      "previous_page": null

    }

  }

}

```

## Authentication Endpoints

### Health Check

- **Endpoint**: `GET /auth/health`
- **Description**: Check authentication service health
- **Authentication**: Not required
- **Response**: Service health status
- **Example Response**:

```json

{

  "status": "healthy",

  "clerk": {

    "status": "healthy",

    "response_time": "45ms",

    "last_check": "2024-01-15T10:30:00Z"

  },

  "message": "Authentication service health check completed"

}

```

### Get Authentication Status

- **Endpoint**: `GET /auth/status`
- **Description**: Get current user authentication status
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Authentication status and user info
- **Example Response (Authenticated)**:

```json

{

  "authenticated": true,

  "user_id": "user_12345",

  "email": "[email protected]",

  "email_verified": true,

  "request_context": {

    "path": "/auth/status",

    "method": "GET",

    "client_ip": "192.168.1.100"

  }

}

```

- **Example Response (Not Authenticated)**:

```json

{

  "authenticated": false,

  "message": "No authentication provided",

  "request_context": {

    "path": "/auth/status",

    "method": "GET",

    "client_ip": "192.168.1.100"

  }

}

```

### Get Current User Profile

- **Endpoint**: `GET /auth/me`
- **Description**: Get authenticated user's profile information
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: User profile data
- **Example Response**:

```json

{

  "id": "user_12345",

  "username": "john_doe",

  "full_name": "John Doe",

  "email": "[email protected]",

  "image_url": "https://example.com/avatar.jpg",

  "email_verified": true,

  "created_at": "2024-01-01T00:00:00Z",

  "last_sign_in_at": "2024-01-15T10:30:00Z"

}

```

**Note**: `created_at` and `last_sign_in_at` fields may be `null` if not available from the authentication provider.

### Get User Permissions

- **Endpoint**: `GET /auth/permissions`
- **Description**: Get user's permissions and access levels
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: User permissions and role information
- **Example Response**:

```json

{

  "user_id": "user_12345",

  "role": "USER",

  "permissions": [

    "read_files",

    "upload_files",

    "generate_videos"

  ],

  "access_level": "standard"

}

```

### Test Protected Endpoint

- **Endpoint**: `GET /auth/test-protected`
- **Description**: Test endpoint for authenticated users
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: Test response with user ID
- **Example Response**:

```json

{

  "message": "Successfully accessed protected endpoint",

  "user_id": "user_12345",

  "timestamp": "2024-01-15T10:30:00Z"

}

```

### Test Verified Endpoint

- **Endpoint**: `GET /auth/test-verified`
- **Description**: Test endpoint for verified users only
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: Test response for verified users
- **Example Response**:

```json

{

  "message": "Successfully accessed verified user endpoint",

  "user_id": "user_12345",

  "email": "[email protected]",

  "email_verified": true,

  "timestamp": "2024-01-15T10:30:00Z"

}

```

### Verify Token

- **Endpoint**: `POST /auth/verify`
- **Description**: Verify authentication token validity
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: Token verification status
- **Example Response**:

```json

{

  "verified": true,

  "user_id": "user_12345",

  "email": "[email protected]",

  "email_verified": true,

  "message": "Token verified successfully"

}

```

## File Management Endpoints

### Upload Single File

- **Endpoint**: `POST /files/upload`
- **Description**: Upload a single file
- **Headers**:
  - `Authorization: Bearer <token>` (required)
  - `Content-Type: multipart/form-data`
- **Parameters**:
  - `file` (file, required): File to upload
  - `file_type` (string, optional): File type category
  - `subdirectory` (string, optional): Target subdirectory
  - `description` (string, optional): File description
- **Response**: File upload confirmation with file ID

### Batch Upload Files

- **Endpoint**: `POST /files/batch-upload`
- **Description**: Upload multiple files at once
- **Headers**:
  - `Authorization: Bearer <token>` (required)
  - `Content-Type: multipart/form-data`
- **Parameters**:
  - `files` (file[], required): Files to upload
  - `file_type` (string, optional): File type for all files
  - `subdirectory` (string, optional): Subdirectory for all files
  - `description` (string, optional): Description for all files
- **Response**: Batch upload results

### List Files

- **Endpoint**: `GET /files`
- **Description**: List user's files with pagination and filtering
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Query Parameters**:

| Name             | Type    | Required | Default | Description                                         |
| ---------------- | ------- | -------- | ------- | --------------------------------------------------- |
| `file_type`      | string  | no       | -       | Filter by file type (document, image, video, audio) |
| `page`           | integer | no       | 1       | Page number (≥1)                                    |
| `items_per_page` | integer | no       | 20      | Items per page (1-100)                              |

- **Response**: Paginated list of files
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "items": [

      {

        "id": "file_123456",

        "filename": "document.pdf",

        "size": 2048576,

        "file_type": "document",

        "created_at": "2024-01-15T10:30:00Z"

      }

    ],

    "pagination": {

      "page": 1,

      "items_per_page": 20,

      "total_items": 150,

      "total_pages": 8,

      "has_next": true

    }

  }

}

```

### Get File Details

- **Endpoint**: `GET /files/{file_id}`
- **Description**: Get comprehensive file information including content details and metadata
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Response**: Complete file details
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "id": "file_123456",

    "filename": "document.pdf",

    "size": 2048576,

    "content_type": "application/pdf",

    "file_type": "document",

    "subdirectory": "uploads/2024",

    "description": "Important document",

    "created_at": "2024-01-15T10:30:00Z",

    "updated_at": "2024-01-15T10:30:00Z",

    "download_count": 5,

    "metadata": {

      "pages": 10,

      "author": "John Doe",

      "creation_date": "2024-01-15"

    }

  }

}

```

### Get File Metadata

- **Endpoint**: `GET /files/{file_id}/metadata`
- **Description**: Get file metadata and technical information only
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Response**: File metadata only
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "content_type": "application/pdf",

    "size": 2048576,

    "checksum": "sha256:abc123...",

    "metadata": {

      "pages": 10,

      "author": "John Doe",

      "creation_date": "2024-01-15"

    }

  }

}

```

### Download File

- **Endpoint**: `GET /files/{file_id}/download`
- **Description**: Download file content
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Query Parameters**:
  - `inline` (boolean, default: false): Serve inline instead of attachment
- **Response**: File content

### Stream File

- **Endpoint**: `GET /files/{file_id}/stream`
- **Description**: Stream file content
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Query Parameters**:
  - `quality` (string, default: "auto"): Stream quality
- **Response**: Streamed file content

### Get File Thumbnail

- **Endpoint**: `GET /files/{file_id}/thumbnail`
- **Description**: Get file thumbnail
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Query Parameters**:
  - `size` (string, default: "medium"): Thumbnail size (small|medium|large)
- **Response**: Thumbnail image

### Get File Analytics

- **Endpoint**: `GET /files/{file_id}/analytics`
- **Description**: Get file usage analytics
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Response**: File analytics data

### Delete File

- **Endpoint**: `DELETE /files/{file_id}`
- **Description**: Delete a file
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `file_id` (string, required): Unique file identifier
- **Response**: Deletion confirmation

### Get File Statistics

- **Endpoint**: `GET /files/stats`
- **Description**: Get user's file statistics
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Response**: File usage statistics

### Cleanup Files

- **Endpoint**: `POST /files/cleanup`
- **Description**: Cleanup files based on criteria
- **Headers**:
  - `Authorization: Bearer <token>` (required)
  - `Content-Type: application/json`
- **Request Body**: File cleanup criteria
- **Response**: Cleanup results

### Secure File Access

- **Endpoint**: `GET /files/secure/{file_id}`
- **Description**: Access files via signed URLs
- **Query Parameters**:
  - `user_id` (string, required): User ID from signed URL
  - `expires` (string, required): Expiration timestamp
  - `signature` (string, required): URL signature
  - `file_type` (string, optional): File type
  - `inline` (string, default: "false"): Serve inline
  - `size` (string, optional): Thumbnail size
  - `quality` (string, optional): Stream quality
- **Response**: Secure file access

## Job Management Endpoints

### List Jobs

- **Endpoint**: `GET /jobs`
- **Description**: List user's jobs with pagination and filtering
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Query Parameters**: Pagination and filtering parameters
- **Response**: Paginated list of jobs

### Get Job Details

- **Endpoint**: `GET /jobs/{job_id}`
- **Description**: Get comprehensive job information including status, progress, and results
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Response**: Complete job details and status
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "id": "job_789012",

    "type": "video_generation",

    "status": "completed",

    "progress": 100,

    "created_at": "2024-01-15T10:30:00Z",

    "started_at": "2024-01-15T10:30:05Z",

    "completed_at": "2024-01-15T10:35:30Z",

    "duration": 325,

    "parameters": {

      "prompt": "A beautiful sunset over mountains",

      "duration": 10,

      "quality": "1080p"

    },

    "result": {

      "file_id": "video_456789",

      "file_size": 15728640,

      "thumbnail_url": "/videos/job_789012/thumbnail"

    },

    "error": null

  }

}

```

### Get Job Logs

- **Endpoint**: `GET /jobs/{job_id}/logs`
- **Description**: Get job execution logs with filtering and pagination
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Query Parameters**:

| Name     | Type    | Required | Default | Description                                       |
| -------- | ------- | -------- | ------- | ------------------------------------------------- |
| `limit`  | integer | no       | 100     | Maximum log entries (1-1000)                      |
| `offset` | integer | no       | 0       | Log entries to skip (≥0)                          |
| `level`  | string  | no       | -       | Filter by log level (DEBUG, INFO, WARNING, ERROR) |

- **Response**: Job logs with metadata
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "logs": [

      {

        "timestamp": "2024-01-15T10:30:15Z",

        "level": "INFO",

        "message": "Video processing started",

        "details": {

          "step": "initialization",

          "progress": 0

        }

      },

      {

        "timestamp": "2024-01-15T10:30:45Z",

        "level": "INFO",

        "message": "Processing frame 100/1000",

        "details": {

          "step": "rendering",

          "progress": 10

        }

      }

    ],

    "total_logs": 250,

    "has_more": true

  }

}

```

### Cancel Job

- **Endpoint**: `POST /jobs/{job_id}/cancel`
- **Description**: Cancel a running job
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Response**: Cancellation confirmation

### Delete Job

- **Endpoint**: `DELETE /jobs/{job_id}`
- **Description**: Delete a job and its data
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Response**: Deletion confirmation

## System Monitoring Endpoints

### System Health Check

- **Endpoint**: `GET /system/health`
- **Description**: Get overall system health status
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: System health metrics

### System Metrics

- **Endpoint**: `GET /system/metrics`
- **Description**: Get detailed system metrics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: System performance metrics

### Queue Status

- **Endpoint**: `GET /system/queue`
- **Description**: Get job queue status and statistics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Queue status and metrics

### Cache Information

- **Endpoint**: `GET /system/cache`
- **Description**: Get cache status and information
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Cache metrics and status

### Cache Metrics

- **Endpoint**: `GET /system/cache/metrics`
- **Description**: Get detailed cache metrics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Cache performance metrics

### Cache Report

- **Endpoint**: `GET /system/cache/report`
- **Description**: Get comprehensive cache report
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Detailed cache report

### Performance Summary

- **Endpoint**: `GET /system/performance`
- **Description**: Get system performance summary
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Query Parameters**:
  - `hours` (integer, default: 1): Time range in hours
- **Response**: Performance summary

### Connection Statistics

- **Endpoint**: `GET /system/connections`
- **Description**: Get connection statistics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Connection metrics

### Async Statistics

- **Endpoint**: `GET /system/async`
- **Description**: Get asynchronous processing statistics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Async processing metrics

### Deduplication Statistics

- **Endpoint**: `GET /system/deduplication`
- **Description**: Get deduplication statistics
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Deduplication metrics

### Invalidate Cache

- **Endpoint**: `POST /system/cache/invalidate`
- **Description**: Invalidate cache entries
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Query Parameters**:
  - `pattern` (string, optional): Cache key pattern
  - `user_id` (string, optional): User-specific cache
- **Response**: Cache invalidation results

### Warm Cache

- **Endpoint**: `POST /system/cache/warm`
- **Description**: Pre-warm cache with frequently accessed data
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Cache warming results

### Optimize Performance

- **Endpoint**: `POST /system/optimize`
- **Description**: Trigger system performance optimization
- **Headers**:
  - `Authorization: Bearer <token>` (optional)
- **Response**: Optimization results

## Video Processing Endpoints

### Generate Video

- **Endpoint**: `POST /videos/generate`
- **Description**: Create a new video generation job
- **Headers**:
  - `Authorization: Bearer <token>` (required)
  - `Content-Type: application/json`
- **Request Body**: Job creation parameters
- **Response**: Job creation confirmation with job ID

### Get Job Status

- **Endpoint**: `GET /videos/{job_id}/status`
- **Description**: Get video generation job status
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Response**: Job status and progress

### Download Video

- **Endpoint**: `GET /videos/{job_id}/download`
- **Description**: Download generated video
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Query Parameters**:
  - `inline` (boolean, default: false): Serve inline instead of attachment
- **Response**: Video file content

### Stream Video

- **Endpoint**: `GET /videos/{job_id}/stream`
- **Description**: Stream generated video
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Query Parameters**:
  - `quality` (string, default: "auto"): Stream quality (auto|720p|1080p)
- **Response**: Streamed video content

### Get Video Metadata

- **Endpoint**: `GET /videos/{job_id}/metadata`
- **Description**: Get comprehensive video metadata and technical information
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Response**: Detailed video metadata
- **Example Response**:

```json

{

  "success": true,

  "data": {

    "job_id": "job_789012",

    "video": {

      "duration": 10.5,

      "width": 1920,

      "height": 1080,

      "fps": 30,

      "bitrate": 5000000,

      "codec": "h264",

      "format": "mp4",

      "file_size": 15728640

    },

    "audio": {

      "codec": "aac",

      "bitrate": 128000,

      "sample_rate": 44100,

      "channels": 2

    },

    "generation": {

      "prompt": "A beautiful sunset over mountains",

      "model": "t2v-v2.1",

      "seed": 12345,

      "created_at": "2024-01-15T10:30:00Z"

    }

  }

}

```

### Get Video Thumbnail

- **Endpoint**: `GET /videos/{job_id}/thumbnail`
- **Description**: Get video thumbnail
- **Headers**:
  - `Authorization: Bearer <token>` (required)
- **Path Parameters**:
  - `job_id` (string, required): Unique job identifier
- **Query Parameters**:
  - `size` (string, default: "medium"): Thumbnail size (small|medium|large)
- **Response**: Video thumbnail image

## Error Handling

### Error Codes

| Code                  | HTTP Status | Description                     |
| --------------------- | ----------- | ------------------------------- |
| `AUTH_REQUIRED`       | 401         | Authentication required         |
| `AUTH_INVALID`        | 401         | Invalid authentication token    |
| `AUTH_EXPIRED`        | 401         | Authentication token expired    |
| `PERMISSION_DENIED`   | 403         | Insufficient permissions        |
| `RESOURCE_NOT_FOUND`  | 404         | Requested resource not found    |
| `VALIDATION_ERROR`    | 400         | Request validation failed       |
| `RATE_LIMIT_EXCEEDED` | 429         | Rate limit exceeded             |
| `SERVER_ERROR`        | 500         | Internal server error           |
| `SERVICE_UNAVAILABLE` | 503         | Service temporarily unavailable |

### Error Response Examples

**Invalid Authentication (401)**

```json

{

  "success": false,

  "error": {

    "code": "AUTH_INVALID",

    "details": "Token has expired or is malformed"

  }

}

```

**Resource Not Found (404)**

```json

{

  "success": false,

  "error": {

    "code": "RESOURCE_NOT_FOUND",

    "message": "File not found",

    "details": "File with ID 'file_123456' does not exist or you don't have access"

  }

}

```

**Validation Error (400)**

```json

{

  "success": false,

  "error": {

    "code": "VALIDATION_ERROR",

    "message": "Request validation failed",

    "details": {

      "file_type": [

        "Invalid file type. Must be one of: document, image, video, audio"

      ],

      "page": ["Page must be greater than 0"]

    }

  }

}

```

**Rate Limit Exceeded (429)**

```json

{

  "success": false,

  "error": {

    "code": "RATE_LIMIT_EXCEEDED",

    "message": "Rate limit exceeded",

    "details": "You have exceeded the limit of 100 uploads per hour. Try again in 45 minutes."

  }

}

```

## Rate Limits

- **General API**: 1000 requests per hour per user
- **File Upload**: 100 uploads per hour per user
- **Video Generation**: 10 jobs per hour per user
- **System Endpoints**: 500 requests per hour per user

## Code Examples

### cURL Examples

**Upload a file**

```bash

curl -X POST "https://api.example.com/api/v1/files/upload" \

  -H "Authorization: Bearer your-token-here" \

  -F "[email protected]" \

  -F "file_type=document" \

  -F "description=Sample document"

```

**Generate video**

```bash

curl -X POST "https://api.example.com/api/v1/videos/generate" \

  -H "Authorization: Bearer your-token-here" \

  -H "Content-Type: application/json" \

  -d '{

    "prompt": "A beautiful sunset over mountains",

    "duration": 10,

    "quality": "1080p"

  }'

```

**Get job status**

```bash

curl -X GET "https://api.example.com/api/v1/jobs/job_789012" \

  -H "Authorization: Bearer your-token-here"

```

**Get system metrics**

```bash

curl -X GET "https://api.example.com/api/v1/system/metrics" \

  -H "Authorization: Bearer your-token-here"

```

### Python Examples

**File Management**

```python

import requests



headers = {"Authorization": "Bearer your-token-here"}

base_url = "https://api.example.com/api/v1"



# Upload file

with open("example.txt", "rb") as f:

    files = {"file": f}

    data = {"file_type": "document", "description": "Sample document"}

    response = requests.post(f"{base_url}/files/upload", headers=headers, files=files, data=data)

    file_data = response.json()

    print(f"File uploaded: {file_data['data']['id']}")



# List files

response = requests.get(f"{base_url}/files", headers=headers, params={"page": 1, "items_per_page": 10})

files = response.json()

print(f"Found {files['data']['pagination']['total_items']} files")

```

**Job Management**

```python

# Get job logs

job_id = "job_789012"

response = requests.get(f"{base_url}/jobs/{job_id}/logs", headers=headers, params={"limit": 50, "level": "INFO"})

logs = response.json()

print(f"Retrieved {len(logs['data']['logs'])} log entries")



# Cancel job

response = requests.post(f"{base_url}/jobs/{job_id}/cancel", headers=headers)

if response.json()['success']:

    print("Job cancelled successfully")

```

**Video Processing**

```python

# Generate video

job_data = {

    "prompt": "A beautiful sunset over mountains",

    "duration": 10,

    "quality": "1080p"

}

response = requests.post(f"{base_url}/videos/generate", headers=headers, json=job_data)

job = response.json()

job_id = job['data']['job_id']

print(f"Video generation started: {job_id}")



# Check status

response = requests.get(f"{base_url}/videos/{job_id}/status", headers=headers)

status = response.json()

print(f"Job status: {status['data']['status']} ({status['data']['progress']}%)")

```

**System Monitoring**

```python

# Get system metrics

response = requests.get(f"{base_url}/system/metrics", headers=headers)

metrics = response.json()

print(f"CPU usage: {metrics['data']['cpu_usage']}%")

print(f"Memory usage: {metrics['data']['memory_usage']}%")



# Get queue status

response = requests.get(f"{base_url}/system/queue", headers=headers)

queue = response.json()

print(f"Jobs in queue: {queue['data']['pending_jobs']}")

```

### JavaScript Examples

**File Management**

```javascript

const headers = {

  Authorization: "Bearer your-token-here",

};

const baseUrl = "https://api.example.com/api/v1";



// Upload file

const formData = new FormData();

formData.append("file", fileInput.files[0]);

formData.append("file_type", "document");

formData.append("description", "Sample document");



fetch(`${baseUrl}/files/upload`, {

  method: "POST",

  headers: headers,

  body: formData,

})

  .then((response) => response.json())

  .then((data) => console.log("File uploaded:", data.data.id));



// List files with pagination

fetch(`${baseUrl}/files?page=1&items_per_page=10`, {

  headers: headers,

})

  .then((response) => response.json())

  .then((data) =>

    console.log(`Found ${data.data.pagination.total_items} files`)

  );

```

**Job Management**

```javascript

// Get job logs

const jobId = "job_789012";

fetch(`${baseUrl}/jobs/${jobId}/logs?limit=50&level=INFO`, {

  headers: headers,

})

  .then((response) => response.json())

  .then((data) =>

    console.log(`Retrieved ${data.data.logs.length} log entries`)

  );



// Cancel job

fetch(`${baseUrl}/jobs/${jobId}/cancel`, {

  method: "POST",

  headers: headers,

})

  .then((response) => response.json())

  .then((data) => {

    if (data.success) console.log("Job cancelled successfully");

  });

```

**Video Processing**

```javascript

// Generate video

const jobData = {

  prompt: "A beautiful sunset over mountains",

  duration: 10,

  quality: "1080p",

};



fetch(`${baseUrl}/videos/generate`, {

  method: "POST",

  headers: { ...headers, "Content-Type": "application/json" },

  body: JSON.stringify(jobData),

})

  .then((response) => response.json())

  .then((data) => {

    const jobId = data.data.job_id;

    console.log("Video generation started:", jobId);



    // Poll for status

    const checkStatus = () => {

      fetch(`${baseUrl}/videos/${jobId}/status`, { headers })

        .then((response) => response.json())

        .then((status) => {

          console.log(

            `Status: ${status.data.status} (${status.data.progress}%)`

          );

          if (status.data.status === "processing") {

            setTimeout(checkStatus, 5000); // Check again in 5 seconds

          }

        });

    };

    checkStatus();

  });

```

**System Monitoring**

```javascript

// Get system metrics

fetch(`${baseUrl}/system/metrics`, { headers })

  .then((response) => response.json())

  .then((data) => {

    console.log(`CPU usage: ${data.data.cpu_usage}%`);

    console.log(`Memory usage: ${data.data.memory_usage}%`);

  });



// Get queue status

fetch(`${baseUrl}/system/queue`, { headers })

  .then((response) => response.json())

  .then((data) => console.log(`Jobs in queue: ${data.data.pending_jobs}`));

```

## Support

For API support and questions, please contact:

- Email: [email protected]
- Documentation: https://docs.example.com
- Status Page: https://status.example.com

## Webhooks

The T2M API supports webhook notifications for long-running operations like video generation.

### Webhook Configuration

Configure webhook URLs in your account settings or via the API:

```bash

curl -X POST "https://api.example.com/api/v1/webhooks" \

  -H "Authorization: Bearer your-token-here" \

  -H "Content-Type: application/json" \

  -d '{

    "url": "https://your-app.com/webhooks/t2m",

    "events": ["job.completed", "job.failed"],

    "secret": "your-webhook-secret"

  }'

```

### Webhook Events

| Event           | Description                     |
| --------------- | ------------------------------- |
| `job.started`   | Job processing has begun        |
| `job.progress`  | Job progress update (every 10%) |
| `job.completed` | Job completed successfully      |
| `job.failed`    | Job failed with error           |
| `job.cancelled` | Job was cancelled               |

### Webhook Payload Example

**Job Completed**

```json

{

  "event": "job.completed",

  "timestamp": "2024-01-15T10:35:30Z",

  "data": {

    "job_id": "job_789012",

    "type": "video_generation",

    "status": "completed",

    "result": {

      "file_id": "video_456789",

      "download_url": "https://api.example.com/api/v1/videos/job_789012/download",

      "thumbnail_url": "https://api.example.com/api/v1/videos/job_789012/thumbnail"

    }

  }

}

```

### Webhook Security

Verify webhook authenticity using the signature header:

```python

import hmac

import hashlib



def verify_webhook(payload, signature, secret):

    expected = hmac.new(

        secret.encode('utf-8'),

        payload.encode('utf-8'),

        hashlib.sha256

    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)



# In your webhook handler

signature = request.headers.get('X-T2M-Signature')

if verify_webhook(request.body, signature, webhook_secret):

    # Process webhook

    pass

```

## Advanced Features

### Batch Operations

**Batch File Upload**

```bash

curl -X POST "https://api.example.com/api/v1/files/batch-upload" \

  -H "Authorization: Bearer your-token-here" \

  -F "[email protected]" \

  -F "[email protected]" \

  -F "[email protected]" \

  -F "file_type=document"

```

### Signed URLs for Secure Access

Generate temporary signed URLs for file access without authentication:

```python

# Request signed URL

response = requests.post(f"{base_url}/files/{file_id}/signed-url",

                        headers=headers,

                        json={"expires_in": 3600})  # 1 hour

signed_url = response.json()['data']['url']



# Use signed URL (no auth required)

file_response = requests.get(signed_url)

```

### Streaming and Quality Options

**Video Streaming with Quality Selection**

```bash

# Stream in different qualities

curl "https://api.example.com/api/v1/videos/job_789012/stream?quality=720p" \

  -H "Authorization: Bearer your-token-here"

```

**Thumbnail Sizes**

```bash

# Get different thumbnail sizes

curl "https://api.example.com/api/v1/videos/job_789012/thumbnail?size=large" \

  -H "Authorization: Bearer your-token-here"

```

## Performance Optimization

### Caching

The API implements intelligent caching. Use these endpoints to manage cache:

```bash

# Warm cache for better performance

curl -X POST "https://api.example.com/api/v1/system/cache/warm" \

  -H "Authorization: Bearer your-token-here"



# Invalidate specific cache patterns

curl -X POST "https://api.example.com/api/v1/system/cache/invalidate" \

  -H "Authorization: Bearer your-token-here" \

  -d "pattern=user:123:*"

```

### Request Optimization

- Use pagination for large datasets
- Implement client-side caching for frequently accessed data
- Use appropriate quality settings for streaming
- Batch operations when possible

## Monitoring and Analytics

### System Health Monitoring

```bash

# Check overall system health

curl "https://api.example.com/api/v1/system/health"



# Get detailed performance metrics

curl "https://api.example.com/api/v1/system/performance?hours=24" \

  -H "Authorization: Bearer your-token-here"

```

### File Analytics

Track file usage and performance:

```bash

curl "https://api.example.com/api/v1/files/file_123456/analytics" \

  -H "Authorization: Bearer your-token-here"

```

## Migration Guide

### From v1.0 to v1.1

**Breaking Changes:**

- `GET /files/{id}/info` is now `GET /files/{id}` (consolidated endpoints)
- Error response format now includes `details` field
- Pagination format standardized across all endpoints

**New Features:**

- Webhook support for job notifications
- Batch file operations
- Enhanced error details
- Signed URL support

**Migration Steps:**

1. Update endpoint URLs for file info
2. Update error handling to use new format
3. Implement webhook handlers for better UX
4. Use batch operations for improved performance

## Changelog

### v1.1.0 (2024-01-15)

- Added webhook support
- Introduced batch file operations
- Enhanced error responses with details
- Added signed URL generation
- Improved pagination format
- Added system performance endpoints

### v1.0.0 (2023-12-01)

- Initial API release
- Basic CRUD operations for files
- Video generation capabilities
- Job management system
- System monitoring endpoints