AHV AI Orchestrator

Dịch vụ API xử lý các tác vụ AI nặng — đổi mặt, nâng cấp ảnh, tạo ảnh/video, nhạc, giọng nói, thử đồ ảo… — theo cơ chế job bất đồng bộ: bạn gửi yêu cầu, nhận ngay job_id, rồi nhận kết quả qua webhook hoặc polling.

Kiến trúc (mức khái niệm)

• Bất đồng bộ: POST /v1/jobs trả về ngay; việc nặng chạy nền, bạn không phải giữ kết nối.
• Điều phối tự động: orchestrator xếp hàng đợi và chọn tài nguyên xử lý phù hợp trong cụm GPU. Phía khách không cần (và không thể) chọn máy xử lý.
• Ước tính thời gian: mỗi job trả về predict_time (giây) và eta_utc — chỉ là ước tính tham khảo, không phải cam kết.
• Kiểm duyệt nội dung: nội dung đầu vào có thể được hệ thống kiểm duyệt tự động; nội dung vi phạm bị từ chối (rejected).

Bắt đầu nhanh

Mọi API công khai nằm dưới https://ai.ahvchat.com. Ba bước để chạy job đầu tiên:

1. Tạo job

curl -X POST https://ai.ahvchat.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "task": "faceswap",
    "payload": {
      "target_url": "https://example.com/photo.jpg",
      "source_url": "https://example.com/face.jpg"
    },
    "webhook_url": "https://your-server.com/webhook"
  }'

Phản hồi:

{
  "job_id": "JOB_ID",
  "status": "queued",
  "predict_time": 10,
  "eta_utc": "2026-11-11T10:00:10Z"
}

2. Nhận kết quả

Có hai cách (dùng một hoặc cả hai): chờ webhook gửi tới webhook_url, hoặc hỏi trạng thái job bằng polling:

curl https://ai.ahvchat.com/v1/jobs/JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

3. Tải kết quả về

Khi status là succeeded, lấy result.url và tải tệp về lưu ở hệ thống của bạn — liên kết kết quả chỉ tồn tại tạm thời (xem Khuyến nghị tích hợp).

Xác thực

Các API tạo/đọc job và kiểm duyệt ảnh yêu cầu header:

X-API-Key: YOUR_API_KEY

• Khoá API do AHV cấp. Cần khoá API hoặc hỗ trợ tích hợp? Xem mục Liên hệ ở trang chủ.
• Decide API dùng một khoá riêng (xem Decide API).
• Thiếu hoặc sai khoá ⇒ HTTP 401.
• Chỉ dùng khoá ở máy chủ của bạn. Không nhúng khoá vào app di động, trang web hay mã nguồn công khai. Nếu nghi ngờ khoá bị lộ, hãy liên hệ AHV để thu hồi và cấp khoá mới.

Trong tài liệu này, YOUR_API_KEY chỉ là chỗ giữ chỗ — hãy thay bằng khoá của bạn.

Vòng đời job & trạng thái

Luồng xử lý

1. Client gửi POST /v1/jobs với task, payload và (tuỳ chọn) webhook_url.
2. Job được ghi nhận ở trạng thái queued; phản hồi có job_id, predict_time, eta_utc.
3. Webhook giai đoạn 1: sự kiện job.queued.
4. Hệ thống nhận job từ hàng đợi và giao cho tài nguyên xử lý phù hợp; webhook giai đoạn 2: job.started.
5. Xử lý xong, hệ thống lưu kết quả; webhook giai đoạn 3: job.finished kèm result hoặc error.

API: Tạo & theo dõi job

POST /v1/jobs — Tạo job

Ví dụ gọi: xem Bắt đầu nhanh. Phản hồi thành công gồm job_id, status (queued), predict_time, eta_utc.

GET /v1/jobs/{job_id} — Xem trạng thái

Khi thành công

{
  "job_id": "JOB_ID",
  "task": "faceswap",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "url": "https://...",
    "filename": "result.jpg",
    "meta": {"width": 1080, "height": 1920}
  },
  "duration_sec": 3.5
}

Khi lỗi

{
  "job_id": "JOB_ID",
  "status": "failed",
  "error": {"code": 502, "message": "Processing timeout"}
}

result.meta chứa thông tin bổ sung tuỳ task (kích thước, thời lượng…). Chỉ nên dựa vào các trường đã được mô tả trong API Docs; các trường khác có thể thay đổi.

Chi tiết payload từng task: xem API Docs, mục 1.

API: Upload & kiểm duyệt ảnh

POST /upload — Upload tệp

Dùng khi ảnh/âm thanh của bạn chưa có URL công khai (hoặc nguồn chặn tải trực tiếp). Gửi tệp bằng multipart/form-data, nhận lại URL để dùng làm đầu vào cho job.

curl -X POST https://ai.ahvchat.com/upload -F "file=@photo.jpg"

{"url": "https://...", "filename": "..."}

Tệp upload chỉ lưu tạm; hãy tạo job ngay sau khi upload.

POST /v1/nsfw-check — Kiểm duyệt ảnh

Kiểm tra nhanh một ảnh có nội dung 18+ hay không. Gửi image_url (hoặc tệp ảnh) kèm mức strict:

Kết quả gồm cờ is_nsfw và nhãn (safe/nsfw). Cần header X-API-Key. Định dạng chi tiết: xem API Docs.

Webhook

Nếu job có webhook_url, hệ thống gửi POST JSON tới URL đó ở 3 thời điểm:

Payload khi thành công

{
  "event": "job.finished",
  "event_id": "...",
  "job_id": "JOB_ID",
  "task": "faceswap",
  "status": "succeeded",
  "ok": true,
  "progress": 100,
  "duration": 3.5,
  "predict_time": 10,
  "result": {
    "ok": true,
    "status": "succeeded",
    "url": "https://...",
    "filename": "result.jpg",
    "meta": {"width": 1080, "height": 1920}
  },
  "error": null
}

Payload khi lỗi / bị từ chối

{
  "event": "job.finished",
  "job_id": "JOB_ID",
  "status": "failed",
  "ok": false,
  "error": {"code": 502, "message": "Processing timeout"}
}

{
  "event": "job.finished",
  "job_id": "JOB_ID",
  "status": "rejected",
  "ok": false,
  "error": {"code": "NSFW_BLOCKED", "message": "Content violates policy"}
}

Phía máy chủ của bạn nên

• Trả HTTP 2xx nhanh (xử lý nặng thì đưa vào hàng đợi của bạn). Nếu không nhận được 2xx, sự kiện có thể được gửi lại.
• Chống trùng: cùng một sự kiện có thể được gửi nhiều hơn một lần. Dùng job_id + event (hoặc event_id) để bỏ qua bản trùng.
• Đối chiếu trước khi hành động quan trọng (cộng tiền, giao hàng…): gọi GET /v1/jobs/{job_id} để xác nhận trạng thái thật thay vì chỉ tin nội dung request.
• Giữ kín webhook_url (dùng HTTPS, đừng ghi vào log công khai) và chỉ nhận phương thức POST. URL không phải cơ chế xác thực — hãy dựa vào bước đối chiếu ở trên.
• Luôn có phương án dự phòng: nếu không nhận được webhook, dùng polling theo job_id.

API: Decide (quyết định có kiểu)

Gửi một nội dung (state) kèm vài câu hỏi có kiểu → nhận đáp án có cấu trúc kèm xác suất. API đồng bộ (trả kết quả ngay trong response, không tạo job) và tương thích với các client Decide chuẩn: chỉ cần đổi base_url (chi tiết tương thích xem API Docs).

• Base URL cho client tương thích: https://ai.ahvchat.com/decide
• Xác thực: header Authorization: Bearer YOUR_API_KEY hoặc X-API-Key: YOUR_API_KEY. Đây là khoá riêng của Decide API, không phải khoá dùng cho /v1/jobs.
• 3 kiểu câu hỏi: noul (có/không → xác suất), choice (chọn 1 nhãn trong 2–255 nhãn), score (thang 2–10 mức). Các trường mở rộng của AHV (ví dụ warnings): xem API Docs.
• Mã lỗi: 401 sai/thiếu khoá, 429 gọi quá nhanh, 503 dịch vụ tạm thời không khả dụng (thử lại sau).

curl -s https://ai.ahvchat.com/decide/v1/systemone \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"jev-latest","state":"Mình đã thanh toán nhưng chưa thấy đơn hàng được xác nhận!",
       "questions":{"gap":{"type":"score","instructions":"Mức gấp?",
                           "criteria":["không gấp","sớm","khẩn cấp"]}}}'

Tài liệu đầy đủ: API Docs, mục 10; thử trực tiếp ở tab Decide trên API Demo.

Danh sách tính năng (task)

Giá trị task gửi trong POST /v1/jobs. Cột “Chi tiết” dẫn tới mục tương ứng trong API Docs.

Ngoài job bất đồng bộ, API Docs còn mô tả các API đồng bộ: Chat LLM (mục 7) và Giọng nói (mục 8), cùng Decide API ở trên.

Faceswap & Upscale

Tham số tuỳ chọn

Tạo ảnh

Payload (ahv_image)

Tham số nâng cao của từng engine: xem API Docs. Chỉ gửi các tham số có trong tài liệu.

Tạo video

Payload

Việc tạo video mất nhiều thời gian hơn ảnh — hãy dùng webhook hoặc polling thưa (mỗi vài chục giây).

Talking video (lip sync)

Gửi một ảnh chân dung kèm nguồn giọng nói → nhận video người trong ảnh nói đúng lời, khớp môi. Dùng chung task: "talking_video"; ba luồng khác nhau ở nguồn giọng:

Tham số

Thời gian xử lý

Thời gian tỉ lệ thuận với độ dài video — từ vài phút đến vài chục phút. Hãy dùng webhook job.finished; nếu polling thì thưa (30–60 giây/lần). Video kết quả được đánh dấu là nội dung do AI tạo. Khi hệ thống đang bận có thể trả TV_BUSY; xem Mã lỗi. Chi tiết đầy đủ: API Docs, mục 9.

Nhạc: music_gen / music_cover

music_cover — bốn kịch bản

• Sai tổ hợp tham số (ví dụ mode: "voice" thiếu voice_ref_url, hoặc thiếu prompt ở remix/vocal) ⇒ lỗi 400 ngay, không cần thử lại.
• Đây là các task dài: dùng webhook hoặc polling thưa. Thời gian xử lý có thể dao động tuỳ độ dài và tình trạng hệ thống.
• Kết quả là liên kết HTTPS tới tệp âm thanh; liên kết chỉ tồn tại tạm thời — hãy tải về sớm.

Chi tiết payload: API Docs mục 5 (music_gen) và mục 6 (music_cover).

Virtual Try-On

Payload

Công cụ ảnh

Xoá nhiều vật thể trong một lượt

remove_object nhận mask_urls (tối đa 10 mask) để xoá nhiều vị trí một lần. Kết hợp với scan_objects (trả về nhãn, ảnh biểu tượng và mask của từng vật) để làm luồng “bấm chọn vật cần xoá”:

1. Gọi scan_objects với ảnh gốc → nhận danh sách vật thể kèm mask_url.
2. Người dùng chọn các vật muốn xoá.
3. Gọi remove_object với mask_urls là các mask đã chọn.

Mask chỉ tồn tại tạm thời; hãy dùng ngay sau khi quét. Chi tiết: scan_objects, remove_object, remove_background.

Mã lỗi & cách xử lý

Khi gọi API (HTTP status)

Khi job kết thúc không thành công

Job ở trạng thái failed hoặc rejected có đối tượng error dạng {"code": ..., "message": "..."}.

Mã lỗi theo tính năng

Chiến lược thử lại

• Chỉ thử lại lỗi tạm thời: 429, 5xx, và job failed với code: 502.
• Không thử lại lỗi do dữ liệu (400, 422, NSFW_BLOCKED, lỗi tải ảnh) trước khi sửa dữ liệu.
• Backoff luỹ thừa có jitter: chờ khoảng 2 → 4 → 8 → 16 giây (cộng ngẫu nhiên nhỏ), tối đa vài lần rồi dừng và báo lỗi cho người dùng.
• Khi tạo lại job sau lỗi, hãy dùng job_id mới và ghi nhớ job_id cũ để đối soát.

Ví dụ: chờ kết quả bằng polling

import time
import requests

API = "https://ai.ahvchat.com"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
RETRY_HTTP = (429, 500, 502, 503, 504)

def wait_for_job(job_id, interval=3, timeout=3600):
    # timeout: đặt theo loại task (video, nhạc, talking_video cần lâu hơn ảnh)
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API}/v1/jobs/{job_id}", headers=HEADERS, timeout=15)
        if r.status_code not in RETRY_HTTP:
            r.raise_for_status()
            job = r.json()
            if job["status"] in ("succeeded", "failed", "rejected"):
                return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)   # thưa dần, tối đa 30 giây
    raise TimeoutError(job_id)

Giới hạn đầu vào

Các giới hạn dưới đây áp dụng cho từng tính năng; giới hạn chi tiết khác xem trong API Docs.

Khuyến nghị tích hợp

1. Ưu tiên webhook thay cho polling dày; nếu polling, bắt đầu sau vài giây và giãn dần (task nhanh: 2–3 giây/lần; video, nhạc, talking video: 30–60 giây/lần).
2. Lưu job_id ngay khi tạo job; dùng nó để đối soát và khi cần hỗ trợ.
3. Xử lý webhook idempotent: cùng sự kiện có thể đến nhiều lần.
4. Tải kết quả về và lưu riêng. Liên kết kết quả, mask và tệp upload chỉ tồn tại tạm thời; đừng dùng chúng làm kho lưu trữ lâu dài.
5. Kiểm tra đầu vào trước khi gọi: URL còn sống và tải được, định dạng và kích thước hợp lệ, ảnh có nội dung phù hợp. Phần lớn lỗi job là do dữ liệu đầu vào.
6. Phân loại lỗi: thử lại lỗi tạm thời có backoff; báo người dùng và sửa dữ liệu với lỗi 4xx / rejected.
7. Hiển thị tiến độ cho người dùng bằng progress, predict_time và eta_utc.
8. Bảo vệ khoá API: chỉ gọi từ máy chủ của bạn, không đưa vào mã nguồn công khai hay ứng dụng phía người dùng.

Tài liệu & liên hệ