Veedeo API V3 Specification

Version: 3.0 Release Date: September 17, 2025 Base URL: https://api.veedeo.dev/v3

Table of Contents

1. Overview
2. Authentication
3. Rate Limiting
4. API Versioning
5. Endpoints
6. Data Models
7. Webhook Events
8. Error Handling
9. File Management
10. Examples

Overview

The Veedeo API V3 provides a modern, asynchronous video rendering service designed for high-volume production environments. This specification follows industry best practices from leading platforms like RunwayML, Replicate, and Midjourney.

Key Features

• Async-First Architecture: All rendering operations are asynchronous
• Webhook-Driven: Real-time updates via configurable webhooks
• Professional Subtitle System: Advanced text styling and CJK language support
• Multi-Track Timeline: Video, audio, and subtitle composition
• High Availability: 99.9% uptime SLA with automatic failover
• Idempotent Operations: Safe retry mechanisms with request IDs

Authentication

All API requests require Bearer token authentication.

Authorization: Bearer your_api_key_here

API Key Management

• Standard Tier: 100 requests/minute, 5 concurrent renders
• Pro Tier: 500 requests/minute, 20 concurrent renders
• Enterprise Tier: Custom limits with dedicated resources

Rate Limiting

Rate limits are enforced per API key with the following headers returned:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642434600
X-RateLimit-Type: requests

When rate limits are exceeded, a 429 Too Many Requests response is returned.

API Versioning

Version is specified via header:

X-Veedeo-Version: 2025-01-17

Current version:

• 2025-01-17 (current)

Endpoints

Core Rendering Operations

Create Render Task

POST /v3/tasks

Creates a new asynchronous video rendering task.

Request Body:

{
  "version": "3.0",
  "request_id": "req_1234567890abcdef",
  "input": {
    "timeline": {
      "duration_ms": 15000,
      "tracks": [
        {
          "id": "video_track_1",
          "type": "video",
          "clips": [
            {
              "id": "clip_1",
              "media_url": "https://storage.example.com/image1.jpg",
              "start_time_ms": 0,
              "end_time_ms": 3000,
              "properties": {
                "scale": { "x": 1.0, "y": 1.0 },
                "opacity": 1.0,
                "position": { "x": 0, "y": 0 },
                "fit": "contain"
              }
            }
          ]
        },
        {
          "id": "audio_track_1",
          "type": "audio",
          "clips": [
            {
              "id": "audio_clip_1",
              "media_url": "https://storage.example.com/voice.mp3",
              "start_time_ms": 0,
              "end_time_ms": 15000,
              "properties": {
                "volume": 0.8,
                "fade_in_ms": 500,
                "fade_out_ms": 500
              }
            }
          ]
        },
        {
          "id": "subtitle_track_1",
          "type": "subtitle",
          "clips": [
            {
              "id": "subtitle_clip_1",
              "media_url": "https://storage.example.com/subtitles.srt",
              "start_time_ms": 0,
              "end_time_ms": 15000,
              "properties": {
                "preset": "netflix",
                "font_size": 26,
                "font_family": "dejavu-sans",
                "color": "#FFFFFF",
                "position": { "x": 0, "y": 90 },
                "text_wrapping": {
                  "enabled": true,
                  "max_chars_per_line": 40,
                  "strategy": "word",
                  "language": "auto"
                },
                "outline": {
                  "enabled": true,
                  "width": 3,
                  "color": "#000000",
                  "blur": 1
                },
                "shadow": {
                  "enabled": true,
                  "offset_x": 1,
                  "offset_y": 1,
                  "blur": 2,
                  "color": "#000000",
                  "opacity": 0.7
                }
              }
            }
          ]
        }
      ]
    },
    "output": {
      "resolution": {
        "width": 1920,
        "height": 1080
      },
      "framerate": 30,
      "format": "mp4",
      "quality": "high",
      "codec": "h264"
    }
  },
  "webhook": {
    "url": "https://your-app.com/webhooks/veedeo",
    "events": ["task.started", "task.progress", "task.completed", "task.failed"],
    "secret": "your_webhook_secret_for_hmac_validation"
  },
  "metadata": {
    "user_reference": "project_abc_render_001",
    "tags": ["production", "social_media"],
    "priority": "standard",
    "retention_hours": 24
  }
}

Response (201 Created):

{
  "task_id": "tsk_1234567890abcdef",
  "status": "queued",
  "created_at": "2025-01-17T10:00:00Z",
  "estimated_duration_seconds": 120,
  "queue_position": 5,
  "priority": "standard",
  "links": {
    "self": "/v3/tasks/tsk_1234567890abcdef",
    "cancel": "/v3/tasks/tsk_1234567890abcdef"
  },
  "webhook": {
    "url": "https://your-app.com/webhooks/veedeo",
    "events": ["task.started", "task.progress", "task.completed", "task.failed"]
  }
}

Get Render Status

GET /v3/tasks/{task_id}

Retrieves the current status and details of a render task.

Response (200 OK):

{
  "task_id": "tsk_1234567890abcdef",
  "status": "completed",
  "created_at": "2025-01-17T10:00:00Z",
  "started_at": "2025-01-17T10:00:15Z",
  "completed_at": "2025-01-17T10:02:30Z",
  "progress": {
    "percentage": 100,
    "current_phase": "completed",
    "phases": {
      "download": { "completed": true, "duration_seconds": 5 },
      "render": { "completed": true, "duration_seconds": 110 },
      "upload": { "completed": true, "duration_seconds": 10 }
    }
  },
  "output": {
    "video_url": "https://storage.veedeo.dev/renders/tsk_1234.mp4",
    "thumbnail_url": "https://storage.veedeo.dev/thumbnails/tsk_1234.jpg",
    "preview_url": "https://storage.veedeo.dev/previews/tsk_1234.gif",
    "duration_ms": 15000,
    "file_size_bytes": 12582912,
    "resolution": { "width": 1920, "height": 1080 },
    "format": "mp4",
    "expires_at": "2025-01-18T10:02:30Z"
  },
  "metadata": {
    "user_reference": "project_abc_render_001",
    "tags": ["production", "social_media"],
    "processing_time_seconds": 135,
    "estimated_vs_actual": {
      "estimated": 120,
      "actual": 135,
      "accuracy": 0.89
    }
  }
}

Cancel Render Task

DELETE /v3/tasks/{task_id}

Cancels a queued or in-progress render task.

Response (200 OK):

{
  "task_id": "tsk_1234567890abcdef",
  "status": "canceled",
  "canceled_at": "2025-01-17T10:01:00Z",
  "message": "Render task successfully canceled"
}

List Render Tasks

GET /v3/tasks?status=completed&limit=20&offset=0

Query Parameters:

• status (optional): Filter by status (queued, processing, completed, failed, canceled)
• limit (optional): Number of results per page (default: 20, max: 100)
• offset (optional): Page offset (default: 0)
• created_after (optional): ISO 8601 timestamp
• created_before (optional): ISO 8601 timestamp

Response (200 OK):

{
  "tasks": [
    {
      "task_id": "tsk_1234567890abcdef",
      "status": "completed",
      "created_at": "2025-01-17T10:00:00Z",
      "completed_at": "2025-01-17T10:02:30Z",
      "metadata": {
        "user_reference": "project_abc_render_001",
        "tags": ["production", "social_media"]
      }
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Retry Failed Render

POST /v3/tasks/{task_id}/retry

Retries a failed render task with the same configuration.

Response (201 Created):

{
  "task_id": "tsk_new_retry_id",
  "original_task_id": "tsk_1234567890abcdef",
  "status": "queued",
  "created_at": "2025-01-17T10:30:00Z",
  "retry_count": 1
}

Supporting Endpoints

List Available Models

GET /v3/models

Returns available rendering models and presets.

Response (200 OK):

{
  "models": [
    {
      "id": "standard",
      "name": "Standard Render",
      "description": "Balanced quality and speed for most use cases",
      "max_resolution": { "width": 4096, "height": 2160 },
      "max_duration_seconds": 3600,
      "supported_formats": ["mp4", "mov", "webm"],
      "pricing_tier": "standard"
    },
    {
      "id": "premium",
      "name": "Premium Render",
      "description": "High-quality render with advanced effects",
      "max_resolution": { "width": 7680, "height": 4320 },
      "max_duration_seconds": 7200,
      "supported_formats": ["mp4", "mov", "webm", "prores"],
      "pricing_tier": "premium"
    }
  ]
}

Get API Usage Statistics

GET /v3/usage?period=current_month

Query Parameters:

• period: current_month, last_month, current_week, last_week, today, yesterday

Response (200 OK):

{
  "period": "current_month",
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-17T23:59:59Z",
  "usage": {
    "total_renders": 150,
    "successful_renders": 145,
    "failed_renders": 5,
    "total_processing_minutes": 1250,
    "total_output_minutes": 75,
    "storage_used_gb": 2.5
  },
  "limits": {
    "monthly_renders": 1000,
    "concurrent_renders": 5,
    "max_storage_gb": 10
  },
  "costs": {
    "total_usd": 47.50,
    "breakdown": {
      "rendering_usd": 37.50,
      "storage_usd": 5.00,
      "bandwidth_usd": 5.00
    }
  }
}

Font Support

Overview

The Veedeo V3 API uses a strict font policy that only supports specific font families installed on our rendering servers. This ensures consistent, high-quality subtitle rendering across all videos.

Supported Font Families

Liberation Font Family (Complete Collection)

DejaVu Font Family (Complete Collection)

Noto CJK Font Family (Serif Collection)

Source Han Sans Font Family (Premium CJK Collection)

Professional sans-serif fonts from Adobe for superior Chinese text rendering quality.

Convenient Aliases

Usage Examples

Basic Font Usage

{
  "properties": {
    "font_family": "dejavu-sans",
    "font_size": 24
  }
}

Using Chinese Fonts

{
  "properties": {
    "font_family": "sourcehan-sans-sc",
    "font_size": 28
  }
}

Chinese Platform Presets

{
  "properties": {
    "preset": "douyin",
    "font_size": 24
  }
}

Bold Fonts

{
  "properties": {
    "font_family": "liberation-sans-bold",
    "font_size": 26
  }
}

Important Notes

⚠️ Strict Font Policy: Only the fonts listed above are supported. Using any other font name will result in an error.

✅ Quality Assurance: All fonts are pre-installed and tested to ensure consistent rendering.

🎯 Recommendations:

• Use dejavu-sans for modern, clean subtitles
• Use liberation-sans for maximum compatibility
• Use noto-serif-sc for Chinese content
• Use preset fonts via the preset parameter for optimal results

Error Handling

If you specify an unsupported font, the API will return a validation error:

{
  "error": {
    "code": "INVALID_FONT",
    "message": "Font 'custom-font' not supported. Available fonts: liberation-sans, dejavu-sans, ..."
  }
}

Data Models

Task Status

type TaskStatus =
  | "queued"      // Task accepted and waiting in queue
  | "processing"  // Actively being rendered
  | "completed"   // Successfully completed
  | "failed"      // Failed due to error
  | "canceled";   // Manually canceled

Priority Levels

type Priority =
  | "low"       // Best effort, lower cost
  | "standard"  // Normal processing
  | "high"      // Faster processing, higher cost
  | "urgent";   // Highest priority, premium cost

Subtitle Presets

type SubtitlePreset =
  | "netflix"       // Netflix-style subtitles
  | "youtube"       // YouTube-style subtitles
  | "professional"  // Professional broadcast style
  | "minimal"       // Clean, minimal style
  | "cinema"        // Cinematic style
  | "douyin"        // 抖音/TikTok style for short videos
  | "xiaohongshu"   // 小红书/RedBook style for lifestyle content
  | "wechat-video"  // 微信视频号 style for WeChat videos
  | "custom";       // User-defined styling

Output Quality

type OutputQuality =
  | "draft"    // Fast, lower quality for previews
  | "standard" // Balanced quality and file size
  | "high"     // High quality, larger file size
  | "premium"; // Maximum quality

Video Clip Properties

interface VideoClipProperties {
  scale: { x: number; y: number };        // Scaling factors (1.0 = original size)
  opacity: number;                        // Opacity level (0.0 to 1.0)
  position: { x: number; y: number };     // Position offset in pixels
  fit?: FitMode;                          // How media fits within canvas
  rotation?: number;                      // Rotation angle in degrees
  blend_mode?: string;                    // Blending mode for composition
  layer_type?: "background" | "foreground"; // Layer classification
  z_index?: number;                       // Stacking order (higher = on top)
  background_fit?: FitMode;               // [Deprecated] Use 'fit' instead
  background_blur?: number;               // Blur intensity (0-100, background only)
}

Fit Modes

The fit parameter controls how media assets are scaled and positioned to fit the target canvas:

type FitMode =
  | "contain"  // Default: Show complete media, may add black bars
  | "cover"    // Fill canvas completely, may crop media
  | "fill"     // Stretch to fit canvas, may distort
  | "stretch"; // Alias for 'fill'

Common Use Cases:

// Square image (1440×1440) on vertical canvas (1080×1920)
{
  "fit": "cover",  // Fills canvas, crops sides → No black bars
  "scale": {"x": 1.0, "y": 1.0},
  "position": {"x": 0, "y": 0}
}

// Landscape image (1920×1080) on vertical canvas (1080×1920)
{
  "fit": "contain",  // Shows full image → Black bars top/bottom
  "scale": {"x": 1.0, "y": 1.0},
  "position": {"x": 0, "y": 0}
}

Webhook Events

Webhooks are sent as HTTP POST requests to your configured endpoint with HMAC-SHA256 signature validation.

Event Types

task.queued

Sent when a task is successfully queued.

{
  "event": "task.queued",
  "timestamp": "2025-01-17T10:00:00Z",
  "task_id": "tsk_1234567890abcdef",
  "data": {
    "queue_position": 5,
    "estimated_start_time": "2025-01-17T10:02:00Z"
  }
}

task.started

Sent when rendering begins.

{
  "event": "task.started",
  "timestamp": "2025-01-17T10:00:15Z",
  "task_id": "tsk_1234567890abcdef",
  "data": {
    "started_at": "2025-01-17T10:00:15Z",
    "estimated_completion": "2025-01-17T10:02:15Z"
  }
}

task.progress

Sent periodically during rendering (maximum once every 30 seconds).

{
  "event": "task.progress",
  "timestamp": "2025-01-17T10:01:00Z",
  "task_id": "tsk_1234567890abcdef",
  "data": {
    "progress": {
      "percentage": 45,
      "current_phase": "render",
      "phase_progress": 0.75,
      "estimated_completion": "2025-01-17T10:02:15Z"
    }
  }
}

task.completed

Sent when rendering completes successfully.

{
  "event": "task.completed",
  "timestamp": "2025-01-17T10:02:30Z",
  "task_id": "tsk_1234567890abcdef",
  "data": {
    "completed_at": "2025-01-17T10:02:30Z",
    "processing_time_seconds": 135,
    "output": {
      "video_url": "https://storage.veedeo.dev/renders/tsk_1234.mp4",
      "thumbnail_url": "https://storage.veedeo.dev/thumbnails/tsk_1234.jpg",
      "preview_url": "https://storage.veedeo.dev/previews/tsk_1234.gif",
      "duration_ms": 15000,
      "file_size_bytes": 12582912,
      "expires_at": "2025-01-18T10:02:30Z"
    }
  }
}

task.failed

Sent when rendering fails.

{
  "event": "task.failed",
  "timestamp": "2025-01-17T10:01:30Z",
  "task_id": "tsk_1234567890abcdef",
  "data": {
    "failed_at": "2025-01-17T10:01:30Z",
    "error": {
      "code": "MEDIA_DOWNLOAD_FAILED",
      "message": "Unable to download media file",
      "details": {
        "media_url": "https://example.com/unreachable.jpg",
        "http_status": 404
      },
      "retry_possible": true
    }
  }
}

Webhook Security

All webhooks include HMAC-SHA256 signature for verification:

X-Veedeo-Signature: sha256=abcdef1234567890...
X-Veedeo-Timestamp: 1642434600
X-Veedeo-Event: task.completed

Error Handling

HTTP Status Codes

• 200 OK - Successful request
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request format
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 409 Conflict - Resource conflict (e.g., duplicate request_id)
• 422 Unprocessable Entity - Valid format but business logic error
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error
• 503 Service Unavailable - Temporary service outage

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid timeline configuration",
    "details": [
      {
        "field": "input.timeline.tracks[0].clips[0].media_url",
        "issue": "URL is not accessible",
        "provided_value": "https://invalid-url.com/missing.jpg"
      }
    ],
    "request_id": "req_xyz123",
    "documentation_url": "https://docs.veedeo.dev/errors/VALIDATION_ERROR",
    "suggested_action": "Verify that all media URLs are publicly accessible"
  }
}

Common Error Codes

File Management

File Retention

• Output files: Retained for 24 hours by default (configurable up to 7 days)
• Thumbnails: Retained for 7 days
• Previews: Retained for 7 days
• Input files: Cached for 1 hour during processing only

File Access

All output files are provided as pre-signed URLs with temporary access:

{
  "video_url": "https://storage.veedeo.dev/renders/tsk_1234.mp4?expires=1642521000&signature=abc123",
  "expires_at": "2025-01-18T10:02:30Z"
}

Persistent Storage

For longer retention, use webhook notifications to download and store files in your own storage:

{
  "webhook": {
    "url": "https://your-app.com/webhooks/save-render",
    "events": ["task.completed"]
  }
}

Examples

Basic Video Render

curl -X POST https://api.veedeo.dev/v3/tasks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "X-Veedeo-Version: 2025-01-17" \
  -d '{
    "version": "3.0",
    "request_id": "my_unique_request_123",
    "input": {
      "timeline": {
        "duration_ms": 10000,
        "tracks": [
          {
            "id": "video_track",
            "type": "video",
            "clips": [
              {
                "id": "clip1",
                "media_url": "https://example.com/image.jpg",
                "start_time_ms": 0,
                "end_time_ms": 10000,
                "properties": {
                  "scale": {"x": 1.0, "y": 1.0},
                  "opacity": 1.0,
                  "position": {"x": 0, "y": 0}
                }
              }
            ]
          }
        ]
      },
      "output": {
        "resolution": {"width": 1920, "height": 1080},
        "framerate": 30,
        "format": "mp4",
        "quality": "high"
      }
    },
    "webhook": {
      "url": "https://my-app.com/webhook",
      "events": ["task.completed"]
    }
  }'

Advanced Multi-Track Render

See API_V3_EXAMPLES.md for comprehensive examples including:

• Multi-track video composition
• Professional subtitle styling
• Audio mixing and effects
• Custom animations and transitions
• Error handling and retry logic

Last Updated: January 17, 2025 Version: 3.0 Contact: api-support@veedeo.dev