Hướng dẫn sử dụng API OpenRouter để chỉnh sửa ảnh với Nano Banana 2

Hướng dẫn này chỉ cho bạn cách chỉnh sửa hình ảnh bằng câu lệnh văn bản (text prompt) trong mã nguồn. Bạn gửi hình ảnh gốc và câu lệnh chỉnh sửa đến google/gemini-3.1-flash-image thông qua OpenRouter API, và hình ảnh đã chỉnh sửa sẽ được trả về trong phản hồi. “Nano Banana” là biệt danh cho các mô hình hình ảnh Gemini của Google. Slug này là Nano Banana 2, mô hình nhanh mặc định trong dòng sản phẩm đó. Vì bạn truy cập nó thông qua một API duy nhất, bạn có thể sử dụng một mô hình chỉnh sửa khác sau này chỉ bằng cách thay đổi một trường.

Chỉnh sửa hình ảnh là thay đổi một hình ảnh hiện có. Tạo hình ảnh là tạo ra một hình ảnh mới từ văn bản. Hướng dẫn này tập trung vào việc chỉnh sửa, vì vậy mọi yêu cầu ở đây đều bao gồm một hình ảnh gốc. Để tạo hình ảnh từ văn bản, hãy xem tài liệu về tạo hình ảnh hoặc hướng dẫn tạo hình ảnh.

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

Bạn cần ba thứ:

Mô hình nào để sử dụng

Mặc định trong hướng dẫn này là google/gemini-3.1-flash-image, tức Nano Banana 2. Nó nhận hình ảnh làm đầu vào và trả về hình ảnh đã chỉnh sửa. Dòng Nano Banana hiện có bốn thành viên: Nano Banana 2 (google/gemini-3.1-flash-image) là mặc định trong hướng dẫn này, Nano Banana 2 Lite (google/gemini-3.1-flash-lite-image) là rẻ nhất và nhanh nhất, Nano Banana Pro (google/gemini-3-pro-image) chậm hơn nhưng có chất lượng cao hơn, và Nano Banana gốc (google/gemini-2.5-flash-image) là mô hình cũ hơn mà biệt danh này bắt nguồn từ đó.

Danh mục hình ảnh thay đổi thường xuyên. Các mô hình được thêm vào, ngừng hỗ trợ và thay đổi giá, vì vậy một slug bạn ghim hôm nay có thể bị loại bỏ sau này. Trước khi xây dựng ứng dụng dựa trên một mô hình, hãy kiểm tra xem nó có chấp nhận đầu vào là hình ảnh và hỗ trợ các tính năng chỉnh sửa bạn cần hay không. Bạn có thể duyệt qua các mô hình có khả năng chỉnh sửa trong bộ sưu tập mô hình hình ảnh. Để xem hướng dẫn chi tiết về danh mục, hãy xem các mô hình tạo hình ảnh.

Các mẫu dưới đây sử dụng slug hiển thị trong mỗi yêu cầu, vì vậy bạn có thể chạy chúng như đã viết và thay đổi mô hình sau. Hãy giữ khóa API của bạn trong một biến môi trường, không để trong mã nguồn:

Lần chỉnh sửa hình ảnh đầu tiên của bạn

Để chỉnh sửa hình ảnh, hãy gửi hình ảnh gốc và hướng dẫn bằng văn bản trong một yêu cầu duy nhất. Hình ảnh đã chỉnh sửa sẽ được trả về trong phản hồi. Dưới đây là một yêu cầu hoạt động bằng Python giúp mã hóa một tệp cục bộ:

Yêu cầu tương tự bằng TypeScript:

Phần thân yêu cầu (request body) giống nhau ở cả hai ngôn ngữ. Đặt hình ảnh tham chiếu vào input_references và hướng dẫn vào prompt. Đó là toàn bộ yêu cầu.

Mã hóa hình ảnh đầu vào: base64 hoặc URL

Trường input_references chấp nhận URL dữ liệu base64 hoặc URL HTTP(S). Các ví dụ trên mã hóa một tệp cục bộ. Nếu hình ảnh của bạn đã được lưu trữ công khai, hãy truyền trực tiếp liên kết và bỏ qua bước mã hóa:

Sử dụng URL khi hình ảnh công khai và đã được lưu trữ, vì nó giúp phần thân yêu cầu nhỏ gọn. Sử dụng base64 cho các tệp cục bộ hoặc tệp riêng tư. Gemini chấp nhận các đầu vào image/png, image/jpeg, image/webp, image/heic và image/heif. Các định dạng được hỗ trợ khác nhau tùy theo mô hình, vì vậy hãy kiểm tra trang mô hình trước khi gửi.

Truy xuất hình ảnh đã chỉnh sửa từ phản hồi

API trả về hình ảnh đã chỉnh sửa dưới dạng dữ liệu base64 trong mảng data. Giải mã giá trị b64_json và ghi nó vào một tệp:

Phiên bản TypeScript:

Mở edited.png để xem kết quả. Nếu bạn muốn một client có kiểu dữ liệu (typed client) thay vì HTTP thô, OpenRouter SDK có một tài nguyên images gọi đến cùng một endpoint:

Cài đặt SDK bằng pip install openrouter. Nó sử dụng lại api_key đã xác định trước đó, vì vậy không cần thiết lập thêm.

Viết câu lệnh chỉnh sửa (edit prompts)

Một câu lệnh tạo hình ảnh mô tả một hình ảnh hoàn toàn mới. Một câu lệnh chỉnh sửa cho biết những gì cần thay đổi và những gì cần giữ nguyên. Hãy nêu thay đổi trước, sau đó nêu những gì phải giữ nguyên:

Bạn cũng có thể viết câu lệnh dưới dạng một khối văn bản JSON nhỏ:

API xử lý nội dung này như văn bản thuần túy, vì vậy đây không phải là một chế độ đặc biệt. Cấu trúc này có thể giúp mô hình phân biệt những gì cần thay đổi và những gì cần giữ lại. Hãy thử cả dạng câu và dạng JSON trên hình ảnh của riêng bạn và giữ lại dạng nào hiệu quả hơn.

Chỉnh sửa kết quả một lần nữa

Một lần chỉnh sửa không phải lúc nào cũng mang lại kết quả như ý. Để thực hiện lượt chỉnh sửa tiếp theo, hãy gửi lại hình ảnh đã nhận được làm đầu vào cho lần sau. Lấy giá trị b64_json từ phản hồi, chuyển nó thành URL dữ liệu và truyền vào input_references tiếp theo:

Mỗi lần gọi sẽ chỉnh sửa kết quả cuối cùng, vì vậy các thay đổi trước đó sẽ được kế thừa. Hãy đưa ra một hướng dẫn cho mỗi lần gọi. Các chỉnh sửa nhỏ dễ kiểm tra và dễ thực hiện lại hơn khi kết quả không như ý. Mô hình không ghi nhớ các câu lệnh trước đó của bạn, vì vậy hãy lặp lại các phần cần giữ nguyên trong mỗi câu lệnh mới.

Thay đổi mô hình chỉnh sửa

Để gửi cùng một yêu cầu chỉnh sửa đến một mô hình khác, hãy thay đổi trường model. Hình ảnh gốc, câu lệnh và mã xử lý phản hồi vẫn giữ nguyên:

Sử dụng google/gemini-3.1-flash-image làm mặc định nhanh. Sử dụng google/gemini-3.1-flash-lite-image khi bạn muốn mức giá thấp nhất. Sử dụng google/gemini-3-pro-image khi bạn muốn chất lượng cao hơn và có thể chấp nhận độ trễ lớn hơn. Mô hình google/gemini-2.5-flash-image gốc vẫn hoạt động với cùng cấu trúc yêu cầu, nhưng các mô hình mới hơn ở trên là lựa chọn mặc định tốt hơn. Sử dụng mô hình từ nhà cung cấp khác, chẳng hạn như openai/gpt-5-image, khi bạn muốn so sánh chất lượng, chi phí hoặc tốc độ trên hình ảnh của mình. Việc thay đổi một trường này chỉ hoạt động với các mô hình chấp nhận đầu vào hình ảnh và hỗ trợ cấu trúc input_references tương tự, vì vậy hãy kiểm tra xem mô hình đó có khả năng chỉnh sửa hay không trước khi chuyển đổi.

Để thiết lập mô hình và các tùy chọn theo môi trường thay vì trong mã nguồn, hãy sử dụng OpenRouter Presets.

Lỗi và chi phí

Những lỗi này khá phổ biến nên cần có kế hoạch dự phòng:

Phản hồi sẽ báo cáo chi phí của mỗi yêu cầu bằng USD khi có dữ liệu sử dụng. Hãy ghi nhật ký để theo dõi chi tiêu:

Đối với các công việc hàng loạt (batch jobs), hãy duy trì trong giới hạn tốc độ (rate limits). Thử lại các phản hồi 429 và 5xx với độ trễ tăng dần giữa các lần thử, và giới hạn số lượng chỉnh sửa chạy cùng lúc. Lưu từng hình ảnh được trả về trước khi bắt đầu chỉnh sửa tiếp theo, để một lỗi xảy ra không làm mất đi công việc đã hoàn thành.

Các bước tiếp theo

Sao chép yêu cầu đầu tiên, sử dụng hình ảnh của riêng bạn và chạy thử một lần chỉnh sửa. Để tạo hình ảnh từ văn bản thay thế, hãy xem tài liệu về tạo hình ảnh. Để tìm các mô hình có khả năng chỉnh sửa hiện tại, hãy duyệt qua bộ sưu tập mô hình hình ảnh.

Bài gốc còn tiếp — xem tiếp tại bài gốc ↗