Trên trang này
Tóm tắt — Run là một lệnh gọi một style. Priority đúng hạn hoặc miễn phí; Relax rẻ hơn và phải chờ. Run không có kết quả thì miễn phí. Webhook có ký; lệnh gửi idempotent;
end_user_idbắt buộc.
Run
Một run là một lệnh gọi một style cho ra một kết quả. Bạn gửi, run ở queued, rồi running, rồi trạng thái cuối.
Priority: bắt đầu ở 2 s, nhân 1.5 mỗi lần, tối đa 10 s, cộng thêm 0–0.5 s ngẫu nhiên. Relax: 10 s đến 60 s. Trạng thái cuối: completed, failed, nsfw, canceled.
Run mang price và charge: held khi đang chạy, charged khi hoàn tất, released khi miễn phí, none với key test. Huỷ run đang xếp hàng bằng POST vào cancel_url; tiền giữ được trả lại.
Style và lane
Style là một kết quả làm sẵn (ví dụ kiểu chân dung hay một clip chuyển động). Bạn không chọn model: Wandura giữ các nhà cung cấp phía sau mỗi style và đổi được mà bạn không phải sửa code. Mỗi style có schema inputs tại /v2/public/styles/{style}/openapi.json.
Mỗi run chọn một lane:
- Priority: xong trong thời gian cam kết của style (xem danh sách style) nếu không run miễn phí.
- Relax: rẻ hơn, xếp hàng chờ, mỗi end user một run chạy cùng lúc.
POST /v2/quote nhận cùng body như run và trả giá và ETA mà không tính tiền.
Run miễn phí
Bạn không bao giờ trả tiền cho run không có kết quả. Run miễn phí kết thúc với free_run.reason:
free_run.reason |
Khi nào |
|---|---|
priority_late |
Priority did not finish within its promise. |
provider_error |
The run failed on our side. |
bad_input |
An input could not be used (for example a URL that is not http(s)). |
content_blocked |
The input or output was blocked by the content filter (status nsfw). |
Webhook
Đặt một URL webhook cho mỗi product trong console. Mỗi lần run đổi trạng thái được POST như một event, có ký:
Wandura-Signature: t=1791600000,v1=5f2b…v1 là HMAC-SHA256 dạng hex của t + "." + raw body với webhook secret của bạn. Kiểm trên raw body, từ chối t lệch quá 5 phút so với bây giờ, rồi trả 2xx nhanh. Non-2xx sẽ được gửi lại (30 s, 2 phút, 10 phút, 1 giờ, 6 giờ, 24 giờ). Có thể nhận lặp: khử trùng theo Wandura-Event-Id, và giữ sequence cao nhất cho mỗi run. SDK có sẵn hàm kiểm.
Loại event: run.running, run.completed, run.failed, run.nsfw, run.canceled. Link kết quả được giữ 72 giờ.
Giới hạn
| Giới hạn | Mặc định | Điều xảy ra |
|---|---|---|
| Run mỗi end user mỗi ngày | 20 | Vượt: 429 end_user_cap_reached kèm Retry-After (đặt lại 00:00 UTC). Tổ chức của bạn có thể đổi mức trần. |
| Run đồng thời mỗi product | 20 | Run thừa xếp hàng (queued) thay vì lỗi; Priority đi trước. |
| Run Relax đang chạy mỗi end user | 1 | Run Relax kế tiếp của end user đó chạy khi run trước kết thúc. |
| Cửa sổ chữ ký webhook | 300 s | Từ chối webhook có timestamp cũ hơn hoặc mới hơn mức này. |
Cần nhiều hơn? Cho chúng tôi biết khối lượng của bạn, chúng tôi nâng giới hạn của tổ chức.
Idempotency
Mỗi lệnh gửi (POST /v2/styles/{style} hoặc POST /v2/runs) phải có header Idempotency-Key, một chuỗi duy nhất tối đa 255 ký tự. Nếu mạng đứt và bạn thử lại với cùng key và body, bạn nhận lại run đầu tiên (200, header Idempotent-Replayed: true): không bao giờ chạy hay tính tiền hai lần. Cùng key mà body khác là 409 idempotency_key_reused. Dùng key mới cho mỗi run mới.
End-user ID
end_user_id bắt buộc trên mọi run: id của người trong app của bạn mà run này dành cho (chuỗi tự chọn, tối đa 255 ký tự; đừng gửi email hay tên). Trần theo ngày và quy tắc Relax tính theo end user, nên một người dùng nặng không ăn hết cả product. Dùng nó trong console để trả lời khiếu nại của người dùng.
Tải tệp lên
Không có chỗ lưu trữ riêng? POST /v2/uploads với {content_type, size_bytes} trả upload_url đã ký sẵn. PUT dữ liệu vào đó, rồi truyền file_url trong inputs. Tệp được giữ 24–48 giờ.
Test và live
Key test (wdr_test_…) trả kết quả mẫu với giá $0 và theo cùng quy tắc (idempotency, end-user ID, webhook), nên code bạn thử là code bạn chạy thật. Key live chạy thật.
Cập nhật 14/10/2026 · Lịch sử thay đổi (1)