API untuk pengembang · v1

API tukar wajah untuk gambar, video, GIF, dan foto grup

Gunakan alur tugas produksi yang sama dengan studio web FaceSwapAI melalui rute berversi stabil. Otentikasi, rumus kredit nyata, batas file, status tugas, dan perilaku kegagalan didokumentasikan dari penangan yang berjalan.

Kontrak produksi langsung · OpenAPI 3.1 · Diperbarui 30 Agustus 2026

Mulai cepat

Buat kunci di akun terverifikasi Anda, kirim permintaan multibagian dari server Anda, lalu lakukan polling rute GET yang cocok dengan taskId yang dikembalikan. Jaga rahasia di luar bundel browser dan klien seluler.

  1. 1Membuat dan menyalin kunci satu kali
  2. 2Kirimkan ke media lokal dengan persetujuan=benar
  3. 3Lakukan polling selama status PENDING atau 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"

Titik akhir dan harga pasti

MetodeRuteTujuanRumus kredit
POST/api/v1/face-swap/imagePertukaran wajah gambar6
POST/api/v1/face-swap/videoPertukaran wajah videomax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/gifGIF pertukaran wajahmax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/multiplePertukaran gambar beberapa wajah6 × selectedTargetFaces
GET/api/v1/tasksRiwayat tugas0

Contoh kredit yang dikerjakan

Satu tugas gambar66 kredit
Video empat detikmax(9, 3 × ceil(4))12 kredit
GIF delapan detikmax(9, 3 × ceil(8))24 kredit
GIF delapan belas detikmax(9, 3 × ceil(18))54 kredit

Bidang permintaan berdasarkan titik akhir

Pilih rute berdasarkan media target, lalu kirimkan kolom multibagian yang tepat di bawah. Kontrol restorasi opsional menerima angka dari 0 hingga 1.

POST/api/v1/face-swap/image

Pertukaran wajah gambar

Menerapkan satu identitas sumber pada satu foto target.

Diperlukan
sourceImagetargetImageconsent=true
Opsional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/video

Pertukaran wajah video

Menerapkan satu identitas sumber di seluruh video target yang diunggah.

Diperlukan
sourceImagetargetVideoconsent=true
Opsional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/gif

GIF pertukaran wajah

Menerapkan satu identitas sumber di seluruh target yang diunggah GIF.

Diperlukan
sourceImagetargetGifconsent=true
Opsional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/multiple

Pertukaran gambar beberapa wajah

Ganti satu hingga sepuluh wajah yang dipilih dalam satu foto grup.

Diperlukan
sourceImagetargetFace0consent=true
Opsional
targetFace1...targetFace9faceBox0...faceBox9
GET/api/v1/tasks

Riwayat tugas

Daftar tugas yang dimiliki oleh akun yang diautentikasi.

Opsional
pagepageSizestatustaskType

Jajak pendapat setiap tugas media

Setelah POST media mengembalikan taskId, kirim GET ke rute media yang sama dengan taskId sebagai parameter kueri selama status PENDING atau PROCESSING. COMPLETED, FAILED, dan CANCELLED bersifat terminal.

Otentikasi pembawa

Kirim kunci di setiap permintaan sebagai Otorisasi: Pembawa YOUR_API_KEY. Kunci API mewarisi akun terverifikasi dan saldo kredit langsungnya. Batas autentikasi tingkat aplikasi adalah 300 permintaan per menit; kapasitas pembangkitan tetap bergantung pada antrian.

HTTP
Authorization: Bearer YOUR_API_KEY

Contoh JavaScript dan Python

Contoh sisi server ini mengirimkan dua file lokal, menolak kegagalan HTTP, melakukan polling rute tugas yang cocok, dan mencetak URL hasil sementara. Setiap bidang berasal dari kontrak OpenAPI langsung.

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"))

Kirim, lalu polling

POST yang berhasil mencadangkan kredit yang diperlukan dan mengembalikan taskId. Poll rute media yang sama selama status PENDING atau PROCESSING. COMPLETED, FAILED, dan CANCELLED bersifat terminal. Kegagalan antrean atau penyedia mengembalikan reservasi tertunda tepat satu kali.

cURL
curl --get https://faceswapai.com/api/v1/face-swap/image \
  --header "Authorization: Bearer $FACESWAPAI_API_KEY" \
  --data-urlencode "taskId=YOUR_TASK_ID"
PENDING
Diterima dan diantri
PROCESSING
Berlari
COMPLETED
Hasil tersedia
FAILED
Berhenti karena kesalahan publik
CANCELLED
Dibatalkan

Format dan batasan

Gambar menerima JPG, PNG, WebP, GIF, BMP, HEIC atau HEIF hingga 30 MB. Video menerima MP4, MOV, WebM atau AVI hingga 100 MB dan 600 detik. 100 MB setara dengan sekitar 1–2 menit video 1080p biasa dari ponsel, jadi kompres atau potong klip yang lebih panjang. Target GIF dibatasi hingga 30 MB dan 30 detik. Input beberapa wajah dibatasi masing-masing 15 MB dan sepuluh wajah yang dipilih.

Kesalahan HTTP dan percobaan ulang

Jangan mencoba lagi respons 400, 401, 402, 403, atau 413 tanpa mengubah permintaan atau status akun. Mundur di 429. 500 atau 503 dapat dicoba lagi setelah penundaan; reservasi kredit dilindungi oleh jalur pengembalian tugas.

Batasan produksi saat ini

Merencanakan kontrak publik v1 yang ada saat ini, termasuk apa yang tidak diklaimnya.

  • Tugas media tidak sinkron dan menggunakan polling. Kontrak v1 publik saat ini tidak menampilkan webhook.
  • Tidak ada rute batch publik, bidang kunci idempotensi, rute kamera langsung, SLA yang dipublikasikan, atau jaminan waktu penyelesaian.
  • Kunci API ada di server yang dilindungi. Hasil bersifat sementara, kapasitas pembangkitan bergantung pada antrean, dan kegagalan yang diterima menggunakan jalur pengembalian dana yang terdokumentasi.

Persetujuan, privasi, dan tanda air

Setiap generasi memerlukan persetujuan=true, artinya Anda memiliki izin untuk menggunakan setiap wajah yang diunggah. Media tugas bersifat sementara. Tidak ada uji coba gratis: setiap tugas dibayar dengan kredit sekali beli, dan setiap hasil tidak memiliki tanda air dan tidak berisi email akun.

FAQ Tukar Wajah API

Apakah ada kunci Face Swap API gratis?

Membuat kunci API gratis. Generasi menggunakan saldo kredit akun. Tidak ada uji coba gratis maupun tingkat API gratis: setiap tugas dibayar dengan kredit sekali beli, mulai 600 kredit seharga US$19,99.

Apakah API mendukung video dan banyak wajah?

Ya. Rute berversi mencakup tugas gambar, video, GIF, dan gambar banyak wajah. Harga video dan GIF dihitung dari metadata media yang diukur.

Bagaimana saya tahu kalau hasilnya sudah siap?

Baca taskId dari respons POST dan poll rute GET yang sesuai selama status PENDING atau PROCESSING. COMPLETED menyertakan URL hasil sementara; FAILED dan CANCELLED juga bersifat terminal.

Bisakah saya memanggil API langsung dari browser?

Jangan memaparkan kunci rahasia dalam kode browser. Kirim permintaan dari server Anda sendiri, fungsi tanpa server, atau backend terlindungi lainnya.