Hướng dẫn tích hợp API tạo ảnh của OpenRouter: Giải pháp tập trung cho lập trình viên

Việc thêm tính năng tạo ảnh vào ứng dụng sẽ trở nên khó khăn hơn khi bạn cần hỗ trợ nhiều nhà cung cấp cùng lúc. Hàng chục mô hình ảnh từ nhiều nhà cung cấp khác nhau sử dụng các endpoint, định dạng dữ liệu, cơ chế kiểm soát và mô hình thanh toán riêng biệt, với chi phí được tính theo từng ảnh, megapixel hoặc token.

Chúng tôi giải quyết vấn đề tích hợp này bằng một Image generation API chuyên dụng, sử dụng chung một định dạng yêu cầu và một khóa (key) duy nhất cho tất cả các mô hình được hỗ trợ.

Tóm tắt

Trong hướng dẫn này, bạn sẽ xây dựng các luồng Python và JavaScript có thể chạy được để gửi một prompt, giải mã và lưu ảnh trả về, sau đó truyền một ảnh tham chiếu vào endpoint và lưu biến thể ảnh được tạo ra.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy chuẩn bị sẵn những thứ sau:

Bước 1: Lấy khóa và chọn mô hình ảnh

Tạo một khóa trên trang keys, sau đó xuất (export) nó trong cùng terminal mà bạn sẽ dùng để chạy tập lệnh.

Chọn một mô hình từ bộ sưu tập image models. Hãy bắt đầu với bytedance-seed/seedream-4.5 cho lần chạy đầu tiên.

Bạn có thể chuyển đổi giữa các mô hình hỗ trợ tạo ảnh bằng cách thay đổi chuỗi mô hình (model string). Các tùy chọn kiểm soát như độ phân giải, nhiều đầu ra và đầu vào tham chiếu sẽ khác nhau tùy theo mô hình, vì vậy hãy kiểm tra bản ghi khả năng (capability record) trước khi thêm chúng vào.

Để khám phá trong thời gian chạy (runtime discovery), GET /api/v1/images/models sẽ trả về các slug hỗ trợ ảnh và các tham số được hỗ trợ. Mỗi mô hình cũng có các bản ghi endpoint với khả năng và giá cả cụ thể của từng nhà cung cấp. Bạn không cần các endpoint đó cho hướng dẫn này, nhưng chúng sẽ hữu ích khi tập lệnh này trở thành một tính năng sản phẩm.

Bước 2: Gửi yêu cầu tạo ảnh đầu tiên của bạn

Gửi một yêu cầu POST đến https://openrouter.ai/api/v1/images. Image API yêu cầu hai trường trong phần body. model dùng để chọn mô hình hỗ trợ tạo ảnh, trong khi prompt mô tả hình ảnh bạn muốn. Xác thực bằng khóa OpenRouter của bạn trong header Bearer.

Python

Việc kiểm tra response.ok trước khi phân tích cú pháp giúp các lỗi API hiển thị rõ ràng thay vì biến chúng thành các lỗi thiếu trường gây khó hiểu sau này.

JavaScript

Việc kiểm tra lỗi tường minh giúp bảo toàn phần body của phản hồi, nơi thường chứa thông tin chi tiết bạn cần để sửa yêu cầu.

Hình ảnh nằm ở đâu trong phản hồi?

Một phản hồi đệm (buffered response) thành công sẽ tuân theo cấu trúc rút gọn sau:

Chi phí ví dụ chỉ nhằm minh họa cấu trúc trường dữ liệu. Đây không phải là giá hiện tại.

data là một mảng vì một yêu cầu có thể trả về nhiều kết quả. Ảnh đầu tiên nằm tại data[0].b64_json. Giá trị đó chứa các byte được mã hóa base64, không phải URL được lưu trữ. media_type xuất hiện khi chúng tôi có thể xác định định dạng đầu ra. Giá trị tùy chọn usage.cost báo cáo chi phí của yêu cầu đã hoàn tất khi có sẵn.

Hiện tại, giá trị b64_json không rỗng xác nhận rằng quá trình tạo ảnh đã thành công. Bước tiếp theo là chuyển đổi các byte đó thành tệp ảnh cục bộ.

Bước 3: Giải mã và lưu output.png

Phản hồi cho thấy quá trình tạo ảnh đã hoạt động, nhưng hình ảnh vẫn là văn bản base64 bên trong JSON. Bước tiếp theo là giải mã b64_json thành các byte và ghi các byte đó vào đĩa. Cả hai tập lệnh bên dưới đều lặp lại yêu cầu để bạn có thể chạy độc lập từng tệp.

Python

Lưu tệp này dưới tên generate.py:

base64.b64decode chuyển đổi chuỗi phản hồi thành dữ liệu ảnh nhị phân gốc. Việc mở tệp đích với chế độ wb ngăn Python xử lý các byte đó như văn bản.

JavaScript

Lưu tệp này dưới tên generate.mjs:

Buffer.from(..., "base64") thực hiện chuyển đổi tương tự, trong khi writeFile lưu các byte thu được.

Chạy một trong hai phiên bản từ thư mục chứa tệp:

Đối với JavaScript, sử dụng:

Một lần chạy thành công sẽ in ra Saved output.png. Dòng chi phí chỉ xuất hiện khi phản hồi bao gồm usage.cost.

Định dạng đầu ra thay đổi tùy theo mô hình. Một số mô hình trả về byte JPEG hoặc WebP thay vì PNG. Nếu định dạng quan trọng đối với mục đích sử dụng của bạn, hãy đọc media_type từ phản hồi và chọn phần mở rộng tệp cho phù hợp.

Bước 4: Thêm ảnh tham chiếu

Ảnh tham chiếu cung cấp cho mô hình tài liệu trực quan để làm việc thay vì chỉ dựa vào prompt. Nó được thêm thông qua input_references.

Đối với tệp cục bộ, hãy đọc các byte, mã hóa chúng dưới dạng base64 và thêm loại phương tiện (media type) chính xác vào phía trước để tạo thành một data URL.

Đặt tệp ảnh product.jpg vào cùng thư mục dự án với tập lệnh, sau đó tạo tệp reference.py:

Chạy nó từ cùng thư mục: