Chuyển API ảnh sang SeedRouter: yêu cầu và tác vụ chạy nền

Chuyển một API ảnh sang SeedRouter đòi hỏi kiểm tra hợp đồng yêu cầu và phản hồi, chứ không chỉ thay khóa API và địa chỉ gốc. GPT Image 2 dùng những trường tạo ảnh quen thuộc, nhưng lần gửi trả về một mã tác vụ. Ứng dụng của bạn phải lưu mã đó, hỏi trạng thái tới khi hoàn tất rồi đọc các URL ảnh đã xong.

Bước chuyển nhỏ nhất mà vẫn có ích là một yêu cầu từ chữ sang ảnh chạy trong mã phía máy chủ. Hãy làm nó chạy được trước khi chuyển phần sửa theo ảnh tham chiếu, mặt nạ hay một lô lớn. Giữ tích hợp cũ sẵn sàng cho tới khi đường đi mới vượt qua đúng những bài kiểm tra nghiệm thu đó.

Những giả định nào phải thay đổi?

Hãy tìm đoạn mã biến một yêu cầu ảnh thành tệp dùng được. Hiện nó có thể đang chờ ảnh ngay trong phản hồi đầu tiên, giải mã một trường base64 hoặc tải lên kiểu multipart. Từng giả định đó phải được đối chiếu riêng với tài liệu GPT Image 2 của SeedRouter.

Giả định hiện tại	Hợp đồng của SeedRouter	Thay đổi trong ứng dụng
Lần gửi trả về ảnh đã xong	Lần gửi trả về một tham chiếu tác vụ	Lưu `id` trước khi chờ kết quả
Kết quả nằm trong mảng `data` của lần gửi	Ảnh của tác vụ đã xong nằm trong `output.data`	Đọc kết quả sau khi tác vụ hoàn tất
Client giải mã `b64_json`	Ảnh được trả về dưới dạng URL đã lưu trữ	Tải về theo các URL được trả
Chỉnh sửa tải lên byte của tệp	Ảnh tham chiếu dùng đối tượng URL trong `images`	Cho phép truy cập ảnh đầu vào qua URL
Một đường dẫn sửa riêng chọn chế độ chỉnh sửa	`images` và `mask` quyết định thao tác	Dùng endpoint tạo ảnh công khai
Hết thời gian chờ nghĩa là ảnh đã hỏng	Tác vụ có thể vẫn đang chạy	Hỏi lại mã tác vụ đã lưu

Vì vậy một lời gọi SDK ảnh kiểu đồng bộ không phải bản thay thế trực tiếp, kể cả khi nó cho phép đổi địa chỉ gốc. Hãy giữ những thiết lập mô hình bạn vẫn cần, nhưng sửa lại phần mã ứng dụng chờ và xử lý kết quả.

Đối chiếu các trường yêu cầu trước khi sửa mã

Hãy bắt đầu với model, prompt, size, quality và n. Dùng gpt-image-2 làm mã mô hình. Gửi kích thước tường minh như 1024x1024 hoặc dùng auto; đừng mang theo một trường resolution riêng hay một chuỗi tỷ lệ khung hình để làm kích thước.

Tài liệu OpenAPI của SeedRouter là thứ nên mở kèm khi rà soát. Hãy so sánh những trường mà ứng dụng thực sự gửi đi, kể cả giá trị do SDK tự thêm, thay vì chỉ xem các tham số nhìn thấy tại chỗ gọi hàm. Trường lạ sẽ bị từ chối.

Với mô hình này, style, response_format và một input_fidelity tùy chỉnh không phải trường yêu cầu hợp lệ. Hãy loại bỏ các giả định đó thay vì giấu chúng trong một đối tượng tùy chọn chung chung. Yêu cầu cũng không hỗ trợ stream hay partial_images; tiến độ trong tích hợp này được báo qua trạng thái tác vụ.

Các thiết lập đầu ra ràng buộc lẫn nhau. Nếu yêu cầu nền trong suốt, hãy chọn PNG. Chỉ gửi output_compression cho JPEG, không gửi cho PNG. Giá trị nén bằng không là hợp lệ, nên tránh kiểu kiểm tra "có giá trị hay không" rồi thay nó bằng mặc định. Đây là những chi tiết nhỏ mà một yêu cầu cơ bản thành công sẽ không chạm tới.

Bỏ giả định về phản hồi đồng bộ

Ví dụ Node.js sau gửi một yêu cầu và in ra mã tác vụ của nó. Hãy đặt SEEDROUTER_API_KEY trên máy chủ; tuyệt đối không để khóa trong mã chạy ở trình duyệt hay trong biến môi trường công khai.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

In mã tác vụ ra là đủ cho một lần thử thủ công. Trong ứng dụng, hãy lưu mã đó trước khi trả quyền điều khiển lại cho người dùng. Khi ấy bản ghi ảnh vẫn ở trạng thái chờ trong lúc người dùng đi sang trang khác, và một lần kiểm tra sau sẽ lấy lại được kết quả.

Dùng GET https://api.seedrouter.ai/v1/tasks/{id} với đúng header ủy quyền đó để xem tiến độ. Khi completed, hãy đọc output.data[].url. Khi failed, hãy xử lý lỗi đã ghi trong tài liệu và hiển thị trạng thái thất bại phù hợp. Muốn một ví dụ chạy được có lưu tiến độ, xem gửi theo lô và hỏi trạng thái.

Đừng gắn khóa API vào yêu cầu tải ảnh. Ủy quyền thuộc về lời gọi API tác vụ, không thuộc về một lần tải riêng theo URL tệp được trả.

Chuyển ảnh tham chiếu và mặt nạ sang đầu vào URL

Quy trình đang dùng tệp cục bộ cần thêm một bước chuẩn bị: đưa ảnh tham chiếu lên một URL HTTP(S) truy cập được do bạn kiểm soát. Hãy truyền nó dưới dạng images: [{"image_url": "https://example.com/reference.png"}] và thay địa chỉ đó bằng địa chỉ của bạn. Đừng gửi đường dẫn tệp, URL blob:, data URL base64 hay Files ID.

Hãy kiểm tra URL có hoạt động khi không có cookie đăng nhập của trình duyệt hay không. Một URL chỉ mở được trong phiên đã đăng nhập của bạn thì không dùng làm ảnh tham chiếu cho yêu cầu này. Giữ ảnh ở trạng thái truy cập được trong lúc tác vụ đang chạy; đừng thu hồi quyền truy cập ngay sau khi gửi.

Mặt nạ dùng dạng mask: {"image_url": "https://example.com/mask.png"} và bắt buộc phải có ảnh tham chiếu. Nó phải trùng kích thước với ảnh tham chiếu đầu tiên. Hãy đọc toàn bộ giới hạn đầu vào media trước khi chuyển một luồng chỉnh sửa có sẵn, đặc biệt là định dạng và dung lượng tệp.

Bài kiểm tra nghiệm thu nên bao gồm những gì?

Hãy kiểm tra đúng hành vi mà ứng dụng phụ thuộc vào, kể cả khi bị gián đoạn. Một tấm ảnh thành công chỉ chứng minh rằng một yêu cầu đã chạy được. Nó không chứng minh trạng thái chờ của bạn sống sót qua một lần tải lại trang, hay một lỗi tải về sẽ không dẫn tới việc tạo ảnh trùng lặp.

Gửi một yêu cầu chỉ có chữ và lưu mã trả về trước khi bắt đầu hỏi trạng thái.
Dừng vòng hỏi, chạy lại với đúng mã đó và xác nhận không có lệnh POST nào phát sinh thêm.
Xử lý processing, completed và failed như ba trạng thái riêng biệt.
Tải một ảnh đã hoàn tất mà không gửi kèm header ủy quyền của API.
Thử một lần sửa theo ảnh tham chiếu với URL truy cập được, rồi kiểm tra cách xử lý lỗi với URL không truy cập được.
Kiểm tra các trường tùy chọn, gồm cả mức nén bằng không, theo schema đã công bố.
Xác nhận khoản trừ được đọc từ lịch sử sử dụng, không phải từ một trường chi phí tự nghĩ ra trong phản hồi tác vụ.

Hãy dùng phản hồi giả lập cho các bài kiểm tra lỗi và hết thời gian chờ có thể lặp lại. Chỉ chạy một phép thử thật, nhỏ và có chủ đích, sau khi những bài kiểm tra đó đã qua; ảnh tạo thật sẽ trừ vào số dư. Nếu kết quả của lần gửi chưa rõ, hãy điều tra trước khi gửi lại. Một ngoại lệ ở máy bạn không chứng minh rằng chẳng có tác vụ nào được nhận.

Câu hỏi thường gặp

Tôi có giữ được các prompt đang dùng không?

Có, như một điểm khởi đầu, miễn là chúng thỏa các ràng buộc của yêu cầu. Hãy giữ vài prompt tiêu biểu để so sánh, nhưng đừng mong các lần tạo lặp lại cho ra ảnh y hệt.

Tôi có cần thư viện client mới không?

Với các ví dụ ở đây thì không. Yêu cầu HTTP thông thường là đủ. Dù chọn client nào, nó cũng phải biết gửi tác vụ và hỏi trạng thái, thay vì chờ một tấm ảnh hoàn chỉnh ngay lập tức.

Tìm chi phí cuối cùng ở đâu?

Trong lịch sử sử dụng của tài khoản. Một tác vụ đã hoàn tất có thể kèm mức dùng token, nhưng phản hồi công khai của nó không có trường chi phí. Hướng dẫn về giá nói về phần ước tính.

Hoàn tất việc chuyển đổi ở ranh giới ứng dụng

Việc chuyển một API ảnh coi như xong khi ứng dụng xử lý trọn vòng đời của kết quả: tác vụ được nhận, trạng thái chờ, kết quả hoàn tất, tải về và lỗi. Hãy giữ thay đổi đầu tiên thật nhỏ, kiểm tra các tình huống gián đoạn, rồi chỉ chuyển những yêu cầu còn lại sau khi đã rà soát giả định đầu vào và đầu ra của chúng.

Chuyển tích hợp ảnh sang SeedRouter