简介¶
本指南将带你完成将 iSamurai API 集成到 Python 应用程序中的技术全流程。
iSamurai Python SDK 对我们的 REST API 进行了封装，帮你处理文件上传、结果轮询、错误管理等复杂任务。使用这个 SDK，你可以在不搭建自有基础设施的情况下，用我们的云端 GPU 处理视频。
本教程包含以下内容：
1. 安装与设置
2. AI 换脸（单人与多人）
3. AI 慢动作生成
4. 面向生产环境的最佳实践
1. 安装与设置¶
环境要求¶
- Python 3.8 或更高版本。
- 一个 iSamurai API 密钥（可在你的开发者个人资料中获取）。
安装 SDK¶
使用 pip 直接从 GitHub 安装官方包：
pip install git+https://github.com/isamurai-ai/iSamurai-SDK.git
身份验证¶
使用你的 API 密钥初始化客户端。出于安全考虑，我们建议使用环境变量。
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. AI 换脸¶
该 API 的核心功能是用源人脸替换目标视频或图像中的人脸。
基础单人换脸¶
本示例演示了标准工作流程：上传文件、提交任务并等待结果。
# 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}")
进阶：多人换脸¶
如果你的目标视频中包含多个人物，你可能只想替换其中特定的人脸，而保留其他人脸不变。
第一步：分析视频¶
首先，检测目标视频中的人脸，获取其对应的 ID。
# 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']}")
第二步：创建映射¶
将检测到的 person_id 映射到你想要使用的源图像。
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")
})
第三步：处理¶
将映射数据提交到多人换脸接口。
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. 创建 AI 慢动作¶
你可以使用该 API 从普通视频生成高帧率的慢动作效果，其原理是通过 AI 帧插值来实现流畅的运动效果。
# 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
功能组合使用¶
一种常见的工作流程是将这些操作串联起来：
1. 换脸：处理视频以更改身份。
2. 应用慢动作：将第一步得到的输出 URL 传给慢动作 API。
4. 最佳实践¶
使用图库¶
如果你经常使用同一张源图像（例如某用户的头像），不必每次请求都重新上传。将其上传到图库一次即可节省带宽。
# Upload once
client.upload_to_gallery(["profile.jpg"])
# (Future SDK updates will allow referencing these IDs directly)
高效轮询¶
wait_for_job 辅助方法适合用于脚本，但对于生产环境中的 Web 应用，你应该使用Webhooks。这样一来，任务完成时你的服务器会立即收到通知，而无需保持连接开启。
有关 Webhook 配置，请参阅API 文档。
错误处理¶
请始终将你的 API 调用包裹在 try/except 代码块中。常见错误包括：
* 402 Payment Required：额度不足。
* 400 Bad Request：文件格式或参数无效。
5. 常见问题解答（FAQ）¶
问：我可以将该 API 用于商业应用吗？
答：可以。使用 iSamurai API 生成的所有素材，其完整商业使用权归你所有。你可以基于我们的基础设施构建 SaaS 产品、移动应用或内部工具。
问：速率限制是多少？
答：默认情况下，账户同一时间限制处理一个并发任务。如果在第一个任务运行时提交第二个任务，它将被加入队列等待处理。如需更高的并发限制，请联系支持团队了解企业版方案。
问：我的数据是否私密？
答：是的。源图像和目标视频仅用于处理你所请求的任务。我们不会使用用户数据来训练我们的模型。
问：费用是多少？
答：费用因操作类型（换脸、慢动作等）和分辨率而异。详细信息请参阅我们的价格页面。
总结¶
iSamurai SDK 让你能够更轻松地为 Python 项目添加 AI 视频功能。
相关教程与功能¶
- 查看可视化编辑器：Face Swap Studio PRO 界面
- 阅读完整的开发者文档：API 文档
