Khái niệm

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 xếp hàng chờ, không hạn chót, giá không bao giờ cao hơn Priority. Run không có kết quả thì miễn phí. Webhook có ký; lệnh gửi idempotent; end_user_id bắt buộc.

Các khái niệm này đúng cho cả hai cửa. Tích hợp mới bắt đầu bằng Jobs API, dùng chữ của job (processing, succeeded, cancelled, timeout); trang này mô tả cả runs, vẫn được hỗ trợ.

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.

Chấm điểm kết quả#

Đang triển khai, không bắt buộc. Báo cho Wandura biết kết quả tốt hay không:

curl -X POST https://api.wandura.ai/v2/runs/run_Qk2m9XaB7Lc4/feedback \
  -H "Authorization: Bearer $WANDURA_KEY" -H "Content-Type: application/json" \
  -d '{"rating": "down", "reason": "Face does not match"}'

• rating: up hoặc down. reason: không bắt buộc, tối đa 280 ký tự.
• Id là id của run hoặc job_id của job, tạo bằng key cùng product.
• Mỗi run, mỗi API key một lần chấm. Gọi lại thì thay lần trước.
• Câu trả lời là lần chấm đã lưu: object run_feedback, run, rating, reason, created_at, updated_at.
• Lỗi: 400 invalid_request (rating hoặc reason sai), 404 run_not_found.

Wandura đọc các lần chấm để làm style tốt hơn. Chúng không hiện công khai và không có gì khác phụ thuộc vào chúng. Trong console, trang Runs và Playground có cùng nút thích / không thích.

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: xếp hàng chờ, không hạn chót, mỗi end user một run chạy cùng lúc; giá không bao giờ cao hơn Priority.

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:

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ờ.

Product của bạn cũng có thể đăng ký event nghẽn, queue.congestion_started và queue.congestion_ended: xem Hàng chờ và nghẽn.

Giới hạn#

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.

Run đồng thời theo mức nạp#

Đang triển khai: bậc theo mức nạp đã xây xong nhưng chưa bật. Trước khi bật, mọi tài khoản dùng mức mặc định ở trên.

Khi bật, product đang ở mức mặc định được chạy nhiều run cùng lúc hơn khi tổ chức của bạn nạp tiền bằng thẻ. Phần được tính là các lần nạp thẻ đã vào ví trong 28 ngày gần nhất, trừ phần đã hoàn. Giới hạn chỉ tăng: không bậc nào thấp hơn mức mặc định, và giới hạn chúng tôi đặt riêng cho product của bạn theo thoả thuận giữ nguyên. Bảng bậc hiện tại ở open.wandura.ai/pricing. Bậc của bạn, số đã nạp và mức cần cho bậc kế tiếp hiện ở GET /v2/queue (trường spend_tier) và trang Limits của console.

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ờ.

Khoá API#

Đang triển khai: quyền, style được phép và tag dưới đây lên api.wandura.ai và console ở bản phát hành tới.

Mỗi key thuộc một product. Khi tạo key trong console ở mục Keys, bạn có thể thu hẹp nó cho một app hoặc một người:

Nếu org của bạn chỉ chạy được một số style, style được phép của key vẫn nằm trong tập đó. Key tạo không kèm các thiết lập này chạy như mọi key xưa nay và không bao giờ nhận 403. Rotate (xoay) key giữ nguyên thiết lập; muốn đổi thì tạo key mới rồi thu hồi key cũ. Đối tượng key và webhook key.expiring / key.revoked chỉ có preset (run_styles hoặc read_only), allowed_styles và tags trên key có đặt chúng.

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.