OpenRouter ra mắt API chuyên dụng cho các mô hình tạo ảnh

Bạn kết nối với một nhà cung cấp dịch vụ tạo ảnh, thiết lập cho nó hoạt động, rồi một tuần sau, bạn lại cần đọc một hình ảnh. Có thể là OCR trên hóa đơn đã tải lên, quét nhanh để phát hiện đối tượng trước khi lưu tài sản, hoặc tạo văn bản thay thế (alt-text) để hỗ trợ truy cập. Đó là một công việc khác. Với hầu hết các nhà cung cấp, điều này đồng nghĩa với việc phải dùng thêm SDK thứ hai, API key thứ hai và quy trình thanh toán thứ hai.

Trên OpenRouter, cả hai công việc đều chạy qua một URL cơ sở duy nhất, https://openrouter.ai/api/v1, với một API key và một hóa đơn duy nhất. Để tạo ảnh, hãy gửi POST một prompt đến /images. Để đọc ảnh, hãy gửi nó đến một mô hình thị giác (vision model) tại /chat/completions.

Danh mục mô hình đằng sau các endpoint đó bao gồm các phòng thí nghiệm hình ảnh lớn, đồng thời tính năng định tuyến (routing) và chuyển đổi dự phòng (failover) của nhà cung cấp hoạt động trên các lệnh gọi hình ảnh tương tự như trên các lệnh gọi trò chuyện.

Tóm tắt (Tl;dr)

Tôi có thể tạo và đọc hình ảnh thông qua một API duy nhất không?

Có, thông qua một URL cơ sở và một API key duy nhất. Để tạo ảnh, hãy gửi POST một prompt đến Image API chuyên dụng. Để đọc ảnh, hãy gửi nó đến một mô hình thị giác tại endpoint Chat Completions tiêu chuẩn.

Một ứng dụng đã có tính năng tạo ảnh có thể thêm khả năng thị giác với cùng một key và tài khoản thanh toán. Chỉ có endpoint và cấu trúc yêu cầu là thay đổi.

Những mô hình hình ảnh nào hiện có sẵn?

Danh mục bao gồm Google (họ mô hình Gemini image), OpenAI (GPT Image), Black Forest Labs (FLUX), xAI (Grok Imagine), ByteDance (Seedream), Microsoft (MAI-Image), Recraft, Krea và Sourceful (Riverflow). Tên mô hình cụ thể thay đổi theo từng bản phát hành, vì vậy để biết danh sách hiện tại, khả năng và giá cả theo từng mô hình, hãy sử dụng danh mục mô hình hình ảnh.

Ba cách để tìm một mô hình hình ảnh:

Làm thế nào để tôi tạo một hình ảnh?

Gửi một yêu cầu POST đến /api/v1/images với một mô hình và một prompt. Hình ảnh sẽ trả về trong mảng data dưới dạng base64.

Mỗi mục trong data chứa hình ảnh dưới dạng base64 trong b64_json, cộng với trường media_type (thường là image/png; các mô hình vector của Recraft có thể trả về image/svg+xml). Trường usage báo cáo số lượng token và chi phí của yêu cầu. Bạn có thể yêu cầu tối đa 10 hình ảnh mỗi lần gọi với tham số n (không phải nhà cung cấp nào cũng hỗ trợ n > 1), và hãy lặp qua mảng data thay vì cố định chỉ số 0.

Kiểm soát kích thước, chất lượng và định dạng

Phần thân yêu cầu (request body) nhận trực tiếp các trường dành riêng cho hình ảnh:

Kiểm tra supported_parameters của mô hình trong GET /api/v1/images/models để biết mỗi endpoint chấp nhận những gì. Các nhà cung cấp cũng có thể nhận các tùy chọn riêng thông qua provider.options, và các mô hình có supports_streaming: true có thể truyền phát (stream) các phần hình ảnh qua SSE với stream: true. Tài liệu về tạo ảnh bao gồm toàn bộ lược đồ yêu cầu.

Làm thế nào để tôi phân tích hoặc đọc một hình ảnh?

Gửi một mảng messages chứa một phần văn bản và một phần image_url đến một mô hình thị giác tại /chat/completions. Bạn sẽ nhận lại một văn bản hoàn thiện (text completion). image_url chấp nhận cả URL công khai hoặc URL dữ liệu base64.

Phản hồi trả về dưới dạng văn bản hoàn thiện tiêu chuẩn, với câu trả lời của mô hình nằm trong choices[0].message.content.

Bốn hành vi cần lên kế hoạch:

Đối với tệp PDF, hãy sử dụng loại nội dung tệp (file content type) thay vì hiển thị các trang thành hình ảnh trước. OpenRouter cũng hỗ trợ đầu vào âm thanh và video thông qua cùng một endpoint, sử dụng cùng một mô hình thay đổi mô hình và loại nội dung. Tổng quan về đa phương thức (multimodal) bao gồm mọi loại đầu vào.

Tạo hay hiểu: tôi cần cái nào?

Sử dụng tạo ảnh (generation) khi đầu ra là một tài sản hình ảnh mới: bản thiết kế (mockup), ảnh sản phẩm, hình minh họa, nội dung sáng tạo tiếp thị, bất cứ thứ gì bắt đầu bằng một prompt văn bản và kết thúc bằng các điểm ảnh (pixels).

Sử dụng hiểu ảnh (understanding) khi bạn đã có sẵn hình ảnh và cần thông tin từ nó: OCR trên hóa đơn và biểu mẫu, văn bản thay thế (alt-text) để hỗ trợ truy cập, phát hiện đối tượng hoặc lỗi trên dây chuyền sản xuất, phân loại hoặc mô tả đơn thuần.

Endpoint bạn gọi cho chúng tôi biết bạn đang thực hiện công việc nào. Tạo ảnh gửi đến /api/v1/images; hiểu ảnh gửi đến /chat/completions. Cả hai đều sử dụng cùng một API key và nằm trên cùng một hóa đơn.

Có một tùy chọn thứ ba cho các ứng dụng mà trong đó chính cuộc trò chuyện sẽ quyết định khi nào cần hình ảnh. Công cụ máy chủ openrouter:image_generation (beta) cho phép một mô hình trò chuyện tạo hình ảnh ngay trong cuộc trò chuyện mà mã ứng dụng của bạn không cần thực hiện lệnh gọi đó một cách rõ ràng. Thêm { "type": "openrouter:image_generation" } vào mảng tools của yêu cầu, và mô hình sẽ xác định khi nào cần gọi nó. Mặc định là openai/gpt-5-image. Tài liệu về công cụ máy chủ bao gồm các tham số khả dụng.

Định tuyến và chuyển đổi dự phòng có hoạt động cho các lệnh gọi hình ảnh không?

Có. Trên /api/v1/images, đối tượng provider chấp nhận order, only, ignore, sort và allow_fallbacks. Một mô hình hình ảnh được phục vụ bởi nhiều nhà cung cấp có thể chuyển đổi dự phòng giữa chúng nếu nhà cung cấp đầu tiên không khả dụng hoặc chậm.

Yêu cầu này ưu tiên một nhà cung cấp và chuyển sang nhà cung cấp tiếp theo nếu nó thất bại. Các lệnh gọi thị giác trên /chat/completions sử dụng toàn bộ đối tượng nhà cung cấp trò chuyện, bao gồm data_collection: "deny".

Bạn trả phí theo mức giá danh mục mà không có phụ phí từ chúng tôi. Theo chính sách Zero Completion Insurance, một lệnh gọi hình ảnh bị chuyển đổi dự phòng và không bao giờ hoàn tất sẽ không bị tính phí. Để biết cách bộ định tuyến chọn nhà cung cấp, hãy xem cách thức hoạt động của định tuyến mô hình OpenRouter.

Có cách nào để tạo hình ảnh miễn phí không?

Hiện tại là không. Gói miễn phí bao gồm các mô hình có hậu tố:free với giới hạn 50 yêu cầu/ngày và 20 RPM mà không cần thẻ tín dụng (1.000 yêu cầu/ngày với 10 đô la tín dụng trở lên), và hiện tại không có mô hình tạo ảnh nào mang hậu tố đó. Nhóm miễn phí thay đổi khi các mô hình mới xuất hiện hoặc bị loại bỏ, vì vậy bạn nên kiểm tra lại tại /models?output_modalities=image.

Do đó, việc tạo ảnh sẽ trừ vào số dư tín dụng của bạn, nhưng chi phí thử nghiệm rất thấp. Giá mỗi hình ảnh trên các mô hình chi phí thấp bắt đầu khoảng một xu, và trường usage.cost của mỗi phản hồi sẽ báo cáo chi phí của yêu cầu đó. Hướng dẫn về các mô hình miễn phí bao gồm cơ chế của gói miễn phí cho các mô hình văn bản.

Làm thế nào để tôi sửa lỗi “no endpoints found that support image input”?

Lỗi này có nghĩa là bạn đã gửi một image_url đến một mô hình không chấp nhận đầu vào hình ảnh. Chúng tôi tự động lọc các mô hình khả dụng theo nội dung yêu cầu, vì vậy khi mô hình bạn đặt tên không có endpoint khả dụng nào hỗ trợ hình ảnh, yêu cầu sẽ thất bại với lỗi này thay vì âm thầm loại bỏ hình ảnh.

Sửa lỗi này trong ba bước:

Các lỗi tương tự như "no endpoints found that support tool use" và các biến thể về chính sách dữ liệu cũng hoạt động theo cách tương tự. Tên lỗi chỉ ra yêu cầu không khớp; hãy nới lỏng yêu cầu đó hoặc chọn một sự kết hợp giữa mô hình và nhà cung cấp đáp ứng được yêu cầu đó.

Tôi nên lập kế hoạch dựa trên những giới hạn nào?

Hãy bắt đầu với danh mục mô hình hình ảnh, kiểm tra prompt trong Chatroom và kết nối lệnh gọi bằng các đoạn mã ở trên.