Skip to content

API.md

Latest commit

 

History

History
324 lines (257 loc) · 7.13 KB

API.md

File metadata and controls

324 lines (257 loc) · 7.13 KB

VideoGen Messenger API Documentation

Base URL: https://api.videogenmessenger.com/api/v1

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer vgm_your_api_key_here

Get your API key by registering at: POST /api/v1/auth/register

Rate Limits

Tier Generations/Day Searches/Hour API Calls/Minute
Free 10 100 100
Creator 100 1,000 500
Pro 500 10,000 2,000
Enterprise Unlimited Unlimited Custom

Endpoints

Generate Video

POST /generate

Request a new AI video generation.

Request Body:

{
  "prompt": "Happy birthday celebration with balloons",
  "quality": "hd",
  "duration": 5,
  "style": "realistic"
}

Parameters:

  • prompt (string, required): Description of the video to generate (5-500 chars)
  • quality (string, optional): Video quality - sd, hd, or 4k. Default: hd
  • duration (number, optional): Video duration in seconds (1-30). Default: 5
  • style (string, optional): Generation style - realistic, animated, cartoon

Response: 202 Accepted

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "estimated_time": 60,
  "message": "Video generation started"
}

Check Generation Status

GET /generate/status/:jobId

Check the status of a video generation job.

Response: 200 OK

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 1.0,
  "video_url": "https://cdn.videogenmessenger.com/videos/abc123.mp4",
  "thumbnail_url": "https://cdn.videogenmessenger.com/thumbnails/abc123.jpg",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:30Z"
}

Status Values:

  • queued: Job is in queue
  • processing: Currently generating
  • completed: Video ready
  • failed: Generation failed

Search Videos

GET /search?q=happy+birthday&limit=20&page=1

Search for existing videos.

Query Parameters:

  • q (string, required): Search query (minimum 2 characters)
  • limit (number, optional): Results per page (1-100). Default: 20
  • page (number, optional): Page number. Default: 1
  • quality (string, optional): Filter by quality
  • duration (string, optional): Filter by duration range

Response: 200 OK

{
  "data": [
    {
      "id": "vid_abc123",
      "video_id": "abc123",
      "title": "Happy Birthday Celebration",
      "description": "Colorful birthday party with balloons",
      "video_url": "https://cdn.videogenmessenger.com/videos/abc123.mp4",
      "thumbnail_url": "https://cdn.videogenmessenger.com/thumbnails/abc123.jpg",
      "duration": 5.2,
      "width": 1920,
      "height": 1080,
      "created_at": "2025-01-15T10:00:00Z",
      "tags": ["birthday", "celebration", "party"]
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "meta": {
    "query": "happy birthday",
    "request_id": "req_xyz789"
  }
}

Get Trending Videos

GET /trending?limit=50&timeRange=24h

Get currently trending videos.

Query Parameters:

  • limit (number, optional): Number of results (1-100). Default: 50
  • category (string, optional): Filter by category
  • timeRange (string, optional): Time range - 24h, 7d, 30d. Default: 24h

Response: 200 OK

{
  "data": [
    {
      "id": "vid_trending1",
      "title": "Trending Video 1",
      "video_url": "https://cdn.videogenmessenger.com/videos/trend1.mp4",
      "thumbnail_url": "https://cdn.videogenmessenger.com/thumbnails/trend1.jpg",
      "views": 15000,
      "shares": 2500
    }
  ],
  "meta": {
    "time_range": "24h",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Get Video Details

GET /videos/:id

Get detailed information about a specific video.

Response: 200 OK

{
  "data": {
    "id": "vid_abc123",
    "video_id": "abc123",
    "title": "Happy Birthday Celebration",
    "description": "Colorful birthday party with balloons",
    "video_url": "https://cdn.videogenmessenger.com/videos/abc123.mp4",
    "thumbnail_url": "https://cdn.videogenmessenger.com/thumbnails/abc123.jpg",
    "duration": 5.2,
    "width": 1920,
    "height": 1080,
    "created_at": "2025-01-15T10:00:00Z",
    "prompt": "Happy birthday celebration with balloons",
    "tags": ["birthday", "celebration", "party"]
  }
}

Error Responses

All errors return appropriate HTTP status codes with JSON error details:

400 Bad Request

{
  "error": "Validation error",
  "details": ["Prompt must be at least 5 characters"]
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Code Examples

JavaScript/Node.js

const API_KEY = 'vgm_your_api_key';
const BASE_URL = 'https://api.videogenmessenger.com/api/v1';

// Generate video
async function generateVideo(prompt) {
  const response = await fetch(`${BASE_URL}/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt,
      quality: 'hd',
      duration: 5
    })
  });

  const data = await response.json();
  console.log('Job ID:', data.job_id);

  return data.job_id;
}

// Check status
async function checkStatus(jobId) {
  const response = await fetch(`${BASE_URL}/generate/status/${jobId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  return await response.json();
}

// Usage
const jobId = await generateVideo('Happy birthday celebration');
const status = await checkStatus(jobId);

Swift/iOS

let apiKey = "vgm_your_api_key"
let baseURL = "https://api.videogenmessenger.com/api/v1"

func generateVideo(prompt: String) async throws -> String {
    var request = URLRequest(url: URL(string: "\(baseURL)/generate")!)
    request.httpMethod = "POST"
    request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let body = [
        "prompt": prompt,
        "quality": "hd",
        "duration": 5
    ] as [String: Any]
    request.httpBody = try JSONSerialization.data(withJSONObject: body)

    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(GenerationResponse.self, from: data)

    return response.jobId
}

Webhooks (Coming Soon)

Subscribe to webhooks for real-time notifications when video generation completes:

{
  "event": "generation.completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "video_url": "https://cdn.videogenmessenger.com/videos/abc123.mp4",
  "timestamp": "2025-01-15T10:31:30Z"
}

Support