Tổng quan

Một endpoint duy nhất cho toàn bộ chức năng sinh video.

Hệ thống gồm 6 chức năng gen video qua 3 vendor. DashScope & WaveSpeed đi qua Worker proxy (prefix /ds, /ws); Ufoto app gọi thẳng (tự ký sign).

Luồng chung mọi chức năng: submit job → nhận task_id/URL → poll mỗi 3s tới khi có video hoặc lỗi (tối đa ~10 phút) → tải video về.

Dùng ngay

3 bước là chạy, không cần Firebase/SDK.

1) Health check (không cần token)

curl https://aivideo-proxy.manhpd-football.workers.dev/health
# → ok

2) Submit 1 job Text→Video

curl -X POST \
  https://aivideo-proxy.manhpd-football.workers.dev/ds/api/v1/services/aigc/video-generation/video-synthesis \
  -H "X-App-Token: " \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{"model":"wan2.6-t2v","input":{"prompt":"a cat on the beach"},"parameters":{"size":"1280*720","duration":5}}'

3) Poll tới khi xong

curl https://aivideo-proxy.manhpd-football.workers.dev/ds/api/v1/tasks/{task_id} \
  -H "X-App-Token: "
# output.task_status: PENDING → RUNNING → SUCCEEDED (kèm output.video_url)

Kiến trúc

App → Worker → Vendor. Key thật chỉ nằm ở Worker.

Ufoto không qua Worker — app gọi thẳng cpi.ufotosoft.com / face-api.ufotosoft.com và tự ký sign (xem mục Ký request).

Xác thực

Mọi request tới proxy phải mang header token.

Thiếu hoặc sai token → 401 Unauthorized. Riêng /health không cần token.

🧪 Test thật

Gõ prompt → tạo video thật qua proxy → xem kết quả ngay tại đây.

Chức năng Ghép mặt vào mẫu — GIỐNG APP (Ufoto FaceFusion) Text → Ảnh (Dezgo) Ảnh + Prompt → Ảnh — GIỮ MẶT (Kontext / Gemini) Text → Video (wan2.6-t2v) Image → Video — ảnh của bạn (wan2.6-i2v-flash) Face Swap — video của bạn (WaveSpeed)

Chọn mẫu (bấm để chọn) —

Ảnh mặt của bạn

Video của bạn (để ghép mặt vào)

Prompt (tùy chọn) a cute cat walking on the beach at sunset, cinematic

Kích thước ảnh 5127681024

Model ảnh Mặc định Dreamshaper 8 (đa năng) Absolute Reality (ảnh thực) Realistic Vision (ảnh thực) CyberRealistic Epic Diffusion Stable Diffusion 1.5

Steps 20253550

Negative prompt (thứ cần tránh)

Model (giữ mặt) Flux Kontext Pro — nhanh (~6s) Nano-Banana / Gemini — đẹp hơn (~1 phút)

Mẹo prompt: nói rõ "giữ nguyên khuôn mặt, chỉ đổi trang phục/bối cảnh". Tránh từ mask (che mặt). Ảnh nên rõ mặt, chính diện.

Kích thước 1280*720720*1280960*960

Thời lượng (s) 510

⚡ Nhanh (480p · 3s) — render nhanh hơn, chất lượng thấp hơn

▶ Tạo video ✕ Huỷ

🧭 Dùng cái nào? — hướng dẫn chọn

Mỗi nhu cầu → chọn đúng chức năng + đầu vào cần chuẩn bị.

Mẹo chạy nhanh & ít lỗi

• ⚡ Nhanh (Text/Image→Video): tick để render 480p · 3s — nhanh hơn nhiều, hợp lúc test. Bỏ tick khi cần chất lượng cao.
• Ảnh mặt: chọn ảnh rõ mặt, chính diện, đủ sáng. Trang tự nén ảnh (≤1280px, JPEG) nên HEIC/ảnh to vẫn OK.
• strength (Ảnh→Ảnh): 0.3–0.5 giữ gần ảnh gốc; 0.7–0.95 biến đổi mạnh theo prompt.
• Lỗi mạng/máy chủ tạm thời: trang tự thử lại (poll & upload) — cứ để chạy.
• Video mất 1–5 phút là bình thường (phía vendor), không phải treo. Có đồng hồ đếm giây + log tiến trình.

Lỗi hay gặp

Text → Video

Sinh video từ prompt bằng model wan2.6-t2v.

{
  "model": "wan2.6-t2v",
  "input": { "prompt": "a cat walking on the beach at sunset" },
  "parameters": { "size": "1280*720", "duration": 5 }
}

{
  "output": { "task_id": "06ad4c22-...", "task_status": "PENDING" }
}

Image → Video

Sinh video từ ảnh (kèm prompt & audio lip-sync tùy chọn) bằng wan2.6-i2v-flash.

{
  "model": "wan2.6-i2v-flash",
  "input": {
    "img_url": "https://cdn.../face.jpg",
    "prompt": "gentle smile, cinematic",
    "audio_url": "https://cdn.../voice.mp3"
  },
  "parameters": { "resolution": "720P", "duration": 5 }
}

Poll task (DashScope)

Dùng chung cho Text→Video và Image→Video.

{
  "output": {
    "task_status": "SUCCEEDED",
    "video_url": "https://.../result.mp4"
  }
}

Upload file (WaveSpeed)

Đưa file local lên CDN để lấy URL dùng cho i2v / face swap.

{ "data": { "download_url": "https://cdn.wavespeed.ai/..." } }

Face Swap (WaveSpeed)

Ghép mặt vào video.

{ "video": "https://cdn.../src.mp4", "face_image": "https://cdn.../face.jpg" }

{ "data": { "urls": { "get": "https://aivideo-proxy.../ws/..." } } }

Ufoto — Ký request

Các chức năng Template/Effect/Live gọi thẳng Ufoto, không qua proxy.

Mỗi request gắn bộ header sau:

Ufoto — Upload face

{ "c": 200, "d": [ "https://.../face.jpeg" ] }

Ufoto — Face Fusion (template & multi-face)

{ "c": 200, "d": { "jobId": "..." } }

{ "c": 200, "d": { "videoFaceFusionOutput": { "videoUrl": "https://.../out.mp4" } } }

Ufoto — AI Effect (beatImage2Video)

{ "imageUrls": ["https://.../face.jpg"], "level": 0, "effectType": 12 }

Ufoto — AI Live Photo (livePortrait)

{ "imageUrls": ["https://.../face.jpg"], "modelId": "<song id>", "ifFace": true, "level": 0 }

Text → Ảnh (Dezgo)

Sinh ảnh từ mô tả. Gọi qua proxy, key Dezgo chèn server-side.

curl -X POST https://video-api-docs.pages.dev/proxy/dezgo/text2image \
  --data-urlencode "prompt=a knight in shining armor, epic" \
  --data-urlencode "model=dreamshaper_8" \
  --data-urlencode "negative_prompt=blurry, deformed" \
  --data-urlencode "steps=25" --data-urlencode "width=768" --data-urlencode "height=768" \
  --output out.png

🦸 Sửa ảnh giữ mặt (Ảnh + Prompt → Ảnh)

Gửi ảnh + mô tả → đổi trang phục/bối cảnh nhưng giữ nguyên khuôn mặt. Đây là cách đúng cho "chế thành siêu anh hùng". Chạy qua WaveSpeed (đã proxy sẵn).

Luồng (2 bước)

1. Upload ảnh gốc → CDN: POST /proxy/ws/api/v3/media/upload/binary?ext=jpg → data.download_url
2. Gọi model + prompt → poll tới khi xong:

{ "prompt": "keep the exact same face, only change clothing into a superhero costume",
  "image": "https://cdn.../src.jpg" }
// Nano-Banana dùng "images": [url] (số nhiều) thay cho "image"

Code mẫu

Gọi Text→Video + poll.

Swift (async/await)

let base = "https://aivideo-proxy.manhpd-football.workers.dev"
let token = ""

func submitT2V(prompt: String) async throws -> String {
  var req = URLRequest(url: URL(string: base + "/ds/api/v1/services/aigc/video-generation/video-synthesis")!)
  req.httpMethod = "POST"
  req.setValue(token, forHTTPHeaderField: "X-App-Token")
  req.setValue("application/json", forHTTPHeaderField: "Content-Type")
  req.setValue("enable", forHTTPHeaderField: "X-DashScope-Async")
  req.httpBody = try JSONSerialization.data(withJSONObject: [
    "model": "wan2.6-t2v",
    "input": ["prompt": prompt],
    "parameters": ["size": "1280*720", "duration": 5]
  ])
  let (data, _) = try await URLSession.shared.data(for: req)
  let json = try JSONSerialization.jsonObject(with: data) as! [String:Any]
  return ((json["output"] as! [String:Any])["task_id"] as! String)
}

cURL

curl -X POST "$BASE/ds/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "X-App-Token: $TOKEN" -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{"model":"wan2.6-t2v","input":{"prompt":"..."},"parameters":{"size":"1280*720","duration":5}}'

Polling

Chiến lược chờ kết quả.

Chỉ dừng khi đạt trạng thái terminal (thành công/thất bại) hoặc chạm giới hạn thời gian.

Mã lỗi

Proxy / DashScope

Ufoto (field c)

Tự dựng Worker

Khi cần proxy riêng (đổi tài khoản, xoay key).

# trong thư mục proxy-worker/
npx wrangler login
npx wrangler secret put ALI_KEY           # key DashScope
npx wrangler secret put WSK               # key WaveSpeed
npx wrangler secret put APP_PROXY_TOKEN   # token tự đặt
npx wrangler deploy                       # in ra URL Worker

Sau đó cập nhật BASE URL + X-App-Token trong app. Xoay key: chạy lại secret put + deploy, không cần build lại app (trừ khi đổi token).