> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions. # Vector hóa ảnh hàng loạt qua API với hàng đợi nối lại > Vector hóa ảnh hàng loạt bằng API với hàng đợi lưu bền vững. Lưu ID chuyển đổi, xử lý tệp lỗi và tiếp tục mà không gửi lại phần đã xong. Source: https://perfectvector.com/vi/blog/batch-vectorize-images-api Language: vi Author: Jay Published: 2026-11-10T08:00:00+09:00 Để vector hóa ảnh hàng loạt qua API, đưa mỗi tệp nguồn vào hàng đợi và lưu tiến độ trước khi sang tệp tiếp theo. Với PerfectVector API v1, chương trình xử lý của bạn quản lý đợt chạy. API nhận một ảnh mỗi yêu cầu và mặc định cho mỗi tài khoản thực hiện một lượt chuyển đổi thực tế tại một thời điểm. [Giới hạn PerfectVector API](https://perfectvector.com/docs/api/limits) ## Tạo một bản ghi hàng đợi cho mỗi ảnh Bắt đầu với bản sao cố định của từng ảnh nguồn và một thư mục riêng cho đầu ra. Ví dụ giả định một chương trình xử lý, cơ sở dữ liệu SQLite cục bộ và thư mục chứa PNG, JPEG hoặc WebP một khung hình. Kiểm tra [giới hạn tệp của API](https://perfectvector.com/docs/api/limits) trước khi thêm tệp. Dùng đường dẫn đầu ra riêng để hai tệp nguồn cùng tên `logo.png` không ghi đè lên nhau. Lưu cùng lúc các trường sau trước khi thử tải lên lần đầu. | Trường | Dữ liệu cần lưu | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | | Nguồn | Đường dẫn cố định hoặc phiên bản đối tượng và giá trị băm của dữ liệu gốc. | | Khóa yêu cầu | Khóa chống gửi trùng (idempotency key) dùng để nhận biết các lượt gửi lại cùng thao tác. Ghi thời điểm thử POST đầu tiên. | | ID chuyển đổi | ID dạng `vec_…` của API. Lưu ngay khi nhận. | | Đầu ra | Đích cục bộ riêng và trạng thái hàng đợi mới nhất đã xác nhận. | | Chi tiết lỗi | Mã lỗi API, ID yêu cầu hoặc lỗi chuyển đổi nếu có. | Ghi và xác nhận bản ghi trong cơ sở dữ liệu trước khi gửi POST. Nếu API nhận tệp nhưng kết nối ngắt trước khi bạn nhận ID, bạn vẫn có khóa để dùng lại. PerfectVector nhận diện khóa đó trong vòng 24 giờ kể từ yêu cầu đầu tiên trong cùng tài khoản và chế độ. Khi gửi lại, giữ nguyên dữ liệu ảnh và tùy chọn. [Chống gửi trùng trong PerfectVector](https://perfectvector.com/docs/api/idempotency) **Minh họa quy trình** ![Một chồng ảnh raster có nhãn dẫn đến bản ghi chuyển đổi đã lưu rồi đến SVG. Mũi tên khởi động lại trỏ về bản ghi đã lưu.](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp) *Lưu ID chuyển đổi trước khi tải xuống. Sau khi bị gián đoạn, tiếp tục từ ID đó.* ## Gửi, kiểm tra trạng thái và lưu từng tác vụ Gửi POST multipart đến `/v1/vectorizations`, đưa ảnh vào trường `image` và khóa của dòng vào phần đầu `Idempotency-Key`. Dùng `Prefer: respond-async` để yêu cầu gửi hoàn tất nhanh. Lưu ID từ phản hồi thành công trước khi kiểm tra trạng thái. Phản hồi `202` nghĩa là đang chờ xử lý. Phản hồi `201` có thể mô tả cả chuyển đổi thành công lẫn thất bại, nên hãy đọc trạng thái trong JSON. [Chờ và xử lý bất đồng bộ trong PerfectVector](https://perfectvector.com/docs/api/waiting-and-async) Bảng sau nêu thứ tự quyết định của chương trình xử lý. Trạng thái hàng đợi như `saved` là nhãn do bạn đặt. API trả trạng thái như `processing` và `succeeded`. | Bản ghi hàng đợi trên đĩa | Việc cần làm tiếp | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mới và đã lưu khóa | Tải dữ liệu gốc lên và ghi ID chuyển đổi trả về. | | Chưa rõ đã gửi thành công, chưa biết ID | Gửi lại đúng tệp với khóa đã lưu trong khoảng cho phép. Nếu đã quá hạn, đánh dấu dòng để kiểm tra trước khi bắt đầu một lần chuyển đổi mới có thể mất lượt. | | Đã lưu ID chuyển đổi | Kiểm tra trạng thái ID hiện có. Chờ khoảng hai giây giữa các lần kiểm tra và tuân theo thời gian chờ của giới hạn tần suất. | | Chuyển đổi thành công nhưng thiếu tệp | Tải kết quả, kiểm tra `image/svg+xml`, ghi vào tệp tạm rồi đổi tên thành đích chính thức. Sau đó đánh dấu đã lưu. | | Đã lưu | Bỏ qua POST. Nếu tệp bị mất, thử lấy kết quả hiện có khi liên kết còn dùng được. | | Bị từ chối hoặc thất bại | Ghi lỗi HTTP hoặc lỗi chuyển đổi cuối cùng. Sửa đầu vào trước khi thử như một thao tác mới. | Nếu POST trả `429` hoặc `503`, làm theo `Retry-After` và dùng lại đúng ảnh, tùy chọn, khóa trong vòng 24 giờ. Nếu mã là `too_many_in_flight`, chờ lần chuyển đổi thực tế đang chạy kết thúc. Khi đã có ID, kiểm tra ID trước khi gửi lại. Nếu đã xác nhận trạng thái cuối là `failed` với `timeout` hoặc `provider_unavailable`, hãy dùng khóa mới nếu muốn thử lại. Nếu nhà cung cấp tạm ngừng, chờ dịch vụ khôi phục. Máy khách hết thời gian chờ thì kết quả ban đầu chưa rõ, vì vậy hãy dùng ID hoặc gửi lại với khóa cũ trong khoảng cho phép. [Lỗi PerfectVector API](https://perfectvector.com/docs/api/errors) Khi khởi động lại, chương trình có thể kiểm tra trạng thái hoặc tải kết quả lần nữa mà không bắt đầu lần chuyển đổi mới. Tải và lưu từng SVG thành công trước khi sang mục tiếp theo. Kết quả API hết hạn sau 24 giờ kể từ khi chuyển đổi hoàn tất. [Kết quả và tải xuống PerfectVector](https://perfectvector.com/docs/api/results) Dùng mã giả dưới đây để triển khai với cơ sở dữ liệu và máy khách HTTP của bạn. Phép thử bên dưới giả định chương trình ghi nhật ký mỗi yêu cầu và có điểm tạm dừng dành riêng cho thử nghiệm ngay sau khi xác nhận lưu ID chuyển đổi thứ hai. ```text for each queue row in a stable order: if the row is rejected or its saved SVG is still on disk: continue if the row has no conversion ID: verify source bytes match the stored digest if an earlier POST is uncertain and the replay window expired: flag the row for review and continue POST with the stored key and original bytes and options if the response is a permanent input rejection: commit the error and continue if the POST times out or the service requests a retry: keep the same key, record the retry time and stop this run commit the returned conversion ID pause here when testing recovery after a commit GET status by conversion ID, waiting between pending responses if conversion failed: commit its error and continue download the existing result and check the SVG media type write to a temporary file and rename it to the output path commit the saved state ``` ## Thử khởi động lại với ba tệp Dùng hai logo PNG nhỏ và một PNG bị hỏng. Cố tình giữ tệp hỏng trong bộ thử để xem hàng đợi có đi tiếp sau khi một tệp bị từ chối không. Với khóa thử nghiệm, hai tệp hợp lệ phải trả SVG mẫu. Tệp tải lên bị hỏng phải trượt bước kiểm tra và không sinh tệp trong thư mục đầu ra. Chế độ thử nghiệm trả cùng một SVG mẫu cho cả hai tệp hợp lệ. [Chế độ thử nghiệm PerfectVector](https://perfectvector.com/docs/api/test-mode) 1. Để tệp đầu tiên đạt `saved`. Tạm dừng chương trình sau khi ghi ID của tệp hợp lệ thứ hai, trước khi lưu kết quả. 2. Khởi động lại. Xác nhận chương trình bỏ qua tệp đầu và tải tệp thứ hai bằng ID đã có. 3. Xác nhận tệp hỏng xuất hiện trong báo cáo lỗi kèm mã và không có SVG được ghi cho tệp đó. 4. Chạy lại lần nữa. Kiểm tra cả hai tệp đã lưu vẫn còn và không có lượt tải lên thành công nào bị gửi lại. Chúng tôi thử khởi động lại với API bằng khóa thử nghiệm. Chương trình lưu hai SVG mẫu, ghi một đầu vào hỏng là bị từ chối và tiếp tục tệp thành công thứ hai bằng ID hiện có. Lượt chạy cuối không gửi yêu cầu nào. Chế độ thử nghiệm hoàn tất ngay, nên dùng phản hồi giả lập để kiểm tra nhánh chờ. ## Câu hỏi thường gặp ### Có thể gửi mọi tệp trong một lần gọi API không? PerfectVector API v1 nhận một ảnh mỗi POST. Gửi một đợt dưới dạng nhiều yêu cầu riêng. Với chế độ thực, giữ đúng giới hạn tác vụ đồng thời của tài khoản và đợi lần chuyển đổi hiện tại xong trước khi gửi lần tiếp theo. [Giới hạn PerfectVector API](https://perfectvector.com/docs/api/limits) ### Nếu SVG đã hết hạn thì sao? Nếu đã tải về, dùng bản SVG lưu trước đó. Nếu chưa, kiểm tra trạng thái rồi quyết định có bắt đầu lần chuyển đổi mới không. Một lần chuyển đổi thực tế mới có thể mất thêm một lượt nếu thành công. [Kết quả và tải xuống PerfectVector](https://perfectvector.com/docs/api/results) ## Nguồn tham khảo 1. [PerfectVector — Giới hạn](https://perfectvector.com/docs/api/limits) — Kiểm tra tệp và số tác vụ đồng thời mặc định trên tài khoản. 2. [PerfectVector — Chống gửi trùng](https://perfectvector.com/docs/api/idempotency) — Phạm vi khóa, khoảng cho phép gửi lại và yêu cầu giữ nguyên đầu vào. 3. [PerfectVector — Chờ và xử lý bất đồng bộ](https://perfectvector.com/docs/api/waiting-and-async) — Gửi bất đồng bộ và kiểm tra trạng thái. 4. [PerfectVector — Kết quả](https://perfectvector.com/docs/api/results) — Tải xuống, lỗi và thời hạn kết quả. 5. [PerfectVector — Chế độ thử nghiệm](https://perfectvector.com/docs/api/test-mode) — Kiểm tra tệp tải lên và những kết quả có thể xác minh bằng khóa thử nghiệm. 6. [PerfectVector — Lỗi](https://perfectvector.com/docs/api/errors) — Khoảng chờ Retry-After, lỗi cuối cùng và khi nào cần khóa mới. *** [Lấy khóa thử nghiệm từ trang PerfectVector API](https://perfectvector.com/vi/api) rồi chạy thử với ba tệp của bạn. Kiểm tra mỗi dòng thành công có SVG trên đĩa và khi khởi động lại không dòng đã hoàn tất nào bị gửi lại. ## Explore - [Read the HTML article](https://perfectvector.com/vi/blog/batch-vectorize-images-api) - [Chuyển đổi hàng loạt PNG2SVG: Kiểm tra ZIP tải về](https://perfectvector.com/vi/blog/png2svg-batch-convert.md) - [Chuyển cả thư mục ảnh sang SVG bằng Claude Code](https://perfectvector.com/vi/blog/batch-vectorize-images-claude-code-mcp.md) - [Product facts](https://perfectvector.com/product-facts.md) - [FAQ](https://perfectvector.com/faq.md) - [Pricing and credits](https://perfectvector.com/pricing.md)