API Phát hiện Caption

Giá cả

25 credits cho mỗi yêu cầu

Chi phí cố định bất kể độ dài video hay số lượng caption được phát hiện.

Tổng quan

API Phát hiện Caption phát hiện vị trí caption trong video bằng cách phân tích nhiều frame để phân biệt caption (text thay đổi) và biển bảng (text cố định).

Domain: api.revidapi.com

Endpoint

POST https://api.revidapi.com/paid/detect-caption

Xác thực: Bắt buộc - Header x-api-key

Yêu cầu

Headers

x-api-key: Bắt buộc. API key của bạn để xác thực.
Content-Type: Bắt buộc. Phải là application/json.

Tham số Body

Tham số Bắt buộc

Parameter	Type	Mô tả
`video_url`	string	URL video cần detect (http/https)

Tham số Tùy chọn

Parameter	Type	Default	Mô tả
`caption_region`	string	`"bottom"`	`bottom`, `top`, `center`, `full`, `top_bottom`
`sample_frames`	integer	`5`	Số frame phân tích (3-10, khuyến nghị 5-6)
`srt_text`	string	-	JSON string mảng SRT `[{text, ...}]` để hỗ trợ detect
`webhook_url`	string	-	URL nhận kết quả khi hoàn tất
`id`	string	-	Mã định danh theo dõi

`caption_region`

Value	Mô tả
`bottom`	Caption ở dưới (phổ biến)
`top`	Caption ở trên
`center`	Caption ở giữa
`full`	Toàn màn hình
`top_bottom`	50% top & 50% bottom

Phản hồi

Phản hồi Ngay lập tức (Task Created)

{
  "task_id": "8ffd7873-3272-4277-a4d2-83fd0c3731b4",
  "status": "pending",
  "message": "Detection task created",
  "type": "detect"
}

Trạng thái Task (GET `/paid/get/job/status/{task_id}`)

✅ Hoàn thành

{
  "task_id": "8ffd7873-3272-4277-a4d2-83fd0c3731b4",
  "type": "detect",
  "status": "completed",
  "progress": 100,
  "message": "Found 1 captions, 0 static texts",
  "result": {
    "video_size": {
      "width": 576,
      "height": 1024
    },
    "captions": [
      {
        "x": 45,
        "y": 657,
        "w": 486,
        "h": 62,
        "text": "Text caption mẫu",
        "occurrences": 6
      }
    ],
    "static_text": [
      {
        "x": 50,
        "y": 50,
        "w": 200,
        "h": 30,
        "text": "Text biển bảng cố định",
        "occurrences": 5
      }
    ],
    "caption_area": {
      "x": 45,
      "y": 657,
      "w": 486,
      "h": 62
    },
    "detected_region": {
      "x": 0,
      "y": 768,
      "w": 576,
      "h": 256
    }
  },
  "created_at": "2025-12-22T11:18:35.134597"
}

⏳ Đang xử lý

{
  "task_id": "8ffd7873-3272-4277-a4d2-83fd0c3731b4",
  "status": "processing",
  "progress": 50,
  "message": "Analyzing frame 3/5..."
}

❌ Thất bại

{
  "task_id": "8ffd7873-3272-4277-a4d2-83fd0c3731b4",
  "status": "failed",
  "progress": 30,
  "message": "Failed to download video"
}

Các Trường Phản hồi

`result.captions[]`

Field	Type	Mô tả
`x`	integer	Tọa độ X (pixel)
`y`	integer	Tọa độ Y (pixel)
`w`	integer	Chiều rộng (pixel)
`h`	integer	Chiều cao (pixel)
`text`	string	Text được detect
`occurrences`	integer	Số lần xuất hiện trong các frame

`result.caption_area`

Vùng tổng hợp của tất cả captions - Dùng cho blur và subtitle

Field	Type	Mô tả
`x`	integer	X bắt đầu
`y`	integer	Y bắt đầu
`w`	integer	Chiều rộng
`h`	integer	Chiều cao

`result.static_text[]`

Text cố định (biển bảng) - Bỏ qua, không blur

Logic Detect

1. Trích 5 frames từ video (10% → 90% video)
2. OCR detect text trong mỗi frame
3. So sánh text giữa các frames:
   - Text THAY ĐỔI → Caption ✅
   - Text KHÔNG ĐỔI → Biển bảng ❌
4. Tính caption_area (vùng tổng hợp)

Ví dụ Yêu cầu

Tối thiểu:

curl -X POST "https://api.revidapi.com/paid/detect-caption" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://example.com/video.mp4"}'

Đầy đủ (payload đã chạy):

{
  "video_url": "https://example.com/video.mp4",
  "caption_region": "top_bottom",
  "sample_frames": 6
}

Có SRT hỗ trợ:

{
  "video_url": "https://example.com/video.mp4",
  "caption_region": "top_bottom",
  "sample_frames": 6,
  "srt_text": "[{\"text\":\"Đoạn 1\"},{\"text\":\"Đoạn 2\"}]"
}

Ghi chú Sử dụng

POST trả về ngay với task_id (không chờ xử lý)
GET task status để lấy kết quả (poll trong loop)
caption_area là vùng tổng hợp - dùng cho blur/subtitle
static_text là biển bảng - không cần blur

Workflow

POST /paid/detect-caption
    ↓
GET /paid/get/job/status/{task_id} (loop)
    ↓
Lấy caption_area → Dùng cho blur/subtitle

Tips

Hầu hết captions ở dưới: Dùng caption_region: "bottom" làm mặc định
Không chắc vị trí: Dùng caption_region: "full" để tìm toàn màn hình
Nhiều frames hơn: Tăng sample_frames lên 7-10 để detect chính xác hơn (chậm hơn)
Dùng caption_area: Luôn dùng result.caption_area (không phải captions[0]) cho vị trí blur/subtitle

Vấn đề Thường gặp

Không detect được caption: Thử caption_region khác hoặc tăng sample_frames
Detect sai vùng: Điều chỉnh tham số caption_region
Static text được detect: Dùng caption_area loại trừ static_text

Thực hành Tốt nhất

Dùng webhooks: Luôn dùng webhooks để đáng tin cậy hơn
ID duy nhất: Cung cấp giá trị id duy nhất để theo dõi
Cài đặt mặc định: Dùng caption_region: "bottom" và sample_frames: 5 cho hầu hết trường hợp
Dùng caption_area: Luôn dùng result.caption_area cho các thao tác blur/subtitle tiếp theo