Introduction¶

This guide provides a technical walkthrough for integrating the iSamurai API into your Python applications.

The iSamurai Python SDK wraps our REST API, handling complex tasks like file uploads, polling for results, and error management. By using this SDK, you can process videos using our cloud GPUs without managing your own infrastructure.

This tutorial covers:
1. Installation & Setup
2. Face Swapping (Single and Multi-face)
3. Slow Motion Generation
4. Best Practices for production

1. Installation and Setup¶

Requirements¶

• Python 3.8 or higher.
• An iSamurai API Key (available in your Developer Profile).

Install the SDK¶

Install the official package directly from GitHub using pip:

pip install git+https://github.com/isamurai-ai/iSamurai-SDK.git

Authentication¶

Initialize the client with your API key. We recommend using environment variables for security.

import os
from isamurai import Isamurai

# Initialize the client
api_key = os.getenv("ISAMURAI_API_KEY", "isk_YOUR_KEY_HERE")
client = Isamurai(api_key=api_key)

# Verify connection
credits = client.get_credits()
print(f"Connected. Credits available: {credits['credits']}")

2. Face Swapping¶

The core function of the API is replacing a face in a target video or image with a source face.

Basic Single Face Swap¶

This example demonstrates the standard workflow: uploading files, submitting a job, and waiting for the result.

# 1. Submit the job
job_id = client.process_face_swap(
    source_path="face.jpg",         # The face provider
    target_path="video.mp4",        # The target media
    quality="1080p",                # 720p or 1080p
    enhance=True                    # Apply face enhancement
)

print(f"Job started: {job_id}")

# 2. Wait for completion
# The SDK handles polling automatically
try:
    result = client.wait_for_job(job_id)
    print(f"Download URL: {result['output_media_url']}")
except Exception as e:
    print(f"Processing failed: {e}")

Advanced: Multi-Face Swap¶

If your target video contains multiple people, you may want to swap specific faces while leaving others unchanged.

Step 1: Analyze the Video¶

First, detect the faces in the target video to get their IDs.

# Analyze a representative frame from the video
faces = client.analyze_frame("target_frame.jpg")

# List all detected faces
for face in faces:
    print(f"ID: {face['person_id']}, Location: {face['location']}")

Step 2: Create a Mapping¶

Map the detected person_id to your desired source image.

mapping = []

# Example: Swap the first detected face with 'user_face.jpg'
mapping.append({
    "person_id": faces[0]['person_id'],
    "source_image": client._to_base64("user_face.jpg")
})

Step 3: Process¶

Submit the mapping to the multi-swap endpoint.

job_id = client.process_multi_face_swap(
    target_path="video.mp4",
    analysis_results=mapping
)
result = client.wait_for_job(job_id, multi=True)
print(result['output_media_url'])

3. Creating AI Slow Motion¶

You can use the API to generate high frame-rate slow motion from standard footage. This uses AI frame interpolation to create smooth motion.

# 1. Upload and create project
# mode='slowmo' slows the video down (e.g. 30fps -> 30fps at 4x duration)
job_id = client.create_slow_motion(
    video_path="input_video.mp4",
    slowdown_factor=4,   # Options: 2, 4, 8
    mode="slowmo"
)

# 2. Start processing
client.process_slow_motion(job_id)

# 3. Monitor status (Custom polling logic required for SlowMo currently)
# See documentation for status endpoints

Combining Features¶

A common workflow is to pipeline these operations:
1. Swap Face: Process a video to change the identity.
2. Apply Slow Motion: Take the output URL from step 1 and send it to the Slow Motion API.

4. Best Practices¶

Using the Gallery¶

If you frequently use the same source image (e.g., a user's profile picture), do not upload it for every request. Upload it once to the Gallery to save bandwidth.

# Upload once
client.upload_to_gallery(["profile.jpg"])

# (Future SDK updates will allow referencing these IDs directly)

efficient Polling¶

The wait_for_job helper is useful for scripts, but for production web applications, you should use Webhooks. This allows your server to be notified immediately when a job is done, rather than keeping a connection open.

Refer to the API Documentation for webhook configuration.

Error Handling¶

Always wrap your API calls in try/except blocks. Common errors include:
* 402 Payment Required: Insufficient credits.
* 400 Bad Request: Invalid file formats or parameters.

5. Frequently Asked Questions (FAQ)¶

Q: Can I use the API for commercial applications?
A: Yes. You retain full commercial rights to all media generated using the iSamurai API. You can build SaaS products, mobile apps, or internal tools using our infrastructure.

Q: What are the rate limits?
A: By default, accounts are limited to one concurrent job processing at a time. If you submit a second job while the first is running, it will be queued. For higher concurrency limits, please contact support for an Enterprise plan.

Q: Is my data private?
A: Yes. Source images and target videos are used solely for processing the requested job. We do not use user data to train our models.

Q: How much does it cost?
A: Costs vary based on the operation (Face Swap, Slow Motion, etc.) and resolution. Please clearer details are available on our Pricing Page.

Summary¶

The iSamurai SDK simplifies adding AI video features to your Python projects.

• Download SDK Source
• View Full API Reference