AHV Orchestrator — Developer API Docs

System Overview

Hệ thống AI Orchestrator cung cấp API để xử lý các tác vụ AI nặng (FaceSwap, Video Gen, Upscale, Editing) thông qua cơ chế Async Queue.

Hỗ trợ: Faceswap (Single/Multi) Faceswap Video AHV Image/Video GG Image CX Image Upscale & Beauty Remove Obj Scan Obj

Open Dashboard →

Recommended Workflow

1. Client gửi POST /v1/jobs kèm webhook_url.
2. Server trả về job_id và trạng thái queued.
3. Client tiếp tục làm việc khác.
4. Khi hoàn thành, Server gọi POST webhook_url trả kết quả.

Authentication

Header bắt buộc cho mọi request:
X-API-Key: your_secret_key

1. Async Jobs API

Endpoint: POST /v1/jobs. Hỗ trợ retry, queue management và webhook notification.

Create FaceSwap Job (Image)

Mode 1: Single Face

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "faceswap",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "source_url": "https://example.com/face.jpg",
      "target_url": "https://example.com/body.jpg",
      "upscale": 1,
      "max_side": 1280
    }
  }'

Mode 2: Multi-Face

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "faceswap_multi",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "source_urls": [
        "https://ex.com/face1.jpg", 
        "https://ex.com/face2.jpg"
      ],
      "target_url": "https://example.com/group.jpg",
      "swap_faces_index": [0, 1],
      "target_faces_index": [2, 0],
      "sharpen": 0.5
    }
  }'

Param	Type	Desc
`target_url`	string	Required. Ảnh đích.
`source_url`	string	Ảnh chứa mặt gốc (1 mặt).
`source_urls`	array	Mảng ảnh chứa mặt (Nhiều mặt).
`swap_faces_index`	array	Index mặt trong nguồn cần lấy.
`target_faces_index`	array	Index mặt trong đích cần thay.
`max_side`	int	Resize cạnh lớn nhất (Def: 1080).
`upscale`	0/1	Bật Upscale sau khi swap (Def: 1).
`sharpen`	float	Độ sắc nét (e.g. 0.12).
`max_faces`	int	Giới hạn số mặt xử lý (Def: 0 - All).

Create FaceSwap Job (Video)

Mode 1: Single Source

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "faceswap_video",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "source_url": "https://example.com/face.jpg",
      "target_url": "https://example.com/video.mp4",
      "keep_audio": 1
    }
  }'

Mode 2: Multi Source

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "faceswap_video",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "source_urls": ["https://face1.jpg", "https://face2.jpg"],
      "target_url": "https://example.com/video_group.mp4",
      "swap_faces_index": [0, 1],
      "target_faces_index": [0, 1]
    }
  }'

Param	Type	Desc
`target_url`	string	Required. Video đích.
`source_url`	string	Ảnh chứa mặt gốc.
`keep_audio`	0/1	Giữ lại âm thanh gốc (Def: 1).
`fps`	int	FPS output (Optional).
`resolution`	string	(Optional) Target resolution.
`crop_mode`	string	(Optional) Crop logic.
`max_faces`	int	Số mặt tối đa detect.

Create AHV Gen Image Job

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "ahv_image",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "Cyberpunk girl, neon lights, 8k",
      "neg_prompt": "bad quality, blurry",
      "image_url": "https://example.com/face.jpg",
      "width": 768,
      "height": 1152,
      "num_steps": 25,
      "guidance": 4.0
    }
  }'

Param	Type	Desc
`prompt`	string	Required. Mô tả ảnh.
`image_url`	string	Ảnh ID gốc (Tự map sang `id_image_url`).
`width/height`	int	Def: 768x1152.
`num_steps`	int	Số bước infer (Def: 20).
`guidance`	float	CFG Scale (Def: 4.0).
`id_weight`	float	Trọng số ảnh gốc (Def: 1.0).
`quality`	str	"fast" (default).

Create AHV Video Gen Job (Veo 3.1)

Tạo video bằng Google Veo 3.1. Hỗ trợ Text-to-Video (T2V) và Image-to-Video (I2V) — hệ thống tự chọn endpoint phù hợp.

Text-to-Video

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "ahv_video",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "A drone shot flying over mountains at sunset",
      "aspect_ratio": "16:9",
      "model": "fast_relaxed"
    }
  }'

Image-to-Video

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "ahv_video",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "Camera pans right, cinematic lighting",
      "image_url": "https://example.com/scene.jpg",
      "aspect_ratio": "16:9",
      "model": "fast_relaxed"
    }
  }'

Param	Type	Desc
`prompt`	string	Required. Mô tả nội dung video.
`image_url`	string	(Optional) Ảnh đầu vào cho I2V. Nếu không có → T2V.
`aspect_ratio`	string	"16:9" (Def), "9:16", "3:4", "4:3".
`model`	string	Tier hoặc model key trực tiếp (xem bảng dưới).

Model Tiers

Chọn tier — hệ thống tự map sang model key phù hợp (T2V/I2V + landscape/portrait).

Tier	Mô tả
`fast_relaxed`	Mặc định — Nhanh, giá tốt, chất lượng ổn.
`fast`	Nhanh, ưu tiên tốc độ.
`fast_ultra`	Nhanh + chất lượng cao hơn.
`quality`	Chất lượng cao nhất, xử lý lâu hơn.
`lite`	Nhanh nhất, tiết kiệm nhất.

Hoặc gửi model key trực tiếp: veo_3_1_t2v_fast_landscape, veo_3_1_i2v_s_fast_ultra_relaxed, v.v.

Create GG Image Gen Job (Imagen 4)

Tạo ảnh bằng Google Imagen 4 qua Flow Proxy. Hỗ trợ text-to-image và image reference.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "gg_image",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "A futuristic cityscape at night, neon lights",
      "model": "imagen4",
      "aspect_ratio": "16:9"
    }
  }'

Với Reference Image

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "gg_image",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "Same style but in winter",
      "model": "imagen4",
      "aspect_ratio": "1:1",
      "image_url": "https://example.com/reference.jpg"
    }
  }'

Param	Type	Desc
`prompt`	string	Required. Mô tả ảnh cần tạo.
`model`	string	Model: `imagen4` (Def), `banana2`, `banana-pro`.
`aspect_ratio`	string	"1:1" (Def), "16:9", "9:16", "3:4", "4:3".
`image_url`	string	(Optional) URL ảnh tham chiếu.

Create CX Image Gen Job

Tạo ảnh bằng CX API (GPT-5.4 Image). Hỗ trợ text-to-image và edit image (base64).

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "cx_image",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "prompt": "A cute cat wearing a tiny hat, studio photo",
      "model": "cx/gpt-5.4-image",
      "size": "auto",
      "quality": "low"
    }
  }'

Param	Type	Desc
`prompt`	string	Required. Mô tả ảnh cần tạo.
`model`	string	Def: `cx/gpt-5.4-image`.
`size`	string	Kích thước: `auto` (Def), `1024x1024`, `1536x1024`, `1024x1536`.
`quality`	string	`low` (Def), `medium`, `high`.
`background`	string	`auto` (Def), `transparent`, `opaque`.
`image_detail`	string	`low` (Def), `high`.
`output_format`	string	`jpeg` (Def), `png`, `webp`.
`image`	string	(Optional) Base64 ảnh gốc để edit.

Create Upscale & Beauty Job

Tăng độ phân giải, khôi phục khuôn mặt và áp dụng filter làm đẹp.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "upscale",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "target_url": "https://example.com/photo.jpg",
      "max_side": 2048,
      "upscale": 1,
      "restore_face": 1,
      "sharpen": 0.2,
      "beauty_full_face": {
        "enabled": 1,
        "preset": "glamour"
      }
    }
  }'

Basic Parameters

Param	Type	Desc
`target_url`	string	Ảnh gốc.
`max_side`	int	Cạnh lớn nhất (Def: 1080).
`upscale`	0/1	Bật/Tắt Upscale (Def: 1).
`restore_face`	0/1	Khôi phục chi tiết mặt.
`sharpen`	float	Độ sắc nét (Default: 0.12).

Beauty Options (Object)

Nằm trong object beauty_full_face.

Field	Type	Range/Desc
`enabled`	0/1	Kích hoạt Beauty Mode
`skin_smoothing`	float	Làm mịn da (0.0 - 1.0)
`skin_brightening`	float	Làm sáng da (0.0 - 1.0)
`teeth_whitening`	float	Làm trắng răng (0.0 - 1.0)
`eye_enhancement`	float	Nâng cấp mắt (0.0 - 1.0)
`under_eye_concealer`	float	Che quầng thâm mắt (0.0 - 1.0)
`blush_enable`	0/1	Bật phấn hồng
`blush_color`	hex	Màu phấn hồng (e.g #e8727a)
`blush_strength`	float	Độ đậm phấn hồng (0.0 - 1.0)
`lip_tint_enable`	0/1	Bật tô son môi
`lip_tint_color`	hex	Màu son (e.g #cc3355)
`lip_tint_strength`	float	Độ đậm son (0.0 - 1.0)
`lip_gloss`	float	Bóng môi (0.0 - 1.0)
`contour_strength`	float	Tạo khối (0.0 - 1.0)
`highlight_strength`	float	Highlight gương mặt (0.0 - 1.0)
`blemish_removal`	float	Xóa khuyết điểm (0.0 - 1.0)
`face_slim`	float	Thon gọn mặt (0.0 - 1.0)
`eye_enlarge`	float	Phóng to mắt (0.0 - 1.0)
`nose_slim`	float	Thon gọn mũi (0.0 - 1.0)
`chin_slim`	float	Thon gọn cằm (0.0 - 1.0)
`forehead_adjust`	float	Điều chỉnh trán (0.0 - 1.0)
`preset`	string	Preset: natural, glamour ← recommend, studio

💡 Nhanh nhất — dùng Preset

Preset	Mô tả	JSON
💄 natural	Đẹp nhẹ nhàng, tự nhiên — selfie, đời thường	`{"enabled":1, "preset":"natural"}`
✨ glamour	Makeup rõ, cân bằng đẹp & tự nhiên ← recommend	`{"enabled":1, "preset":"glamour"}`
🎬 studio	Pro photo, max đẹp — quảng cáo, profile	`{"enabled":1, "preset":"studio"}`

Khách chỉ cần thêm "beauty_full_face": {"enabled": 1, "preset": "glamour"} vào request là xong! Muốn tùy chỉnh thì dùng các param riêng ở trên.

Create Remove Object Job

Xóa vật thể bằng Mask (`mask_urls`) hoặc Prompt Text (`prompt`).

Payload Example (Multi-Object)

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "remove_object",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "target_url": "https://example.com/image.jpg",
      "mask_urls": [
        "https://example.com/mask1.png",
        "https://example.com/mask2.png"
      ],
      "prompt": "" 
    }
  }'

Param	Type	Desc
`target_url`	string	Ảnh gốc (Hoặc `image_url`).
`mask_urls`	array	Mảng URL mask các vị trí cần xóa.
`prompt`	string	(Optional) Text gợi ý vùng xóa (Def: "").

Create Remove Background Job

Tách nền tự động bằng AI.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "remove_background",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "target_url": "https://example.com/product.jpg"
    }
  }'

Create Scan Objects Job

Phát hiện vật thể trong ảnh và trả về danh sách Labels + Bounding Boxes.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "scan_objects",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "target_url": "https://example.com/street.jpg",
      "threshold": 0.35,
      "max_items": 15
    }
  }'

Param	Type	Desc
`target_url`	string	Ảnh cần scan (Hoặc `image_url`).
`threshold`	float	Độ tin cậy tối thiểu (Def: 0.35).
`max_items`	int	Số vật thể tối đa trả về (Def: 15).

Create Virtual Try-On Job

Thử đồ ảo — ghép quần áo lên ảnh người bằng AI. Hỗ trợ áo, quần, váy, fullset.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "try_on",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "person_image_url": "https://example.com/person.jpg",
      "garment_image_url": "https://example.com/garment.png",
      "category": "auto",
      "num_steps": 25,
      "guidance_scale": 2,
      "seed": 42
    }
  }'

Param	Type	Desc
`person_image_url`	string *	URL ảnh người mẫu (bắt buộc).
`garment_image_url`	string *	URL ảnh quần áo cần thử (bắt buộc).
`category`	string	Loại trang phục: `auto`, `upper`, `lower`, `full` (Def: auto).
`num_steps`	int	Số bước xử lý, càng cao càng chi tiết (Def: 25, range: 10-50).
`guidance_scale`	float	Mức độ bám sát quần áo gốc (Def: 2, range: 1-5).
`seed`	int	Random seed cho kết quả lặp lại (Def: 42).

POST /v1/jobs task: nsfw_check

Kiểm tra ảnh có chứa nội dung 18+/NSFW hay không. Trả về điểm NSFW score và nhãn safe/nsfw.

curl -X POST "{{API_BASE}}/v1/jobs" \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "nsfw_check",
    "webhook_url": "https://your-site.com/webhook",
    "payload": {
      "image_url": "https://example.com/photo.jpg",
      "strict": "medium"
    }
  }'

Param	Type	Desc
`image_url`	string *	URL ảnh cần kiểm tra (bắt buộc).
`strict`	string	Mức độ lọc: `low` (0.75), `medium` (0.55), `high` (0.35). Def: low.
`threshold`	float	Ngưỡng tùy chỉnh 0.0-1.0. Nếu set sẽ ghi đè `strict`.

Response result:

{
  "nsfw_score": 0.0001,
  "is_nsfw": false,
  "threshold": 0.75,
  "strict": "low",
  "label": "safe",
  "elapsed": 0.098
}

Strict Level	Threshold	Mô tả
`low`	0.75	Mặc định, chỉ block rõ ràng
`medium`	0.55	Lọc vừa phải
`high`	0.35	Lọc gắt, nhạy cảm cao

POST /v1/nsfw-check Upload file trực tiếp

Endpoint hỗ trợ upload file ảnh trực tiếp (multipart/form-data) hoặc gửi URL. Tự động upload → tạo job → trả job_id.

Upload file:

curl -X POST "{{API_BASE}}/v1/nsfw-check" \
  -H "X-API-Key: {{API_KEY}}" \
  -F "file=@/path/to/image.jpg" \
  -F "strict=medium"

Gửi URL:

curl -X POST "{{API_BASE}}/v1/nsfw-check" \
  -H "X-API-Key: {{API_KEY}}" \
  -F "image_url=https://example.com/photo.jpg" \
  -F "strict=low"

Param	Type	Desc
`file`	file	Upload ảnh trực tiếp (JPG/PNG/WEBP/GIF, max 10MB). Ưu tiên nếu có.
`image_url`	string	URL ảnh (dùng nếu không upload file).
`strict`	string	Mức độ lọc: `low`, `medium`, `high`. Def: low.
`threshold`	float	Ngưỡng tùy chỉnh 0.0-1.0.
`webhook_url`	string	URL nhận kết quả qua webhook.

Response:

{
  "ok": true,
  "job_id": "abc123...",
  "status": "queued",
  "image_url": "https://...uploaded-file.jpg",
  "predict_time": 5
}

💡 Sau đó dùng GET /v1/jobs/{job_id} để lấy kết quả, hoặc nhận qua webhook.

2. Webhook & Job Status

Webhook Payload: succeeded

{
  "event": "job.finished",
  "event_id": "f03675fc03334822be22b98ee9215c1d",
  "ts": "2026-02-04T18:04:19.463754+00:00",
  "job_id": "d1142818265748d9914053dafc20dd98",
  "task": "upscale",
  "status": "succeeded",
  "progress": 100,
  "ok": true,
  "created_at": "2026-02-04T18:04:13.773524+00:00",
  "created_at_ms": 1770228253773,
  "queued_at": "2026-02-04T18:04:13.773524+00:00",
  "queued_at_ms": 1770228253773,
  "started_at": "2026-02-04T18:04:14.264808+00:00",
  "started_at_ms": 1770228254264,
  "finished_at": "2026-02-04T18:04:19.462901+00:00",
  "finished_at_ms": 1770228259462,
  "duration": 5.198093,
  "predict_time": 3,
  "eta_utc": "2026-02-04T18:04:16.773638+00:00",
  "result": {
    "ok": true,
    "status": "succeeded",
    "url": "http://15.235.200.66:2022/files/3c3da5ddac6a4c5081d46d829d168cb3.jpg",
    "filename": "3c3da5ddac6a4c5081d46d829d168cb3.jpg",
    "meta": {
      "width": 507,
      "height": 678,
      "backend": "UPVN1-1"
    }
  },
  "error": null,
  "predictTime": 3
}

Job Lifecycle Status

Click vào badge để xem mẫu Webhook JSON tương ứng.

queued	Đang chờ trong hàng đợi.
running	Backend đang xử lý.
succeeded	Hoàn thành, có `result.url`.
failed	Lỗi kỹ thuật hoặc timeout.
rejected	Từ chối (NSFW blocked).

3. API Reference

Management Endpoints

`GET /stats`	Lấy danh sách các jobs gần nhất.
`GET /v1/jobs/{id}`	Polling trạng thái Job (nếu không dùng Webhook).
`DELETE /tasks/{id}`	Xóa job khỏi hệ thống.
`GET /diag/backends`	Xem trạng thái tải (slots/concurrency) của các node GPU.

Direct Blocking Endpoints

Gọi trực tiếp, giữ kết nối cho đến khi xong. Payload giống hệt payload của Async Job.

POST `/faceswap`	Xử lý FaceSwap Ảnh
POST `/faceswap/video`	Xử lý FaceSwap Video
POST `/upscale`	Upscale & Restore
POST `/ahv/image`	Gen Ảnh (Text2Img, Img2Img)
POST `/ahv/video`	Video Gen (Veo 3.1 T2V/I2V)
POST `/gg/image`	GG Image Gen (Imagen 4)
POST `/cx/image`	CX Image Gen (GPT-5.4 Image)
POST `/remove-object`	Xóa vật thể (Mask/Prompt)
POST `/scan-objects`	Detect vật thể (JSON)
POST `/remove-background`	Tách nền