Link video và tùy chọn

Bạn có thể gửi link YouTube, X, TikTok, Instagram, Facebook, Bluesky hoặc tải file lên. Các nền tảng khác và dạng link cho từng loại video công khai đã ghi hình nằm trong bảng dưới. Khi gọi POST /v1/transcriptions, thêm source, diarize và language vào body nếu muốn chọn nguồn transcript, bật nhận diện người nói hoặc đặt ngôn ngữ. Bạn có thể bỏ qua cả ba trường này để dùng mặc định.

Gửi được link từ đâu?

Đặt link vào url; API sẽ tự nhận diện nền tảng. Chỉ truyền thêm platform khi cần, và giá trị phải khớp với link.

Với năm nền tảng bổ sung, URL phải dùng HTTPS, không kèm thông tin đăng nhập và không đặt cổng riêng. Mỗi link phải dẫn đến một video công khai đã ghi hình. Không nhận bài riêng tư, nội dung cần đăng nhập, buổi phát đang trực tiếp hoặc đang xử lý, trang cá nhân, feed hay bộ sưu tập. transcript1 không gửi cookie tài khoản khi lấy video. Tham số thời gian trên URL không cắt ngắn nội dung.

Giữ nguyên media_id mà API trả về cho clip Twitch và Snapchat Spotlight. Đây có thể là chuỗi ID không thể suy ra từ URL; đừng tự tách hay dựng lại ID.

Trên X, TikTok, Instagram, Facebook và Bluesky, hãy gửi link bài đăng công khai. Nếu bài có nhiều video, transcript1 chỉ lấy video đầu tiên. Trang cá nhân, story, trang livestream và bài ảnh TikTok không dùng được. Nếu nền tảng yêu cầu đăng nhập, job báo login_required. Nếu video không có track audio, job báo no_audio. Bạn không mất phút trong cả hai trường hợp.

YouTube, X, TikTok, Bluesky, Dailymotion và LinkedIn cho phép lấy phụ đề nếu video có bản phù hợp bằng ngôn ngữ gốc. Instagram, Facebook, Twitch, Pinterest và Snapchat chỉ chuyển giọng nói thành văn bản bằng AI: chọn auto hoặc stt, không chọn captions. Mọi nền tảng và file tải lên đều có cùng giá mỗi phút, tính theo thời lượng đo được.

Chỉ các dạng link rút gọn trong bảng trên mới dùng được. Nếu link chia sẻ chưa cho biết ID bài đăng lúc gửi request, API không thể tìm lại job cũ tương ứng. Muốn dùng lại transcript, hãy gửi link đầy đủ của bài đăng.

Dạng link YouTube

Với YouTube, đặt link video vào url và bỏ qua platform hoặc đặt là youtube. Các dạng dưới đây đều dùng được, có hoặc không có www.:

API bỏ qua tham số query như t, list và si. Các dạng link khác nhau của cùng một video vẫn trỏ đến cùng video đó. Gửi URL đầy đủ, không gửi riêng ID video dài 11 ký tự. Link kênh, link chỉ có playlist hoặc link không đúng dạng sẽ nhận 422 invalid_url. Nếu platform không nằm trong danh sách hỗ trợ, API trả 422 unsupported_platform kèm supported_platforms.

Bạn có thể gửi video công khai hoặc không công khai (unlisted), nhưng không gửi video riêng tư, giới hạn độ tuổi hay đang livestream. Các trường hợp này lần lượt báo media_private, age_restricted và live_stream. Nếu có file của mình, bạn có thể tải file lên.

source

Chọn source để lấy transcript từ phụ đề sẵn có hoặc từ audio.

Với file tải lên, transcript1 luôn dùng speech-to-text. Chỉ đặt source là auto hoặc stt; chọn captions sẽ nhận 422 invalid_request.

Phụ đề phải đúng ngôn ngữ bạn yêu cầu. Nếu language là auto, đó phải là ngôn ngữ gốc của video. Trên YouTube, transcript1 lấy bản do người đăng tải lên hoặc bản YouTube tự tạo bằng ngôn ngữ đó, không lấy bản dịch tự động. Thứ tự ưu tiên là phụ đề do người đăng tải lên, track không rõ nguồn gốc, rồi phụ đề tự động. Không rõ nguồn gốc không có nghĩa là do người đăng tải lên.

Trên X, transcript1 lấy track VTT sẵn có. Kể cả phụ đề tự động cũng chỉ có mốc thời gian theo đoạn, không có mốc thời gian từng từ. Chế độ auto có thể chuyển sang STT khi không lấy được nội dung phụ đề hoặc không parse được nội dung đó; lỗi route, lưu trữ hay lập trình không kích hoạt chuyển sang STT. Chọn stt thì luôn bỏ qua phụ đề.

diarize

Bật diarize để nhận diện người nói trong transcript. Mặc định là false.

• Nhận diện người nói cần speech-to-text. Nếu đang dùng source là auto, đặt diarize: true sẽ bỏ qua phụ đề và xử lý audio ngay.
• Không kết hợp source: "captions" với diarize: true; API trả 422 invalid_request.
• Người nói có nhãn Speaker 1, Speaker 2… Bạn đọc nhãn trong transcript.speakers và trường speaker của từng đoạn. Định dạng text và srt thêm tiền tố Speaker 1: ; vtt dùng thẻ <v Speaker 1>.

{ "platform": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ", "source": "stt", "diarize": true }

language

Để transcript1 tự chọn ngôn ngữ, giữ language là auto như mặc định. Bạn cũng có thể truyền mã ISO 639-1 gồm hai chữ cái, chẳng hạn en, de hoặc es.

• Khi lấy phụ đề, language chọn ngôn ngữ của track. Giá trị auto chọn ngôn ngữ gốc của video.
• Khi chạy speech-to-text, giá trị này là gợi ý ngôn ngữ gửi đến nhà cung cấp. Với auto, hệ thống tự nhận diện ngôn ngữ; từng đoạn có trường language riêng.

Trường language ở cấp object transcription cho biết ngôn ngữ chính của toàn bộ bản ghi.

Đọc nguồn và nội dung transcript

Đọc transcript_source để biết văn bản lấy từ đâu: youtube_captions, x_captions, tiktok_captions, bluesky_captions, dailymotion_captions, linkedin_captions hoặc speech_to_text. Nếu lấy từ phụ đề, caption_kind có thể là manual, auto_generated hoặc null. Giá trị null chỉ có nghĩa là chưa rõ nguồn gốc; đừng hiển thị thành phụ đề do người đăng tải lên.

Phụ đề YouTube giữ nguyên nội dung được đăng, kể cả thẻ như [Music]. Speech-to-text xử lý bản ghi tối đa 5 giờ. Dài hơn sẽ báo media_too_long.

Với phụ đề X (x_captions), TikTok, Bluesky, Dailymotion và LinkedIn, mỗi đoạn chỉ có mốc thời gian của cả đoạn. Gọi include=words vẫn nhận words: null, kể cả với phụ đề tự động. Các nguồn này cũng không nhận diện người nói. Cần mốc thời gian từng từ thì chọn source: "stt"; cần nhãn người nói thì đặt diarize: true cùng auto hoặc stt.

Tính phí thế nào?

Lấy phụ đề hay chạy speech-to-text đều tốn như nhau: một credit cho mỗi phút video hoặc audio, làm tròn lên. Bạn chỉ chọn cách lấy văn bản, không chọn mức giá khác. Xem cách tính phút và giới hạn.