はじめに¶
このガイドでは、iSamurai APIをPythonアプリケーションに統合するための技術的な手順を解説します。
iSamurai Python SDKは当社のREST APIをラップし、ファイルのアップロード、結果のポーリング、エラー管理といった複雑な処理を担当します。このSDKを使用すれば、自前のインフラを管理することなく、当社のクラウドGPUを使って動画を処理できます。
このチュートリアルでは、以下の内容を扱います。
1. インストールとセットアップ
2. 顔スワップ(単一・複数人物)
3. スローモーション生成
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. 顔スワップ¶
この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}")
応用編:複数人物の顔スワップ¶
ターゲット動画に複数の人物が写っている場合、特定の顔だけをスワップし、他はそのままにしたいことがあります。
ステップ1:動画を解析する¶
まず、ターゲット動画内の顔を検出し、その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']}")
ステップ2:マッピングを作成する¶
検出された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")
})
ステップ3:処理を実行する¶
マッピングをマルチスワップのエンドポイントに送信します。
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. スローモーションを適用する:ステップ1の出力URLを取得し、スローモーションAPIに送信します。
4. ベストプラクティス¶
ギャラリーの活用¶
同じソース画像(例:ユーザーのプロフィール画像)を頻繁に使用する場合は、リクエストのたびにアップロードする必要はありません。帯域を節約するため、ギャラリーに一度だけアップロードしてください。
# Upload once
client.upload_to_gallery(["profile.jpg"])
# (Future SDK updates will allow referencing these IDs directly)
効率的なポーリング¶
wait_for_jobヘルパーはスクリプトには便利ですが、本番のWebアプリケーションではWebhookの使用を推奨します。これにより、接続を維持し続けることなく、ジョブが完了した時点でサーバーに即座に通知されます。
Webhookの設定については、APIドキュメントをご参照ください。
エラーハンドリング¶
API呼び出しは必ずtry/exceptブロックで囲んでください。よくあるエラーは以下の通りです。
* 402 Payment Required:クレジット不足。
* 400 Bad Request:無効なファイル形式またはパラメータ。
5. よくある質問(FAQ)¶
Q: APIを商用アプリケーションに使用できますか?
A: はい。iSamurai APIを使用して生成されたすべてのメディアについて、完全な商用利用権を保持します。当社のインフラを使ってSaaS製品、モバイルアプリ、社内ツールなどを構築できます。
Q: レート制限はありますか?
A: デフォルトでは、アカウントごとに同時実行できるジョブは1件までに制限されています。1件目の処理中に2件目のジョブを送信すると、キューに追加されます。より高い同時実行数が必要な場合は、Enterpriseプランについてサポートまでお問い合わせください。
Q: データのプライバシーは保護されますか?
A: はい。ソース画像とターゲット動画は、依頼されたジョブの処理のみに使用されます。ユーザーデータをモデルの学習に使用することはありません。
Q: 料金はいくらですか?
A: 料金は処理内容(顔スワップ、スローモーションなど)や解像度によって異なります。詳細は料金ページをご覧ください。
まとめ¶
iSamurai SDKを使えば、AI動画機能をPythonプロジェクトに簡単に追加できます。
関連チュートリアルと機能¶
- ビジュアルエディタを見る:Face Swap Studio PRO UI
- 開発者向けドキュメント全体を読む:APIドキュメント
