iSamurai フェイススワップ API ドキュメント

AIを活用したフェイススワップスローモーション動画画像復元をあなたのアプリケーションに統合するための完全な開発者ガイドです。

🚀 はじめに

iSamurai APIは、当社のAIを活用した動画・画像処理ツール群へのプログラムによるアクセスを提供します。コンテンツ制作プラットフォームを構築する場合でも、フェイススワップ技術をアプリに統合する場合でも、映画のようなスローモーション効果を追加する場合でも、当社のRESTful APIならシンプルに実現できます。

ベースURL

https://isamur.ai/api/

クイックスタート手順

  1. iSamuraiでアカウントを作成します
  2. プロフィールページに移動し、APIキーを生成します
  3. リクエストヘッダーにAPIキーを含めます
  4. APIコールを開始しましょう!
💡

クレジットシステム: すべての処理操作はクレジットを消費します。ジョブを送信する前に/api/user-credits/で残高を確認してください。クレジットパッケージについては料金プランをご覧ください

📦 SDK & ツール

公式クライアントライブラリとコード例で開発を加速しましょう。

Python

公式SDK

自動ポーリング、型ヒント、エラーハンドリングを備えた完全なPythonラッパーです。

GitHubで見る →
Code

API サンプル

API連携に直接使える生のスクリプトと使用例です。

GitHubで見る →

🔐 認証

すべてのAPIエンドポイントには認証が必要です。すべてのリクエストのAuthorizationヘッダーに認証情報を含めてください。

APIキー認証(推奨)

APIキーは、サーバー間連携に推奨される認証方法です。キーは失効せず、すべてのエンドポイントにシンプルかつ安全にアクセスできます。

curl -H "Authorization: Api-Key isk_your_api_key_here" \
  https://isamur.ai/api/user-credits/

🎭 フェイススワップ API

フェイススワップ APIを使用すると、動画や画像の顔をシームレスに入れ替えることができます。まずプレビューエンドポイントで1フレームだけテストしてから、動画全体を処理してください。

クイックプレビュー(単一フレーム)

POST /api/preview-swap-api/

動画全体を処理する前に、フェイススワップの単一フレームプレビューを生成します。base64エンコードされた画像を使用します。コストは約1〜2クレジットです。

リクエストボディ(JSON)

パラメーター必須説明
source_image_base64string必須base64エンコードされたソース顔画像
target_image_base64string必須base64エンコードされたターゲットフレーム(動画または画像から)
instanceUUID任意既存のFaceSwapインスタンスID
enhanceboolean任意顔の強調処理を適用する(デフォルト: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"
}

動画のフル処理(アップロードと処理の統合)

POST /api/full-process-swap/

ファイルをアップロードし、1回のリクエストで即座に処理を開始します。自動化されたワークフローに推奨されるエンドポイントです。クレジットは動画1分あたり約50消費されます。

リクエストパラメーター(multipart/form-data)

パラメーター必須説明
source_imageFile必須顔画像ファイル(JPG/PNG)
target_mediaFile必須動画ファイル(MP4/MOV)または画像
gqualitystring必須480p720p、または1080p
namestring任意ジョブ名(最大20文字)
descriptionstring任意説明(最大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}")

進行状況の確認

GET /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)

ジョブの停止/キャンセル

POST /api/stop-job/

実行中のジョブをキャンセルします。50%のクレジットが返金されます。

{"id": "instance_uuid", "type": "faceswap"}

👥 マルチフェイススワップ API

1本の動画内で複数の顔を入れ替えます。フレームを解析してすべての顔を検出し、それぞれにソース画像を割り当ててから処理します。

ステップ1:フレームの解析(顔の検出)

POST /api/analyse-frame/

動画フレーム内のすべての顔を検出します。ターゲット動画からbase64エンコードされたフレームを送信してください。

リクエストボディ(JSON)

パラメーター説明
target_image_base64stringターゲット動画からの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:マルチスワップのプレビュー(任意)

POST /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:マルチフェイスのフル処理

POST /api/multiple-face-swap/

すべての顔のマッピングを使用して動画全体を処理します。multipart/form-dataを使用してください。

リクエストパラメーター(multipart/form-data)

パラメーター説明
target_mediaFile動画ファイル(MP4/MOV)
gqualitystring480p720p、または1080p
analysis_resultsJSON string各顔のsource_image base64を含む配列

ステップ4:進行状況の確認

GET /api/swap-progress/?id={instance_id}&multi=True

進行状況をポーリングします。マルチフェイススワップのジョブにはmulti=Trueを追加してください。

⏱️ スローモーション & FPSブースト API

AIフレーム補間を使用して、驚くほど滑らかなスローモーション動画を作成します。当社のスローモーション技術は既存のフレームの間に新しいフレームを生成し、滑らかで自然な動きを保ちながら映像を最大8倍までスローダウンできます。

クレジット料金

係数1秒あたりのコスト用途
2倍スロー2クレジット/秒滑らかなスローモーション
4倍ウルトラ3クレジット/秒ドラマチックなスローモーション
8倍スーパー7クレジット/秒極端なスローモーション

スローモーションプロジェクトの作成

POST /api/slowmotion/

動画をアップロードし、スローモーションの設定を行います。

リクエストパラメーター(multipart/form-data)

パラメーター選択肢説明
source_videoFile-スローダウンする動画(MP4/MOV)
slowdown_factorint2, 4, 8どの程度スローダウンするか
qualitystring480p, 720p, 1080p出力品質
modestringslowmo, fpsslowmo = よりスローな動画、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']}")

処理の開始

POST /api/faceswap/slowmotion/process/

スローモーション処理を開始します。

{ "project_id": "uuid" }
GET /api/faceswap/slowmotion/progress/{project_id}/

スローモーション処理の進行状況を確認します。

✨ 画像復元 & 強調 API

当社のAIを活用した画像復元ツールを使用して、古く傷んだ写真を復元したり、顔の画質を強調したりできます。ヴィンテージ写真に新たな命を吹き込んだり、低解像度の顔画像を改善したりするのに最適です。

POST /api/restore-image/

AIによる復元または強調処理で画像を処理します。

リクエストパラメーター(multipart/form-data)

パラメーター選択肢
imageFileJPG/PNG画像
modestringrestoreまたはface_enhance

レスポンス

{
  "url": "/api/media/restored/output.jpg",
  "image_base64": "/9j/4AAQSkZ...",
  "status": "success"
}

💳 ユーザーとクレジット API

クレジット残高とアカウントステータスを確認できます。ジョブを送信する前に、十分な残高があることを確認してください。クレジットを追加購入する場合は料金プランをご覧ください

GET /api/user-credits/

現在のクレジット残高とプラン情報を取得します。

レスポンス

{
  "user_id": 123,
  "user_credits": 9500,
  "plan_id": 5,
  "plan_name": "Samurai"
}

⚠️ エラーハンドリング

すべてのAPIエラーは、エラーメッセージを含む一貫したJSON構造を返します。HTTPステータスコードを使用してエラーの種類を判別してください。

ステータスコード意味対応
400Bad Requestリクエストパラメーターを確認してください
401UnauthorizedAPIキーが有効か確認してください
403Forbiddenクレジット不足または権限不足
404Not Foundリソースが存在しません
500Server 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));
    }
}

始める準備はできましたか? アカウントを作成し、プロフィールページからAPIキーを生成しましょう。