Hướng dẫn tích hợp API tạo video trên OpenRouter: Một mã nguồn cho mọi mô hình

Việc thêm tính năng tạo video vào một ứng dụng sẽ rất đơn giản khi bạn chỉ thử nghiệm một mô hình. Sự phức tạp chỉ xuất hiện khi bạn muốn thử nghiệm thêm các mô hình khác. Mỗi nhà cung cấp có thể có endpoint, tham số yêu cầu, trạng thái công việc, logic polling (truy vấn trạng thái) và định dạng đầu ra riêng. Điều đó biến một thay đổi mô hình đơn giản thành một quá trình tích hợp mới cần phải xây dựng và duy trì.

Chúng tôi đặt quy trình đó đằng sau một API video bất đồng bộ (asynchronous). Bạn gửi một prompt đến POST /api/v1/videos, nhận về một job ID, thực hiện polling cho đến khi quá trình tạo hoàn tất, và sau đó tải xuống video đã hoàn thiện.

Trong hướng dẫn này, chúng ta sẽ xây dựng quy trình đó từ đầu đến cuối. Chúng ta sẽ gửi một công việc với Seedance, thực hiện polling an toàn, lưu tệp MP4, và sau đó chạy quy trình tích hợp tương tự với Veo và Wan.

Tóm tắt (Tl;dr)

Tại sao API bất đồng bộ lại hiệu quả hơn các phương án thay thế

Việc tạo video mất nhiều thời gian hơn so với một phản hồi API thông thường. Một mô hình phải tạo và phối hợp nhiều khung hình, duy trì tính nhất quán về hình ảnh giữa chúng, và đôi khi còn phải tạo cả âm thanh đi kèm. Tùy thuộc vào mô hình và các thiết lập được yêu cầu, quá trình này có thể mất từ vài giây đến vài phút.

Việc giữ cho yêu cầu HTTP gốc mở trong suốt khoảng thời gian đó rất thiếu ổn định. Một phiên trình duyệt có thể đóng, một hàm serverless có thể đạt giới hạn thực thi, hoặc một proxy có thể hết thời gian chờ (timeout) trước khi video sẵn sàng.

Một API bất đồng bộ tách biệt việc gửi yêu cầu khỏi quá trình hoàn tất:

Ứng dụng của bạn có thể tiếp tục chạy trong khi mô hình làm việc ở chế độ nền. Nó cũng có thể khôi phục một công việc sau khi khởi động lại vì quá trình tạo được gắn với một job ID cố định thay vì một kết nối kéo dài.

Tích hợp trực tiếp với một nhà cung cấp

Việc tích hợp trực tiếp với nhà cung cấp có thể hoạt động tốt khi bạn đã biết chính xác mô hình mình muốn và không dự định thay đổi nó. Bạn sử dụng xác thực, định dạng yêu cầu, trạng thái công việc, endpoint polling và phản hồi đầu ra của chính nhà cung cấp đó.

Khối lượng công việc bổ sung sẽ lộ rõ khi bạn muốn so sánh với một mô hình khác. Nhà cung cấp mới có thể sử dụng tên trường khác cho thời lượng và độ phân giải, hoặc trả về một đối tượng công việc khác với các trạng thái kết thúc khác nhau. Nó cũng có thể yêu cầu một phương thức khác để tải xuống tài nguyên đã hoàn thiện. Khi đó, ứng dụng của bạn sẽ cần một client thứ hai, một bộ biến môi trường khác và nhiều mã xử lý lỗi đặc thù cho từng nhà cung cấp hơn.

Không có gì sai trái về bản chất với cách tiếp cận này. Nó chỉ có nghĩa là việc chuyển đổi mô hình trở thành một thay đổi về tích hợp thay vì thay đổi về cấu hình, điều này làm chậm quá trình thử nghiệm và tăng chi phí bảo trì khi danh sách mô hình của bạn ngày càng dài ra.

Chạy các mô hình video cục bộ (locally)

Việc tạo video cục bộ mang lại cho bạn quyền kiểm soát cao nhất. Bạn có thể chọn trọng số mô hình, tùy chỉnh quy trình làm việc, giữ tài nguyên trong môi trường của riêng mình và tránh việc phải trả phí cho nhà cung cấp dịch vụ lưu trữ cho mỗi lần tạo.

Quyền kiểm soát đó đi kèm với trách nhiệm về cơ sở hạ tầng. Bạn cần dung lượng GPU phù hợp cùng các phụ thuộc Python và CUDA chính xác. Bạn cũng cần đủ dung lượng lưu trữ và một môi trường làm việc cho từng dòng mô hình. Độ phân giải cao hơn và video dài hơn sẽ làm tăng yêu cầu về bộ nhớ và xử lý, và việc thêm một mô hình khác có thể đồng nghĩa với việc tải thêm trọng số hoặc duy trì một quy trình làm việc khác.

Điều này có thể xứng đáng đối với các đội ngũ đã vận hành cơ sở hạ tầng GPU hoặc yêu cầu xử lý cục bộ. Đây là một điểm khởi đầu nặng nề hơn khi mục tiêu của bạn là thêm tính năng tạo video nhanh chóng và thử nghiệm nhiều mô hình. Con đường sử dụng OpenRouter đã được lưu trữ sẵn giúp loại bỏ hầu hết các bước thiết lập đó, đây cũng là nội dung mà phần còn lại của hướng dẫn này đề cập.

Sử dụng một API lưu trữ thông qua OpenRouter

Chúng tôi giữ cho vòng đời tạo video nhất quán trên các mô hình video được hỗ trợ. Ứng dụng sử dụng cùng một API key, endpoint POST /api/v1/videos, luồng trạng thái công việc và quy trình truy xuất đầu ra, bất kể mô hình được chọn là Seedance, Veo, Wan hay một mô hình khác trong danh mục.

Các mô hình vẫn có những khả năng khác nhau. Một mô hình có thể hỗ trợ thời lượng dài hơn, trong khi mô hình khác cung cấp thêm các tỷ lệ khung hình, độ phân giải cao hơn, tạo âm thanh hoặc các tùy chọn kiểm soát đặc thù của nhà cung cấp. Chúng tôi hiển thị những khác biệt đó thông qua endpoint video-model thay vì ép buộc mọi mô hình phải có bộ tính năng giống hệt nhau.

Điều đó mang lại cho bạn một sự tích hợp ổn định mà không che giấu đi những điểm khác biệt của từng mô hình. Ứng dụng của bạn có thể truy vấn các khả năng hiện tại, xây dựng một yêu cầu hợp lệ và thay đổi mô hình mà không cần thay thế cơ sở hạ tầng công việc xung quanh.

Điều kiện tiên quyết và thiết lập

Bạn chỉ cần một API key của OpenRouter và một công cụ có thể gửi các yêu cầu HTTP. Các ví dụ ở đây sử dụng Python với thư viện requests và TypeScript với API fetch tích hợp sẵn, nhưng quy trình này hoạt động với bất kỳ ngôn ngữ nào có thể thực hiện yêu cầu HTTP.

Bắt đầu bằng việc tạo một API key từ tài khoản OpenRouter của bạn, sau đó lưu nó vào một biến môi trường thay vì thêm trực tiếp vào mã nguồn:

Đối với các ví dụ Python, hãy cài đặt requests nếu bạn chưa có:

OpenRouter xác thực các yêu cầu API bằng bearer token. Trong Python, chúng ta sẽ định nghĩa các giá trị dùng chung một lần và tái sử dụng chúng trong suốt hướng dẫn:

Trước khi gửi một công việc, bạn cũng có thể truy vấn endpoint video-model để xem những mô hình nào hiện đang khả dụng và mỗi mô hình hỗ trợ những gì:

Phản hồi bao gồm thời lượng, độ phân giải, tỷ lệ khung hình, hỗ trợ hình ảnh khung hình, khả năng âm thanh, SKU định giá và các tham số đặc thù của nhà cung cấp cho từng mô hình. Điều này đáng tin cậy hơn việc giả định rằng các thiết lập được chấp nhận bởi một mô hình video này cũng sẽ hoạt động với mô hình khác.

Bước 1: Gửi công việc tạo video

Gửi một yêu cầu POST đến /api/v1/videos với mô hình video. Bao gồm một prompt mô tả những gì bạn muốn tạo.

model là bắt buộc trong mọi yêu cầu, và prompt là bắt buộc đối với text-to-video. Các mô hình hỗ trợ tạo video chỉ từ đầu vào hình ảnh có thể bỏ qua prompt. Bạn cũng có thể cung cấp các thiết lập tùy chọn như thời lượng, độ phân giải, tỷ lệ khung hình, tạo âm thanh, hình ảnh tham chiếu và một seed khi mô hình được chọn hỗ trợ chúng.

Chúng ta sẽ sử dụng cùng một prompt trong suốt hướng dẫn:

Hàm sau đây gửi công việc bằng cách sử dụng Seedance 2.0:

Yêu cầu cURL tương đương là:

Một yêu cầu thành công sẽ trả về mã HTTP 202 Accepted. Phản hồi đại diện cho một công việc chạy nền, không phải là video đã hoàn thiện:

Hãy lưu lại job ID được trả về trước khi tiếp tục. Nếu quy trình của bạn khởi động lại, bạn sẽ có thể tiếp tục theo dõi công việc hiện tại thay vì phải gửi và trả phí cho một lần tạo khác.

Bước 2: Poll công việc cho đến khi hoàn tất

polling_url được trả về ở Bước 1 trỏ đến cùng một tài nguyên công việc mà bạn sẽ truy cập tại GET /api/v1/videos/{id}, chúng là cùng một endpoint. Một công việc video có thể chuyển qua các trạng thái sau:

Vòng lặp polling của bạn nên trả về kết quả khi trạng thái là completed và dừng lại với lỗi khi ở trạng thái failed, cancelled hoặc expired. Nếu không, ứng dụng có thể tiếp tục kiểm tra một công việc sẽ không bao giờ tạo ra video.