Hugging Face's logo

Spaces:
thanhkt
/
t2m
Configuration error

App Files Community
t2m / API_DOCUMENTATION.md
thanhkt's picture
thanhkt
implement core api
50a7bf0
preview code
|
raw
history blame contribute delete
34.8 kB

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 

{
  "success": true,
  "data": {
    "id": "12345",
    "status": "completed"
  },
  "message": "Operation completed successfully"
}

Error Response 

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID",
    "details": "Token has expired or is malformed"
  }
}

Pagination Format 

{
  "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:
{
  "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):
{
  "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):
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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:
{
  "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)

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID",
    "details": "Token has expired or is malformed"
  }
}

Resource Not Found (404)

{
  "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)

{
  "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)

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

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

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

curl -X GET "https://api.example.com/api/v1/jobs/job_789012" \
  -H "Authorization: Bearer your-token-here"

Get system metrics

curl -X GET "https://api.example.com/api/v1/system/metrics" \
  -H "Authorization: Bearer your-token-here"

Python Examples

File Management

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

# 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

# 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

# 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

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

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

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

// 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:

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:

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

{
  "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:

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

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:

# 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

# 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

# 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:

# 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 

# 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:

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