Hướng dẫn
Giới hạn tần suất và hạn ngạch
Giới hạn đồng thời, giới hạn tốc độ, hạn mức và dung lượng tài khoản, cùng cách thử lại có giãn cách
Giới hạn tần suất và hạn ngạch
Các giới hạn của nền tảng chia thành nhiều loại, biểu hiện khi kích hoạt cũng khác nhau. Phân biệt rõ là loại nào thì mới xử lý nhanh được.
| Loại giới hạn | Biểu hiện khi kích hoạt | Cách xử lý |
|---|---|---|
| Tần suất yêu cầu (giới hạn tần suất) | HTTP 429「Yêu cầu quá thường xuyên」 | Thử lại sau khi giãn cách, không thử lại đồng thời |
| Đồng thời tác vụ bất đồng bộ | HTTP 429, task_concurrency_exceeded | Chờ tác vụ hiện có hoàn thành rồi mới gửi |
| Hạn mức Key | Thông báo thiếu số dư/hạn mức, tác vụ sẽ không được tạo | Nạp tiền, điều chỉnh hạn mức Key hoặc thu nhỏ yêu cầu |
| Số dư tài khoản | Thông báo số dư không đủ bù đắp mức tiêu thụ ước tính lần này | Nạp tiền vào ví |
| Dung lượng tư liệu | Kiểm tra định dạng và kích thước khi gửi tư liệu | Sửa tệp hoặc chuyển sang image_url |
Giới hạn tần suất yêu cầu
Nền tảng có giới hạn tần suất yêu cầu. Thăm dò quá nhanh, đồng thời quá cao hoặc thử lại ồ ạt trong thời gian ngắn đều có thể kích hoạt:
{ "error": { "code": "...", "message": "请求过于频繁" } }Trạng thái HTTP là 429.
Cách làm đúng:
- Sau khi nhận
429, hãy giãn cách: chờ một khoảng thời gian rồi mới gửi yêu cầu tiếp theo, không gửi lại ngay lập tức; - Không dùng yêu cầu đồng thời để vượt qua giới hạn tần suất, điều này chỉ khiến thời gian giãn cách dài hơn;
- Khi thăm dò tác vụ bất đồng bộ, dùng khoảng cách cố định và hợp lý (ví dụ vài giây một lần), không thăm dò không có khoảng nghỉ.
Không thử lại một cách mù quáng với các mã trạng thái ngoài 429:
| Mã trạng thái | Xử lý |
|---|---|
429 | Giãn cách theo hướng dẫn rồi thử lại |
5xx tạm thời | Lưu RequestId, giãn cách rồi thử lại một lần |
400 | Vấn đề tham số, sửa yêu cầu rồi gửi lại |
401 | Key không hợp lệ hoặc đã bị vô hiệu hóa, kiểm tra khóa |
403 | Không có quyền truy cập tài nguyên hoặc mô hình đó |
404 | Tài nguyên không tồn tại, đối chiếu ID |
Đồng thời tác vụ bất đồng bộ
Các tác vụ bất đồng bộ như video chịu ràng buộc giới hạn đồng thời, chia theo chiều tài khoản và chiều toàn nền tảng. Khi đạt giới hạn sẽ trả về HTTP 429,
mã lỗi là task_concurrency_exceeded, trong thông báo sẽ nêu「hiện tại N / giới hạn M」.
Khi gặp phải nên:
- Giữ lại ID của tác vụ hiện có, không được bỏ đi;
- Chờ các tác vụ đang chạy chuyển sang trạng thái cuối (hoặc trực tiếp truy vấn trạng thái hiện tại của chúng);
- Chờ sau đó để người dùng chủ động gửi lại, không thử lại liên tục;
- Không gửi lặp lại cùng một tác vụ để "giành" đồng thời — điều đó sẽ tạo tác vụ trùng lặp và chi phí trùng lặp.
Trước khi gửi hàng loạt, nên quản lý theo hàng đợi ở backend nghiệp vụ: kiểm soát số lượng tác vụ đang chạy, thay vì gửi tất cả cùng một lúc.
Hạn mức Key và số dư tài khoản
Hạn mức và số dư là hai lớp giới hạn:
| Cấp độ | Mô tả |
|---|---|
| Hạn mức Key | Giới hạn mức sử dụng và thời hạn hiệu lực được đặt cho Key đó trong「Khóa API」của bảng điều khiển |
| Số dư tài khoản | Số dư khả dụng, hạn mức gói dịch vụ hoặc điểm của toàn bộ tài khoản LocoPal |
Tác vụ bất đồng bộ sẽ kiểm tra số dư có đủ bù đắp mức tiêu thụ ước tính lần này hay không trước khi gửi. Nếu không đủ sẽ trả về thông báo dễ đọc, và không tạo tác vụ, do đó trường hợp này không phát sinh chi phí.
Cách xử lý:
- Hạn mức Key không đủ → điều chỉnh hạn mức hoặc thời hạn hiệu lực của Key đó trong「Khóa API」;
- Số dư tài khoản không đủ → nạp tiền vào「Ví」hoặc dùng gói dịch vụ;
- Mức tiêu thụ ước tính quá lớn → giảm độ phân giải, thời lượng hoặc chuyển sang mô hình nhỏ hơn.
Nên kiểm tra trước số dư ở backend nghiệp vụ và đưa ra thông báo rõ ràng cho người dùng cuối, thay vì ném thẳng lỗi của nền tảng cho người dùng.
Giới hạn tư liệu
Giao diện tư liệu có kiểm tra dữ liệu tải lên:
| Giới hạn | Biểu hiện | Xử lý |
|---|---|---|
| Định dạng địa chỉ | image_url 必须是可公开下载的 http(s) 地址… | Chuyển sang địa chỉ http(s) có thể tải trực tiếp từ internet công cộng |
| Mỗi lần chỉ gửi một loại | image_url 与 data_url 只能提交一个 | Chỉ giữ lại một trường |
| Kích thước dữ liệu | 图片数据无效或超过 20MB | Nén ảnh hoặc chuyển sang image_url |
| Loại nhóm | 素材分组不存在或不是虚拟素材分组 | Hình ảnh chỉ có thể gửi vào nhóm virtual |
| Độ dài tên | Tên nhóm không được để trống, không quá 64 ký tự; mô tả không quá 300 ký tự | Sửa tên hoặc mô tả |
Tư liệu chưa hoàn tất kiểm duyệt không phải là lỗi: truy vấn trả về 200 và status là Processing, chỉ cần tiếp tục thăm dò bằng cùng ID tư liệu,
không gửi lặp lại.
Gợi ý thăm dò
Việc truy vấn tác vụ bất đồng bộ không phát sinh chi phí, nhưng thăm dò quá dày sẽ kích hoạt giới hạn tần suất.
| Giai đoạn tác vụ | Khoảng cách đề xuất |
|---|---|
| Vừa gửi (đang xếp hàng) | Vài giây một lần |
| Đang tạo | Vài giây đến hơn mười giây một lần |
| Đã vào trạng thái cuối | Dừng thăm dò |
Việc thăm dò nên có giới hạn tổng thời gian. Sau khi đạt giới hạn, dừng truy vấn và trả ID tác vụ cho người dùng, để người dùng có thể dùng ID tiếp tục truy vấn sau — không tạo lại tác vụ.
Tính idempotent và gửi lặp lại
Nền tảng không tự động gộp các yêu cầu giống nhau. Kể cả khi câu lệnh, tham số và tư liệu tham chiếu hoàn toàn giống nhau, mỗi lần chủ động gửi đều tạo tác vụ mới và kết quả mới, và mỗi bên tự tính phí.
Do đó:
- Dùng khóa idempotent phía nghiệp vụ (số đơn hàng, ID nghiệp vụ) để ngăn người dùng nhấn lặp gây gửi trùng;
- Sau khi gửi tác vụ bất đồng bộ, lưu ngay ID tác vụ vào cơ sở dữ liệu; khi mạng gián đoạn, dùng truy vấn thay vì tạo lại để khôi phục;
- Chỉ khi nhấn「Thử lại trực tiếp」trên cùng một kết quả thất bại thì mới thực thi lại tại chỗ — việc này cũng tạo tác vụ mới và chi phí mới.