# 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ý](https://open.wandura.ai/login) 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ủ:

```bash
export WANDURA_API_KEY=wdr_test_...
```

## 3. Chọn style
```bash
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](https://open.wandura.ai/styles) hiện cùng danh sách kèm bản xem trước.

## 4. Gửi job đầu tiên
```bash
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:

```ts
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);
```

```python
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](https://docs.wandura.ai/vi/developers/api-v2/jobs#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](https://docs.wandura.ai/vi/developers/api-v2/jobs#webhooks)). Hoặc poll:

```bash
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](https://docs.wandura.ai/vi/developers/api-v2/jobs#lane-and-inputs)).

## 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](https://docs.wandura.ai/vi/developers/api-v2/concepts#runs).

## Tiếp theo
- [Jobs API](https://docs.wandura.ai/vi/developers/api-v2/jobs): mọi trường, trạng thái, lỗi, webhook và giới hạn.
- [Khái niệm](https://docs.wandura.ai/vi/developers/api-v2/concepts): lane, run miễn phí, webhook, giới hạn, idempotency, end-user ID.
- [Danh sách style](https://docs.wandura.ai/vi/developers/api-v2/styles): mọi style kèm đầu vào và giá.
- [SDK](https://docs.wandura.ai/vi/developers/api-v2/sdks): 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`.