iSamurai フェイススワップ API ドキュメント
AIを活用したフェイススワップ、 スローモーション動画、 画像復元をあなたのアプリケーションに統合するための完全な開発者ガイドです。
🚀 はじめに
iSamurai APIは、当社のAIを活用した動画・画像処理ツール群へのプログラムによるアクセスを提供します。コンテンツ制作プラットフォームを構築する場合でも、フェイススワップ技術をアプリに統合する場合でも、映画のようなスローモーション効果を追加する場合でも、当社のRESTful APIならシンプルに実現できます。
ベースURL
https://isamur.ai/api/
クイックスタート手順
クレジットシステム: すべての処理操作はクレジットを消費します。ジョブを送信する前に/api/user-credits/で残高を確認してください。クレジットパッケージについては料金プランをご覧ください。
📦 SDK & ツール
公式クライアントライブラリとコード例で開発を加速しましょう。
🔐 認証
すべてのAPIエンドポイントには認証が必要です。すべてのリクエストのAuthorizationヘッダーに認証情報を含めてください。
APIキー認証(推奨)
APIキーは、サーバー間連携に推奨される認証方法です。キーは失効せず、すべてのエンドポイントにシンプルかつ安全にアクセスできます。
curl -H "Authorization: Api-Key isk_your_api_key_here" \
https://isamur.ai/api/user-credits/
🎭 フェイススワップ API
フェイススワップ APIを使用すると、動画や画像の顔をシームレスに入れ替えることができます。まずプレビューエンドポイントで1フレームだけテストしてから、動画全体を処理してください。
クイックプレビュー(単一フレーム)
/api/preview-swap-api/
動画全体を処理する前に、フェイススワップの単一フレームプレビューを生成します。base64エンコードされた画像を使用します。コストは約1〜2クレジットです。
リクエストボディ(JSON)
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
source_image_base64 | string | 必須 | base64エンコードされたソース顔画像 |
target_image_base64 | string | 必須 | base64エンコードされたターゲットフレーム(動画または画像から) |
instance | UUID | 任意 | 既存のFaceSwapインスタンスID |
enhance | boolean | 任意 | 顔の強調処理を適用する(デフォルト:false) |
import requests
import base64
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# 画像をbase64に変換
def to_base64(file_path):
with open(file_path, "rb") as f:
return base64.b64encode(f.read()).decode()
# プレビューを生成
response = requests.post(
f"{BASE_URL}/preview-swap-api/",
headers={
"Authorization": f"Api-Key {API_KEY}",
"Content-Type": "application/json"
},
json={
"source_image_base64": to_base64("face.jpg"),
"target_image_base64": to_base64("target_frame.jpg"),
"enhance": False
}
)
# プレビュー画像を保存
preview_base64 = response.json()["image_base64"]
with open("preview.jpg", "wb") as f:
f.write(base64.b64decode(preview_base64))
レスポンス
{
"image_base64": "/9j/4AAQSkZJRgABAQAAAQ...",
"preview_id": "abc123"
}
動画のフル処理(アップロードと処理の統合)
/api/full-process-swap/
ファイルをアップロードし、1回のリクエストで即座に処理を開始します。自動化されたワークフローに推奨されるエンドポイントです。クレジットは動画1分あたり約50消費されます。
リクエストパラメーター(multipart/form-data)
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
source_image | File | 必須 | 顔画像ファイル(JPG/PNG) |
target_media | File | 必須 | 動画ファイル(MP4/MOV)または画像 |
gquality | string | 必須 | 480p、720p、または1080p |
name | string | 任意 | ジョブ名(最大20文字) |
description | string | 任意 | 説明(最大20文字) |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# ローカルファイルをアップロードして処理を開始
with open("face.jpg", "rb") as source, open("video.mp4", "rb") as target:
response = requests.post(
f"{BASE_URL}/full-process-swap/",
headers={"Authorization": f"Api-Key {API_KEY}"},
files={
"source_image": ("face.jpg", source, "image/jpeg"),
"target_media": ("video.mp4", target, "video/mp4")
},
data={
"gquality": "720p",
"name": "My Swap",
"description": "Demo"
}
)
result = response.json()
instance_id = result["faceswap"]["id"]
print(f"Processing started: {instance_id}")
進行状況の確認
/api/swap-progress/?id={instance_id}
ステータスがDoneになるまで、このエンドポイントをポーリングしてジョブの進行状況を監視します。
ステータス値
| ステータス | 説明 |
|---|---|
Queued | キューで待機中 |
Processing | 処理中 |
Done | 完了 - 出力が利用可能 |
Failed | エラーが発生 |
Cancelled | ユーザーがキャンセル |
import time
while True:
response = requests.get(
f"{BASE_URL}/swap-progress/",
headers={"Authorization": f"Api-Key {API_KEY}"},
params={"id": instance_id}
)
data = response.json()
print(f"Status: {data['status']} - {data.get('progress_percentage', 0)}%")
if data["status"] == "Done":
print(f"Output: {data['output_media_url']}")
break
elif data["status"] in ["Failed", "Cancelled"]:
print(f"Error: {data.get('error')}")
break
time.sleep(5)
ジョブの停止/キャンセル
/api/stop-job/
実行中のジョブをキャンセルします。50%のクレジットが返金されます。
{"id": "instance_uuid", "type": "faceswap"}
👥 マルチフェイススワップ API
1本の動画内で複数の顔を入れ替えます。フレームを解析してすべての顔を検出し、それぞれにソース画像を割り当ててから処理します。
ステップ1:フレームの解析(顔の検出)
/api/analyse-frame/
動画フレーム内のすべての顔を検出します。ターゲット動画からbase64エンコードされたフレームを送信してください。
リクエストボディ(JSON)
| パラメーター | 型 | 説明 |
|---|---|---|
target_image_base64 | string | ターゲット動画からのbase64エンコードされたフレーム |
import base64
# 動画からフレームをキャプチャ(OpenCV、ffmpegなどを使用)
with open("frame.jpg", "rb") as f:
frame_b64 = base64.b64encode(f.read()).decode()
response = requests.post(
f"{BASE_URL}/analyse-frame/",
headers={
"Authorization": f"Api-Key {API_KEY}",
"Content-Type": "application/json"
},
json={"target_image_base64": frame_b64}
)
faces = response.json()["analysis"]
for face in faces:
print(f"Face detected: {face['person_id']}")
レスポンス
{
"analysis": [
{"person_id": "P1", "thumbnail": "base64...", "bbox": [x, y, w, h]},
{"person_id": "P2", "thumbnail": "base64...", "bbox": [x, y, w, h]}
]
}
ステップ2:マルチスワップのプレビュー(任意)
/api/multi-preview-swap-api/
本処理の前に、単一フレームでマルチフェイススワップをプレビューします。
リクエストボディ(JSON)
{
"target_image_base64": "base64_frame...",
"analysis_results": [
{
"person_id": "P1",
"thumbnail": "base64...",
"source_image": "base64_of_source_face_1"
},
{
"person_id": "P2",
"thumbnail": "base64...",
"source_image": "base64_of_source_face_2"
}
],
"enhance": false
}
レスポンス
{"preview_image": "base64_result..."}
ステップ3:マルチフェイスのフル処理
/api/multiple-face-swap/
すべての顔のマッピングを使用して動画全体を処理します。multipart/form-dataを使用してください。
リクエストパラメーター(multipart/form-data)
| パラメーター | 型 | 説明 |
|---|---|---|
target_media | File | 動画ファイル(MP4/MOV) |
gquality | string | 480p、720p、または1080p |
analysis_results | JSON string | 各顔のsource_image base64を含む配列 |
ステップ4:進行状況の確認
/api/swap-progress/?id={instance_id}&multi=True
進行状況をポーリングします。マルチフェイススワップのジョブにはmulti=Trueを追加してください。
⏱️ スローモーション & FPSブースト API
AIフレーム補間を使用して、驚くほど滑らかなスローモーション動画を作成します。当社のスローモーション技術は既存のフレームの間に新しいフレームを生成し、滑らかで自然な動きを保ちながら映像を最大8倍までスローダウンできます。
クレジット料金
| 係数 | 1秒あたりのコスト | 用途 |
|---|---|---|
| 2倍スロー | 2クレジット/秒 | 滑らかなスローモーション |
| 4倍ウルトラ | 3クレジット/秒 | ドラマチックなスローモーション |
| 8倍スーパー | 7クレジット/秒 | 極端なスローモーション |
スローモーションプロジェクトの作成
/api/slowmotion/
動画をアップロードし、スローモーションの設定を行います。
リクエストパラメーター(multipart/form-data)
| パラメーター | 型 | 選択肢 | 説明 |
|---|---|---|---|
source_video | File | - | スローダウンする動画(MP4/MOV) |
slowdown_factor | int | 2, 4, 8 | どの程度スローダウンするか |
quality | string | 480p, 720p, 1080p | 出力品質 |
mode | string | slowmo, fps | slowmo = よりスローな動画、fps = より滑らかな動画 |
with open("action_clip.mp4", "rb") as video:
response = requests.post(
f"{BASE_URL}/slowmotion/",
headers={"Authorization": f"Api-Key {API_KEY}"},
files={"source_video": video},
data={
"slowdown_factor": 4,
"quality": "720p",
"mode": "slowmo"
}
)
project = response.json()["slowmotion"]
print(f"Project ID: {project['id']}")
処理の開始
/api/faceswap/slowmotion/process/
スローモーション処理を開始します。
{ "project_id": "uuid" }
/api/faceswap/slowmotion/progress/{project_id}/
スローモーション処理の進行状況を確認します。
✨ 画像復元 & 強調 API
当社のAIを活用した画像復元ツールを使用して、古く傷んだ写真を復元したり、顔の画質を強調したりできます。ヴィンテージ写真に新たな命を吹き込んだり、低解像度の顔画像を改善したりするのに最適です。
/api/restore-image/
AIによる復元または強調処理で画像を処理します。
リクエストパラメーター(multipart/form-data)
| パラメーター | 型 | 選択肢 |
|---|---|---|
image | File | JPG/PNG画像 |
mode | string | restoreまたはface_enhance |
レスポンス
{
"url": "/api/media/restored/output.jpg",
"image_base64": "/9j/4AAQSkZ...",
"status": "success"
}
💳 ユーザーとクレジット API
クレジット残高とアカウントステータスを確認できます。ジョブを送信する前に、十分な残高があることを確認してください。クレジットを追加購入する場合は料金プランをご覧ください。
/api/user-credits/
現在のクレジット残高とプラン情報を取得します。
レスポンス
{
"user_id": 123,
"user_credits": 9500,
"plan_id": 5,
"plan_name": "Samurai"
}
🖼️ ギャラリー API
アップロード済みのソース画像を管理します。画像は一度アップロードすれば、複数のフェイススワップジョブで再利用できます。
ソース画像のアップロード
/api/gallery/sources/
1枚以上のソース画像をギャラリーにアップロードします。imagesフィールドを使用してmultipart/form-dataで送信してください。
リクエストパラメーター(multipart/form-data)
| パラメーター | 型 | 説明 |
|---|---|---|
images | File(s) | 1つ以上の画像ファイル(JPG/PNG)。複数アップロードする場合はフィールドを繰り返してください。 |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# 複数の画像をアップロード
files = [
("images", ("face1.jpg", open("face1.jpg", "rb"), "image/jpeg")),
("images", ("face2.jpg", open("face2.jpg", "rb"), "image/jpeg")),
]
response = requests.post(
f"{BASE_URL}/gallery/sources/",
headers={"Authorization": f"Api-Key {API_KEY}"},
files=files
)
result = response.json()
print(f"Uploaded: {result['message']}")
for img in result["images"]:
print(f" ID: {img['id']} - {img['name']}")
レスポンス
{
"message": "2 images uploaded successfully",
"images": [
{"id": "uuid-1", "name": "face1.jpg", "url": "/media/sources/..."},
{"id": "uuid-2", "name": "face2.jpg", "url": "/media/sources/..."}
]
}
ソース画像の一覧取得
/api/gallery/sources/
アップロード済みのソース画像をページネーション付きで一覧表示します。
クエリパラメーター
| パラメーター | デフォルト | 説明 |
|---|---|---|
page | 1 | ページ番号 |
per_page | 20 | 1ページあたりの件数(最大50) |
レスポンス
{
"images": [{"id": "uuid", "name": "face.jpg", "url": "..."}],
"has_next": true,
"total": 45
}
ソース画像の削除
/api/gallery/sources/{image_id}/
IDを指定して単一のソース画像を削除します。
/api/gallery/sources/bulk-delete/
複数のソース画像をまとめて削除します。
{"ids": ["uuid-1", "uuid-2", "uuid-3"]}
プレビュー(生成済みスワップ)
/api/gallery/previews/
フェイススワップ操作から保存されたプレビュー画像を一覧表示します。
⚠️ エラーハンドリング
すべてのAPIエラーは、エラーメッセージを含む一貫したJSON構造を返します。HTTPステータスコードを使用してエラーの種類を判別してください。
| ステータスコード | 意味 | 対応 |
|---|---|---|
| 400 | Bad Request | リクエストパラメーターを確認してください |
| 401 | Unauthorized | APIキーが有効か確認してください |
| 403 | Forbidden | クレジット不足または権限不足 |
| 404 | Not Found | リソースが存在しません |
| 500 | Server Error | サポートにお問い合わせください |
エラーレスポンスの形式
{
"error": "Insufficient credits: need 500, have 200",
"success": false
}
🚦 レート制限
各ユーザーは同時に1つのジョブのみ実行できます。新しいジョブを送信する前に、現在のジョブが完了するのをお待ちください。ジョブの処理中に新しいジョブを送信した場合、キューに追加されます。
📚 完全なコード例
よくあるユースケースの完全な実装例です。
Python:完全なフェイススワップワークフロー
import requests
import time
API_KEY = "isk_your_key_here"
BASE_URL = "https://isamur.ai/api"
HEADERS = {"Authorization": f"Api-Key {API_KEY}"}
def face_swap(source_path, target_path, quality="720p"):
# ステップ1:アップロード
with open(source_path, "rb") as src, open(target_path, "rb") as tgt:
resp = requests.post(f"{BASE_URL}/faceswap/", headers=HEADERS,
files={"source_image": src, "target_media": tgt},
data={"gquality": quality})
job_id = resp.json()["faceswap"]["id"]
# ステップ2:処理
requests.post(f"{BASE_URL}/process-swap/",
headers={**HEADERS, "Content-Type": "application/json"},
json={"instance": job_id})
# ステップ3:完了を待機
while True:
resp = requests.get(f"{BASE_URL}/swap-progress/",
headers=HEADERS, params={"id": job_id})
data = resp.json()
print(f"Progress: {data.get('progress_percentage', 0)}%")
if data["status"] == "Done":
return data["output_media_url"]
elif data["status"] == "Failed":
raise Exception(data.get("error"))
time.sleep(3)
# 使用例
output = face_swap("face.jpg", "video.mp4")
print(f"Result: https://isamur.ai{output}")
JavaScript:完全なフェイススワップワークフロー
const API_KEY = "isk_your_key_here";
const BASE_URL = "https://isamur.ai/api";
async function faceSwap(sourceFile, targetFile, quality = "720p") {
// ステップ1:アップロード
const formData = new FormData();
formData.append("source_image", sourceFile);
formData.append("target_media", targetFile);
formData.append("gquality", quality);
let resp = await fetch(`${BASE_URL}/faceswap/`, {
method: "POST",
headers: { "Authorization": `Api-Key ${API_KEY}` },
body: formData
});
const jobId = (await resp.json()).faceswap.id;
// ステップ2:処理
await fetch(`${BASE_URL}/process-swap/`, {
method: "POST",
headers: {
"Authorization": `Api-Key ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ instance: jobId })
});
// ステップ3:完了をポーリング
while (true) {
resp = await fetch(`${BASE_URL}/swap-progress/?id=${jobId}`, {
headers: { "Authorization": `Api-Key ${API_KEY}` }
});
const data = await resp.json();
console.log(`Progress: ${data.progress_percentage || 0}%`);
if (data.status === "Done") return data.output_media_url;
if (data.status === "Failed") throw new Error(data.error);
await new Promise(r => setTimeout(r, 3000));
}
}