Developer API

Kết nối web riêng qua API XiaoYang

Luồng chạy: web riêng của bạn -> API XiaoYang kiểm credit và trừ credit -> hệ thống xử lý.

Không nhúng API key vào frontend public. Hãy gọi các endpoint này từ backend/server riêng của bạn.

Lưu ý nguyên liệu: image_url, video_url và clothes_image_url phải là link file public tải trực tiếp. Không dùng link share/preview Google Drive, Mega, trang xem trước hoặc link cần đăng nhập; các link này sẽ bị từ chối hoặc trả lỗi E_DIRECT_MEDIA_URL.

API keys

Đang tải...

Endpoint mẫu

GET https://xiaoyang.online/api/v1/me
Authorization: Bearer xy_your_api_key

GET https://xiaoyang.online/api/v1/modals
Authorization: Bearer xy_your_api_key

POST https://xiaoyang.online/api/v1/tasks
Authorization: Bearer xy_your_api_key
Content-Type: application/json

{
  "modal_key": "img2vid_v30",
  "option_key": "5_off",
  "prompt": "Create a cinematic video",
  "image_url": "https://your-domain.com/input.png"
}

POST https://xiaoyang.online/api/v1/tasks
Authorization: Bearer xy_your_api_key
Content-Type: application/json

{
  "modal_key": "motion_v30",
  "option_key": "default",
  "prompt": "Make the person follow the reference motion",
  "image_url": "https://your-domain.com/input.png",
  "video_url": "https://your-domain.com/motion.mp4",
  "motion_orientation": "video"
}

POST https://xiaoyang.online/api/v1/tasks
Authorization: Bearer xy_your_api_key
Content-Type: application/json

{
  "modal_key": "seedance_v20",
  "option_key": "720p_5_off",
  "prompt": "Create a smooth commercial video",
  "image_url": "https://your-domain.com/input.png",
  "ratio": "16:9"
}

POST https://xiaoyang.online/api/v1/tasks
Authorization: Bearer xy_your_api_key
Content-Type: application/json

{
  "modal_key": "ai_wardrobe",
  "option_key": "default",
  "image_url": "https://your-domain.com/person.png",
  "clothes_image_url": "https://your-domain.com/clothes.png",
  "wardrobe_replace": "upper"
}

GET https://xiaoyang.online/api/v1/tasks/{task_id}
Authorization: Bearer xy_your_api_key

GET https://xiaoyang.online/api/v1/tasks/{task_id}/download
Authorization: Bearer xy_your_api_key

Model, setting và giá credit

modal_keyoption_keyCreditInput

Đang tải...

Tham số POST /api/v1/tasks

FieldBắt buộcGiá trị hợp lệGhi chú

modal_keyCóĐang tải...Chọn đúng model đang mở trong danh sách bên trên.

option_keyCóĐang tải...Phải thuộc modal_key tương ứng.

promptTheo modelstringChỉ dùng cho Image to Video, Motion Control và Seedance. Không gửi prompt cho AI Wardrobe/Enhance.

image_urlTheo modelURL ảnh public trực tiếpCần cho Image to Video, Motion Control, Seedance, AI Wardrobe và Enhance Image. Không dùng Google Drive/Mega share link.

video_urlTheo modelURL video public trực tiếpCần cho Motion Control và Enhance Video. Phải tải thẳng file MP4, không phải trang preview.

clothes_image_urlAI Wardrobe bắt buộcURL ảnh public trực tiếpẢnh quần áo/trang phục. Không dùng link cần đăng nhập hoặc trang xem trước.

wardrobe_replaceKhôngupper, lower, dress, coat, jumpsuit, fullChỉ dùng cho ai_wardrobe, mặc định upper

motion_orientationKhôngvideo, imageChỉ dùng cho Motion Control, mặc định có thể bỏ trống

ratioKhôngadaptive, 1:1, 3:4, 4:3, 9:16, 16:9, 21:9Chỉ dùng cho Seedance, mặc định adaptive.

enhance_4kKhôngtrue, falseTạo xong sẽ tự nâng lên HD 2K nếu model gốc hỗ trợ. Mặc định false.

Response schema

// POST /api/v1/tasks thành công
{
  "ok": true,
  "task_id": "TASK_ID",
  "status": "QUEUED",
  "credits": 1234
}

// GET /api/v1/tasks/{task_id}
{
  "ok": true,
  "task_id": "TASK_ID",
  "status": "SUCCESS",
  "error_message": null,
  "video_url": "/api/v1/tasks/TASK_ID/download",
  "image_url": null,
  "created_at": 1779710000,
  "credit": 72
}

status có thể là QUEUED, PENDING, PROCESSING, SUCCESS, FAIL. Khi kết quả là video, response có video_url. Khi kết quả là ảnh như ai_wardrobe, response có image_url. Cả hai đều là đường dẫn tải kết quả qua API của XiaoYang.

Mã lỗi và ngoại lệ

HTTPÝ nghĩaResponse

400Thiếu tham số, modal/option sai, URL nguyên liệu không hợp lệ{"detail":"..."}

401Thiếu hoặc sai API key{"detail":"Invalid API key"}

402Tài khoản không đủ credit{"detail":"Không đủ credit"}

403Tài khoản bị khóa{"detail":"Account suspended"}

404Không tìm thấy task{"detail":"Task not found"}

502Hệ thống xử lý tạm thời quá tải hoặc đang gặp lỗi{"detail":"..."}

Giới hạn và polling

Hiện chưa đặt rate limit cứng theo phút, nhưng hãy polling mỗi 10-30 giây cho từng task. Không polling mỗi 1-2 giây vì có thể làm chậm hệ thống và dễ bị chặn.

Ảnh/video đầu vào bắt buộc là URL public có thể tải trực tiếp từ server, định dạng thông dụng như JPG, PNG, WEBP, MP4. Không dùng link share Google Drive/Mega vì thường trả về trang HTML/preview, làm Motion Control báo image_url/video_url rỗng.

Webhook hiện chưa mở cho user API. Cách hiện tại là polling GET /api/v1/tasks/{task_id} đến khi status là SUCCESS hoặc FAIL.