Captions

Lưu ý: Vào ngày 13 tháng 3 năm 2024, YouTube thông báo sẽ ngừng sử dụng tham số sync cho các điểm cuối API captions.insertcaptions.update. Tính năng tự động đồng bộ hoá phụ đề vẫn hoạt động trong YouTube Creator Studio. Hãy xem nhật ký sửa đổi API để biết thêm thông tin chi tiết.

Tài nguyên caption đại diện cho phụ đề trên YouTube. Phụ đề được liên kết với đúng một video trên YouTube.

Phương thức

API hỗ trợ các phương thức sau cho tài nguyên captions:

list
Truy xuất danh sách phụ đề có liên kết với một video cụ thể. Lưu ý rằng phản hồi của API không chứa phụ đề thực tế và phương thức captions.download cung cấp khả năng truy xuất phụ đề. Thử ngay.
chèn
Tải phụ đề lên.
cập nhật
Cập nhật phụ đề. Khi cập nhật phụ đề, bạn có thể thay đổi trạng thái nháp của bản nhạc, tải tệp phụ đề mới lên cho bản phụ đề hoặc cả hai.
xóa
Xóa phụ đề đã chỉ định. Thử ngay.
tải xuống
Tải phụ đề xuống. Phụ đề được trả về ở định dạng ban đầu trừ phi yêu cầu chỉ định giá trị cho tham số tfmt và bằng ngôn ngữ gốc, trừ phi yêu cầu chỉ định một giá trị cho tham số tlang.

Trình bày tài nguyên

Cấu trúc JSON dưới đây thể hiện định dạng của tài nguyên captions:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
kind string
Xác định loại tài nguyên API. Giá trị sẽ là youtube#caption.
etag etag
Thẻ Etag của tài nguyên này.
id string
Mã nhận dạng mà YouTube dùng để xác định riêng biệt bản phụ đề.
snippet object
Đối tượng snippet chứa thông tin cơ bản về chú thích.
snippet.videoId string
Mã nhận dạng mà YouTube dùng để xác định riêng biệt video có liên kết với phụ đề.
snippet.lastUpdated datetime
Ngày và giờ cập nhật phụ đề gần đây nhất. Giá trị được chỉ định theo định dạng ISO 8601.
snippet.trackKind string
Loại phụ đề.

Các giá trị hợp lệ cho thuộc tính này là:
  • ASR – Phụ đề được tạo bằng tính năng nhận dạng giọng nói tự động.
  • forced – Phụ đề sẽ phát khi không có phụ đề nào khác được chọn trong trình phát. Ví dụ: Một video có cảnh người nói tiếng nước ngoài có thể có phụ đề bắt buộc để chỉ hiển thị phụ đề cho ngôn ngữ của người nước ngoài.
  • standard – Phụ đề thông thường. Đây là giá trị mặc định.
snippet.language string
Ngôn ngữ của phụ đề. Giá trị thuộc tính là thẻ ngôn ngữ BCP-47.
snippet.name string
Tên của phụ đề. Tên này nhằm mục đích hiển thị với người dùng dưới dạng một tùy chọn trong quá trình phát. Độ dài tên tối đa được hỗ trợ là 150 ký tự.
snippet.audioTrackType string
Loại bản âm thanh liên kết với bản phụ đề.

Các giá trị hợp lệ cho thuộc tính này là:
  • commentary – Bản phụ đề tương ứng với một bản âm thanh thay thế có chứa nội dung bình luận, chẳng hạn như bình luận theo thư mục.
  • descriptive – Phụ đề tương ứng với một bản âm thanh thay thế có âm thanh mô tả bổ sung.
  • primary – Phụ đề tương ứng với bản âm thanh chính của video, thường được liên kết với video.
  • unknown – Đây là giá trị mặc định.
snippet.isCC boolean
Cho biết bản nhạc có phụ đề dành cho người khiếm thính và người có thính giác kém hay không. Giá trị mặc định là false.
snippet.isLarge boolean
Cho biết phụ đề có sử dụng chữ lớn cho người khiếm thị hay không. Giá trị mặc định là false.
snippet.isEasyReader boolean
Cho biết liệu phụ đề có được định dạng để "dễ đọc" hay không, tức là phụ đề dành cho người học ngôn ngữ ở cấp độ ba. Giá trị mặc định là false.
snippet.isDraft boolean
Cho biết phụ đề có phải là bản nháp hay không. Nếu giá trị là true, thì kênh sẽ không hiển thị công khai. Giá trị mặc định là false.
snippet.isAutoSynced boolean
Cho biết liệu YouTube đã đồng bộ hoá bản phụ đề với bản âm thanh trong video hay chưa. Giá trị sẽ là true nếu yêu cầu đồng bộ hoá được thể hiện rõ ràng khi phụ đề được tải lên. Ví dụ: Khi gọi phương thức captions.insert hoặc captions.update, bạn có thể đặt tham số sync thành true để hướng dẫn YouTube đồng bộ hoá bản nhạc đã tải lên với video. Nếu giá trị là false, YouTube sẽ sử dụng mã thời gian trong phụ đề được tải lên để xác định thời điểm hiển thị phụ đề.
snippet.status string
Trạng thái của phụ đề.

Các giá trị hợp lệ cho thuộc tính này là:
  • failed
  • serving
  • syncing
snippet.failureReason string
Lý do YouTube không xử lý được phụ đề. Thuộc tính này chỉ xuất hiện nếu giá trị của thuộc tính statefailed.

Các giá trị hợp lệ của thuộc tính này là:
  • processingFailed – YouTube không xử lý được phụ đề đã tải lên.
  • unknownFormat – Không nhận dạng được định dạng của phụ đề.
  • unsupportedFormat – Không hỗ trợ định dạng của phụ đề.