Bắt đầu nhanh

Tóm tắt — Đăng ký, chép key test, rồi POST /v2/jobs kèm model và style. Nhận kết quả qua webhook có ký hoặc poll GET /v2/jobs/{job_id}.

Chạy style đầu tiên thành một job. Lệnh gọi đi từ máy chủ của bạn tới https://api.wandura.ai kèm API key.

1. Đăng ký#

Đăng ký bằng email. Bạn có tài khoản cá nhân, một product Test với key test, và một product My app để chạy thật.

2. Lấy key#

Key test (wdr_test_…) hiện một lần khi đăng ký. Key test trả kết quả mẫu với giá $0, nên bạn dựng xong cả tích hợp trước khi nạp tiền. Key live (wdr_live_…) chạy thật và trừ ví của product. Giữ key trên máy chủ:

export WANDURA_API_KEY=wdr_test_...

3. Chọn style#

curl "https://api.wandura.ai/v2/styles?model=wandura-video-v1" -H "Authorization: Bearer $WANDURA_API_KEY"

Mỗi style có id, model (wandura-image-v1 hoặc wandura-video-v1), các trường nó nhận (inputs, mỗi trường required hoặc optional), price và preview_url. Catalog style hiện cùng danh sách kèm bản xem trước.

4. Gửi job đầu tiên#

curl -X POST https://api.wandura.ai/v2/jobs \
  -H "Authorization: Bearer $WANDURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "wandura-video-v1", "style": "twenty-four", "image_urls": ["https://your-bucket.example.com/u/42/photo.jpg"], "end_user_id": "user_123"}'
# HTTP 202
# {"job_id":"run_QVqsXwr7VGSP","status":"queued","model":"wandura-video-v1","created_at":"2026-10-16T09:15:40.825Z"}

Cùng lệnh đó bằng JavaScript (Node 18+) hoặc Python, không cần cài gói nào của Wandura:

const res = await fetch('https://api.wandura.ai/v2/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WANDURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: 'wandura-video-v1',
    style: 'twenty-four',
    image_urls: ['https://your-bucket.example.com/u/42/photo.jpg'],
    end_user_id: 'user_123',
  }),
});
const job = await res.json();
console.log(job.job_id, job.status);

import os, uuid, requests

res = requests.post(
    "https://api.wandura.ai/v2/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['WANDURA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "wandura-video-v1",
        "style": "twenty-four",
        "image_urls": ["https://your-bucket.example.com/u/42/photo.jpg"],
        "end_user_id": "user_123",
    },
)
job = res.json()
print(job["job_id"], job["status"])

• Idempotency-Key không bắt buộc nhưng nên gửi: cùng key và cùng body thì không bao giờ thành job thứ hai. Không gửi thì cùng một body trong 10 phút là cùng một job.
• end_user_id không bắt buộc: gửi id người dùng trong app của bạn thì giới hạn theo ngày cho từng người sẽ giữ ví của bạn.
• Body sai bị từ chối ngay bằng 422 INVALID_INPUT, liệt kê mọi lỗi (xem Validation).
• Key test trả file mẫu với giá $0; key live chạy thật và chỉ tính tiền khi job succeeded.

5. Nhận kết quả#

Thêm "webhook_url": "https://your-backend.example.com/hooks/wandura" vào lệnh gửi, Wandura sẽ POST job cuối cùng (có ký) tới đó (xem Webhook). Hoặc poll:

curl https://api.wandura.ai/v2/jobs/run_QVqsXwr7VGSP -H "Authorization: Bearer $WANDURA_API_KEY"

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. Trạng thái: queued → processing → succeeded, failed, cancelled hoặc timeout (cuối). Job succeeded có output[0].url; job failed hoặc timeout có error kèm code và retryable.

Đang triển khai: "lane": "relax" (rẻ hơn hoặc cùng giá, không hạn chót) và "inputs": {…} cho đầu vào riêng của style như keep_audio (xem Lane Relax và đầu vào riêng của style).

Runs (cùng động cơ)#

Tích hợp đã dựng trên runs vẫn chạy: POST /v2/styles/{style} với {"lane", "end_user_id", "inputs"} và một Idempotency-Key trả về một run có status_url và cancel_url. Run mang cùng bộ chữ trạng thái với job ở trường state. Xem Khái niệm.

Tiếp theo#

• Jobs API: mọi trường, trạng thái, lỗi, webhook và giới hạn.
• Khái niệm: lane, run miễn phí, webhook, giới hạn, idempotency, end-user ID.
• Danh sách style: mọi style kèm đầu vào và giá.
• SDK: client JavaScript và Python chính thức, đang preview riêng (chưa có trên npm hay PyPI).
• Dựng bằng AI agent? Đưa cho nó https://api.wandura.ai/v2/openapi.json.