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