API cho nhà phát triển · v1

API hoán đổi khuôn mặt cho hình ảnh, video, GIF và ảnh nhóm

Sử dụng cùng một quy trình nhiệm vụ sản xuất như các studio web FaceSwapAI thông qua các tuyến đường được phiên bản ổn định. Xác thực, công thức tín dụng thực, giới hạn tệp, trạng thái nhiệm vụ và hành vi lỗi được ghi lại từ trình xử lý đang chạy.

Hợp đồng sản xuất trực tiếp · OpenAPI 3.1 · Cập nhật ngày 30 tháng 8 năm 2026

Bắt đầu nhanh

Tạo khóa trong tài khoản đã được xác minh của bạn, gửi yêu cầu nhiều phần từ máy chủ của bạn, sau đó thăm dò lộ trình GET phù hợp với taskId được trả về. Giữ bí mật bên ngoài gói trình duyệt và ứng dụng khách di động.

  1. 1Tạo và sao chép khóa một lần
  2. 2Gửi phương tiện truyền thông địa phương với sự đồng ý=true
  3. 3Thăm dò khi trạng thái là PENDING hoặc PROCESSING
cURL
curl --request POST https://faceswapai.com/api/v1/face-swap/image \
  --header "Authorization: Bearer $FACESWAPAI_API_KEY" \
  --form "sourceImage=@./source.jpg" \
  --form "targetImage=@./target.jpg" \
  --form "consent=true"

Điểm cuối và giá chính xác

Phương thứcĐiểm cuốiMục đíchCông thức tín dụng
POST/api/v1/face-swap/imageHoán đổi khuôn mặt trong hình ảnh6
POST/api/v1/face-swap/videoHoán đổi khuôn mặt videomax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/gifHoán đổi khuôn mặt GIFmax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/multipleHoán đổi hình ảnh nhiều mặt6 × selectedTargetFaces
GET/api/v1/tasksLịch sử nhiệm vụ0

Ví dụ về tín dụng đã làm việc

Một tác vụ hình ảnh66 tín dụng
Video bốn giâymax(9, 3 × ceil(4))12 tín dụng
GIF tám giâymax(9, 3 × ceil(8))24 tín dụng
GIF mười tám giâymax(9, 3 × ceil(18))54 tín dụng

Các trường yêu cầu theo điểm cuối

Chọn tuyến theo phương tiện đích, sau đó gửi các trường gồm nhiều phần chính xác bên dưới. Các điều khiển khôi phục tùy chọn chấp nhận các số từ 0 đến 1.

POST/api/v1/face-swap/image

Hoán đổi khuôn mặt trong hình ảnh

Áp dụng một nhận dạng nguồn cho một ảnh mục tiêu.

Bắt buộc
sourceImagetargetImageconsent=true
Tùy chọn
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/video

Hoán đổi khuôn mặt video

Áp dụng một danh tính nguồn xuyên suốt video mục tiêu được tải lên.

Bắt buộc
sourceImagetargetVideoconsent=true
Tùy chọn
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/gif

Hoán đổi khuôn mặt GIF

Áp dụng một danh tính nguồn cho toàn bộ mục tiêu GIF được tải lên.

Bắt buộc
sourceImagetargetGifconsent=true
Tùy chọn
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/multiple

Hoán đổi hình ảnh nhiều mặt

Thay thế từ một đến mười khuôn mặt đã chọn trong một ảnh nhóm.

Bắt buộc
sourceImagetargetFace0consent=true
Tùy chọn
targetFace1...targetFace9faceBox0...faceBox9
GET/api/v1/tasks

Lịch sử nhiệm vụ

Liệt kê các tác vụ thuộc sở hữu của tài khoản được xác thực.

Tùy chọn
pagepageSizestatustaskType

Thăm dò mọi tác vụ truyền thông

Sau khi POST nội dung trả về taskId, hãy gửi GET đến cùng tuyến với taskId làm tham số truy vấn khi trạng thái là PENDING hoặc PROCESSING. COMPLETED, FAILED và CANCELLED là trạng thái kết thúc.

Xác thực người mang

Gửi khóa trong mọi yêu cầu dưới dạng Ủy quyền: Bearer YOUR_API_KEY. Khóa API kế thừa tài khoản đã được xác minh và số dư tín dụng trực tiếp của tài khoản đó. Giới hạn xác thực ở cấp ứng dụng là 300 yêu cầu mỗi phút; công suất phát điện vẫn phụ thuộc vào hàng đợi.

HTTP
Authorization: Bearer YOUR_API_KEY

Ví dụ về JavaScript và Python

Các ví dụ phía máy chủ này gửi hai tệp cục bộ, từ chối lỗi HTTP, thăm dò tuyến tác vụ phù hợp và in URL kết quả tạm thời. Mọi lĩnh vực đều đến từ hợp đồng OpenAPI trực tiếp.

JavaScriptNode.js 18+
JavaScript · Node.js 18+
import { readFile } from 'node:fs/promises';

const apiUrl = 'https://faceswapai.com/api/v1/face-swap/image';
const headers = {
  Authorization: 'Bearer ' + process.env.FACESWAPAI_API_KEY,
};
const form = new FormData();
form.set('sourceImage', new Blob([await readFile('./source.jpg')]), 'source.jpg');
form.set('targetImage', new Blob([await readFile('./target.jpg')]), 'target.jpg');
form.set('consent', 'true');

const submitted = await fetch(apiUrl, { method: 'POST', headers, body: form });
if (!submitted.ok) throw new Error(submitted.status + ': ' + await submitted.text());
const { taskId } = await submitted.json();

let task;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const polled = await fetch(apiUrl + '?taskId=' + encodeURIComponent(taskId), { headers });
  if (!polled.ok) throw new Error(polled.status + ': ' + await polled.text());
  task = await polled.json();
} while (task.status === 'PENDING' || task.status === 'PROCESSING');

console.log(task.status === 'COMPLETED' ? task.result?.url : task.result?.error);
Pythonrequests 2.x
Python · requests 2.x
import os
import time
import requests

api_url = "https://faceswapai.com/api/v1/face-swap/image"
headers = {"Authorization": "Bearer " + os.environ["FACESWAPAI_API_KEY"]}

with open("source.jpg", "rb") as source, open("target.jpg", "rb") as target:
    response = requests.post(
        api_url,
        headers=headers,
        files={"sourceImage": source, "targetImage": target},
        data={"consent": "true"},
        timeout=60,
    )
response.raise_for_status()
task_id = response.json()["taskId"]

while True:
    time.sleep(2)
    response = requests.get(api_url, headers=headers, params={"taskId": task_id}, timeout=30)
    response.raise_for_status()
    task = response.json()
    if task["status"] not in ("PENDING", "PROCESSING"):
        break

result = task.get("result") or {}
print(result.get("url") if task["status"] == "COMPLETED" else result.get("error"))

Gửi đi rồi bình chọn

POST thành công sẽ giữ số tín dụng cần thiết và trả về taskId. Hãy thăm dò cùng tuyến nội dung khi trạng thái là PENDING hoặc PROCESSING. COMPLETED, FAILED và CANCELLED là trạng thái kết thúc. Lỗi hàng đợi hoặc nhà cung cấp hoàn lại khoản giữ đúng một lần.

cURL
curl --get https://faceswapai.com/api/v1/face-swap/image \
  --header "Authorization: Bearer $FACESWAPAI_API_KEY" \
  --data-urlencode "taskId=YOUR_TASK_ID"
PENDING
Đã chấp nhận và xếp hàng
PROCESSING
Đang chạy
COMPLETED
Đã có kết quả
FAILED
Đã dừng do lỗi công khai
CANCELLED
Đã hủy

Định dạng và giới hạn

Hình ảnh chấp nhận JPG, PNG, WebP, GIF, BMP, HEIC hoặc HEIF lên tới 30 MB. Video chấp nhận MP4, MOV, WebM hoặc AVI lên tới 100 MB và 600 giây. 100 MB tương đương khoảng 1–2 phút video 1080p thông thường quay bằng điện thoại, vì vậy hãy nén hoặc cắt bớt các clip dài hơn. Mục tiêu GIF được giới hạn ở 30 MB và 30 giây. Đầu vào nhiều mặt được giới hạn ở mức 15 MB mỗi mặt và mười mặt được chọn.

Lỗi HTTP và số lần thử lại

Không thử lại các phản hồi 400, 401, 402, 403 hoặc 413 mà không thay đổi trạng thái yêu cầu hoặc tài khoản. Quay lại 429. Có thể thử lại 500 hoặc 503 sau một thời gian trì hoãn; việc đặt trước tín dụng được bảo vệ bởi con đường hoàn trả nhiệm vụ.

Ranh giới sản xuất hiện tại

Lập kế hoạch dựa trên hợp đồng v1 công khai tồn tại ngày nay, bao gồm cả những gì nó không yêu cầu.

  • Tác vụ phương tiện không đồng bộ và sử dụng tính năng bỏ phiếu. Hợp đồng v1 công khai hiện tại không hiển thị webhook.
  • Không có lộ trình hàng loạt công khai, trường idempotency-key, lộ trình camera trực tiếp, SLA được xuất bản hoặc thời gian hoàn thành được đảm bảo.
  • Khóa API thuộc về máy chủ được bảo vệ. Kết quả là tạm thời, công suất phát điện phụ thuộc vào hàng đợi và các lỗi được chấp nhận sẽ sử dụng đường dẫn hoàn tiền được ghi lại.

Sự đồng ý, quyền riêng tư và hình mờ

Mọi thế hệ đều yêu cầu sự đồng ý=true, nghĩa là bạn có quyền sử dụng mọi khuôn mặt đã tải lên. Phương tiện tác vụ là tạm thời. Không có bản dùng thử miễn phí: mọi tác vụ đều trả bằng tín dụng mua một lần, và mọi kết quả đều không có hình mờ và không chứa email tài khoản.

Câu hỏi thường gặp về API hoán đổi khuôn mặt

Có key API Face Swap miễn phí không?

Tạo khóa API là miễn phí. Thế hệ sử dụng số dư tín dụng tài khoản. Không có bản dùng thử miễn phí hay cấp API miễn phí: mọi tác vụ đều trả bằng tín dụng mua một lần, từ 600 tín dụng giá 19,99 US$.

API có hỗ trợ video và nhiều khuôn mặt không?

Vâng. Các tuyến được phiên bản bao gồm các tác vụ hình ảnh, video, GIF và hình ảnh nhiều mặt. Giá video và GIF được tính toán từ siêu dữ liệu phương tiện đo được.

Làm sao tôi biết khi nào có kết quả?

Đọc taskId từ phản hồi POST và thăm dò tuyến GET tương ứng khi trạng thái là PENDING hoặc PROCESSING. COMPLETED gồm URL kết quả tạm thời; FAILED và CANCELLED cũng là trạng thái kết thúc.

Tôi có thể gọi trực tiếp đến API từ trình duyệt không?

Không để lộ khóa bí mật trong mã trình duyệt. Gửi yêu cầu từ máy chủ của riêng bạn, chức năng serverless hoặc chương trình phụ trợ được bảo vệ khác.