Hướng dẫn chi tiết: Cách gửi hình ảnh tới các mô hình đa phương thức qua OpenRouter API

Nếu bạn muốn một Large Language Model (LLM) có khả năng thị giác đọc ảnh chụp màn hình, kiểm tra biểu đồ hoặc trả lời các câu hỏi về một bức ảnh, bạn cần xây dựng phần thân yêu cầu (request body) một cách chính xác. Hướng dẫn này chỉ bao gồm đầu vào là hình ảnh, nghĩa là mô hình sẽ đọc một bức ảnh bạn cung cấp, chứ không phải tạo hoặc chỉnh sửa ảnh.

Mô hình này rất đơn giản. Hãy gửi một tin nhắn chat mà mảng nội dung (content array) bao gồm một phần văn bản (text part) và một phần image_url đến endpoint hiểu hình ảnh của chúng tôi. Sau đó, cấu trúc yêu cầu vẫn giữ nguyên, bạn chỉ cần thay đổi trường model để sử dụng bất kỳ mô hình có khả năng thị giác nào mà chúng tôi hỗ trợ.

Một mô hình có thể xử lý nhận dạng ký tự quang học (OCR) tốt hơn, một mô hình khác đọc ảnh chụp màn hình giao diện người dùng (UI) đáng tin cậy hơn, và một mô hình khác lại suy luận về biểu đồ cẩn thận hơn. Vì cấu trúc đầu vào không thay đổi, bạn có thể kiểm tra những khác biệt đó mà không cần thay đổi tích hợp của mình.

Hướng dẫn này bao gồm việc gửi hình ảnh đến các mô hình đa phương thức (multimodal), lựa chọn giữa URL công khai và tải lên base64, xây dựng các pipeline RAG đa phương thức và các giới hạn thực tế cần lưu ý khi bạn đã triển khai trong môi trường production.

Tóm tắt (Tl;dr)

Chúng tôi hỗ trợ khả năng hiểu hình ảnh đa phương thức thông qua Chat Completions API.

Yêu cầu cơ bản: đính kèm một hình ảnh vào một cuộc gọi chat.

Yêu cầu bao gồm một tin nhắn người dùng với hai phần trong mảng nội dung: một phần văn bản và một phần image_url. Phần còn lại của hướng dẫn này được xây dựng dựa trên yêu cầu này.

Mảng nội dung tin nhắn (The message content array)

Chat chỉ có văn bản sẽ gửi nội dung dưới dạng một chuỗi thuần túy. Khi bạn thêm một hình ảnh, nội dung sẽ trở thành một mảng các đối tượng có kiểu dữ liệu (typed objects):

Thứ tự ở đây rất quan trọng, vì vậy hãy đặt phần văn bản lên trước. Đó là cách chúng tôi phân tích mảng. Nếu trường hợp sử dụng của bạn thực sự cần hình ảnh được tham chiếu trước bất kỳ văn bản nào, hãy chuyển phần khung đó vào system prompt thay vì cố gắng sắp xếp lại mảng nội dung.

URL dữ liệu base64 so với URL hình ảnh được lưu trữ: khi nào nên sử dụng loại nào?

Trường image_url.url chấp nhận hai định dạng: một liên kết HTTP(S) công khai thông thường hoặc một URL dữ liệu base64 được định dạng là data:image/jpeg;base64,<encoded-bytes>. Việc sử dụng loại nào phụ thuộc vào nơi lưu trữ tệp tin hiện tại của bạn.

Nếu hình ảnh đã được lưu trữ ở một nơi công khai, như CDN, S3 bucket với liên kết đã ký (signed link) hoặc máy chủ của riêng bạn, hãy truyền URL đó. Yêu cầu sẽ giữ được kích thước nhỏ và nhà cung cấp sẽ tự lấy dữ liệu byte.

Nếu hình ảnh là tệp cục bộ hoặc không nên có URL công khai (ví dụ: ID do người dùng tải lên hoặc tài liệu nội bộ), hãy mã hóa nó dưới dạng base64 và đưa vào yêu cầu. Yêu cầu sẽ lớn hơn và quá trình tải lên mất nhiều thời gian hơn, nhưng tệp tin chỉ rời khỏi hệ thống của bạn thông qua chính lệnh gọi API đó.

Base64 có một ưu điểm thứ hai. Các URL được lưu trữ có thể bị lỗi do kiểm soát truy cập, chặn theo khu vực hoặc URL đã ký hết hạn. Những lỗi đó không thể xảy ra khi dữ liệu byte đã nằm sẵn trong yêu cầu. Cả hai định dạng đều hỗ trợ PNG, JPEG, WebP và GIF.

Ví dụ có thể chạy được bằng cURL, Python và TypeScript.

Cùng một yêu cầu, ba ngôn ngữ. Dòng duy nhất thay đổi giữa các mô hình là MODEL.

cURL (URL được lưu trữ)

Python (tệp cục bộ → base64)

TypeScript (tệp cục bộ → base64)

Lựa chọn mô hình thị giác (vision model)

Mọi mô hình thị giác trên OpenRouter đều sử dụng cùng một cấu trúc yêu cầu. Để chuyển đổi mô hình, hãy thay đổi trường model và giữ nguyên mọi thứ khác. Điều này cho phép bạn so sánh các mô hình mà không cần thay đổi tích hợp của mình.

Điều gì tạo nên một mô hình có khả năng thị giác?

Không phải mọi mô hình trong danh mục đều có thể đọc hình ảnh. Một mô hình được coi là mô hình ngôn ngữ thị giác (VLM) khi nó kết hợp một mô hình văn bản với một bộ mã hóa hình ảnh (image encoder), cho phép nó tiếp nhận các pixel cùng với các token. Trên OpenRouter, bạn có thể kiểm tra điều này trực tiếp: kiến trúc của mô hình sẽ liệt kê image trong phần input_modalities nếu nó hỗ trợ đầu vào là hình ảnh. Nếu bạn gửi phần image_url đến một mô hình không liệt kê tính năng này, yêu cầu sẽ thất bại. Hãy kiểm tra danh mục trước.

Chi phí, cửa sổ ngữ cảnh (context window) và thế mạnh của từng mô hình.

Cấu trúc yêu cầu giống nhau giữa các mô hình này, nhưng cách các mô hình hoạt động lại khác nhau. Giá cả, cửa sổ ngữ cảnh, độ trễ và khả năng xử lý OCR, biểu đồ hoặc hiểu bối cảnh chung của mô hình đều khác nhau. Hãy kiểm tra các mô hình ứng viên với hình ảnh thực tế của bạn trước khi quyết định chọn một mô hình.

Giá cả và cửa sổ ngữ cảnh thay đổi theo từng mô hình. Hãy coi bảng này là minh họa và lấy số liệu trực tiếp từ /models trước khi dựa vào chúng.

Lọc danh mục các mô hình có khả năng thị giác.

Hãy truy vấn danh mục thay vì mã hóa cứng (hard-coding) danh sách mô hình.

Vì phần thân yêu cầu giống hệt nhau trên tất cả các mô hình, bạn có thể chọn bất kỳ mô hình nào từ danh sách này tại thời điểm gửi yêu cầu. Hãy sắp xếp theo giá, cửa sổ ngữ cảnh hoặc bất cứ tiêu chí nào mà ứng dụng của bạn quan tâm, thay vì mã hóa cứng một mô hình ngay từ đầu.

Gửi nhiều hình ảnh và tài liệu dài.

Nhiều hình ảnh trong một yêu cầu.

Bạn không bị giới hạn ở một hình ảnh mỗi yêu cầu. Hãy thêm bao nhiêu phần image_url vào mảng nội dung tùy thích. Đây là cách bạn xử lý các so sánh trước-sau, quét tài liệu nhiều trang hoặc một câu hỏi bao gồm nhiều biểu đồ cùng lúc:

Các giới hạn thực tế: số lượng hình ảnh, độ phân giải và chi phí token.

Không có giới hạn chung nào cả. Các giới hạn được thiết lập theo từng nhà cung cấp và từng mô hình. Một vài hình ảnh mỗi yêu cầu thường là ổn, nhưng hãy kiểm tra trang endpoint của mô hình cụ thể trước khi gửi hàng chục hình ảnh cùng lúc. Mỗi hình ảnh đều thêm token, vì vậy chi phí tăng theo cả số lượng hình ảnh và độ phân giải, đặc biệt là khi bạn gửi toàn bộ tài liệu đã quét.

Khi nào nên giảm độ phân giải hoặc cắt ảnh (pre-crop) trước khi gửi.

Một bức ảnh chụp hóa đơn bằng điện thoại thường rộng 4000 pixel. Không mô hình nào cần độ phân giải lớn như vậy để đọc tổng số tiền ở phía dưới. Hãy thu nhỏ hình ảnh xuống kích thước nhỏ nhất mà văn bản vẫn còn đọc được. Nếu bạn đã biết phần nào của hình ảnh là quan trọng, hãy cắt lấy vùng đó. Cả hai bước này đều giúp giảm chi phí token. Việc cắt ảnh cũng có xu hướng cải thiện độ chính xác vì nó loại bỏ các nội dung hình ảnh không cần thiết mà mô hình sẽ phải xử lý.

Cách thức hoạt động của việc token hóa hình ảnh (image tokenization).