Welcome to the official iSamurai Face Swap API repository!
This guide serves as a comprehensive tutorial for developers, creators, and businesses looking to integrate professional-grade face swapping capabilities directly into their applications, workflows, or scripts. With the iSamurai API, you can automate high-quality ai face swap, image editing, and slow motion video processing at scale.
- Official Documentation: isamur.ai/documentation
- Python SDK: iSamurai-SDK
- Community Support: r/iSamurai_FaceSwap
- Tutorials & News: Website Blog
iSamurai is the leading platform for realistic, high-fidelity face swapping. Our API exposes the same powerful engine that drives our web platform, allowing you to:
- Automate Content Creation: Generate personalized videos and images programmatically.
- Scale Your Production: Process hundreds of swaps without manual intervention.
- Integrate Seamlessly: Use standard REST API endpoints compatible with any programming language (Python, JavaScript, cURL, etc.).
- Secure & Private: All processing happens on our secure GPU cloud with strict privacy controls.
We've provided ready-to-use Python scripts to help you get started immediately. These scripts handle the authentication and request logic so you can focus on building your application.
Before running heavy jobs, it's good practice to verify your connection and credit balance.
- Purpose: Validates your API Key and retrieves your current plan and available credits.
- Usage: Run this to ensure your API Key is correctly configured.
This is the core script for processing media. It uploads your source (face) and target (media) files to our secure servers and starts the face swap engine.
- Purpose: Uploads images/videos and initiates a "Full Process" job.
- Features: Supports 480p, 720p, and 1080p quality settings.
- Returns: A unique
Job IDthat you will uses to track progress.
Face swapping is a complex AI process that takes time. This script polls the server to check the status of your submitted job.
- Purpose: Monitors a specific
Job IDuntil completion. - Output: Returns the final high-quality download URL when the job is "Done".
Follow this guide to run your first automated face swap.
- Python 3.6+ installed on your machine.
- An active iSamurai Subscription (Developer Mode is available on paid plans).
- Your unique API Key.
- Log in to your iSamurai Profile.
- Scroll down to the Developer Mode section.
- Click Create API Key.
- Copy the key immediately (e.g.,
isk_...). Keep this secret!
Open each python script and locate the API_KEY Configuration line:
API_KEY = "YOUR_API_KEY_HERE" # Replace with your actual keyPaste your key inside the quotes.
Open your terminal or command prompt and run:
python test_apikey_credits.pySuccess Output:
Checking credits...
Status Code: 200
Credits: 1500
Plan: Samurai
✅ Verification Successful!
Prepare a source image (face) and a target video/image. Run the process script:
python test_apikey_process.py ./my_face.jpg ./my_video.mp4The script will upload the files and return a Job ID (e.g., 12345).
Use the Job ID from the previous step to check the status:
python test_apikey_progress.py 12345The script will check every few seconds. Once finished, it will output:
✅ Job completed!
Output URL: https://isamur.ai/media/output/final_video.mp4
Click the link to download your masterpiece!
- Error Handling: The API returns standard HTTP status codes (200 for success, 403 for unauthorized/no credits, 429 for rate limits).
- Webhooks: For production apps, consider checking out our advanced docs for webhook integration (coming soon) to avoid polling.
- Security: Never commit your API Key to public repositories (like GitHub). Use environment variables in production.
Need help? Join our active community on Reddit or contact support via the Validation Dashboard.
Happy Swapping!