顔交換APIでできること
顔交換APIは2枚の画像を受け取り、新しい画像を1枚返します。ソース画像には使いたい顔が写っています。ターゲット画像は変更したい写真です。APIはターゲット内の顔を見つけてソースの顔に置き換え、肌の色、光、角度をなじませて、1枚の写真のように仕上げます。
開発者はこれを、パーソナライズしたグリーティングカード、「ポスターにあなたが登場」キャンペーン、アバターやプロフィールのツール、ゲームキャラクター、イベントのフォトブースアプリなどに使っています。自分でモデルを学習・ホストする代わりに、HTTPリクエストを1回送るだけで画像が返ってきます。
始める前に
必要なものは3つです。
- Morfranアカウント。 新規アカウントには50クレジットが無料で付与されます。1人の顔交換10回分です。
- APIキー。 ダッシュボードのAPIキーで作成します。キーはサーバー側で保管し、ブラウザやモバイルアプリのコードには絶対に入れないでください。
- 公開されている画像URLを2つ。 JPG、PNG、WebPのいずれか。ソースには、ほぼカメラの方を向いたはっきりした顔が1つ写っている必要があります。
すべてのリクエストで、キーを X-API-Key ヘッダーに入れて送ります。ベースURLは https://api.morfran.com です。
curlで最初の顔交換
curl -X POST https://api.morfran.com/v1/face-swap \
-H "X-API-Key: $MORFRAN_KEY" \
-H "Content-Type: application/json" \
-d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'
デフォルトでは呼び出しは同期型です。APIは結果を待ち(最大約60秒)、cdn.morfran.com 上の完成画像へのリンクと使用したクレジットを含むJSONレスポンスを返します。結果は1時間後に削除されるため、画像はすぐにダウンロードしてください。
同じリクエストをJavaScript(Node.js)で
const res = await fetch("https://api.morfran.com/v1/face-swap", {
method: "POST",
headers: {
"X-API-Key": process.env.MORFRAN_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
SourceImageUrl: "https://example.com/face.jpg",
TargetImageUrl: "https://example.com/photo.jpg",
}),
});
const data = await res.json();
console.log(res.status, data);
キーを非公開に保つため、このコードはブラウザではなくサーバーで実行してください。
同じリクエストをPythonで
import os
import requests
res = requests.post(
"https://api.morfran.com/v1/face-swap",
headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
json={
"SourceImageUrl": "https://example.com/face.jpg",
"TargetImageUrl": "https://example.com/photo.jpg",
},
timeout=90,
)
print(res.status_code, res.json())
時間のかかる処理:非同期モードを使う
アプリが開いたままのリクエストで待つべきでない場合は、URLに ?async=true を付けます。APIはすぐにタスクIDを返します。その後、完了するまで数秒おきに GET /v1/face-swap/{taskId} で結果を取得します。ジョブキューの裏側で動かす場合や、自分のサーバーのリクエストタイムアウトが短い場合に便利です。
グループ写真:最大8人の顔を交換
チーム写真や家族写真には POST /v1/face-swap/group を使います。1回の呼び出しで最大8人の顔を変更でき、上限は MaxFaces で設定します。グループ顔交換は10クレジット、1人の顔交換は5クレジットです。フィールドの一覧はAPIドキュメントとOpenAPIスキーマにあります。
エラーとクレジットの扱い
- 401:APIキーがない、または間違っています。
X-API-Keyヘッダーを確認してください。 - 402:クレジットが足りません。ダッシュボードでクレジットパックを購入してください。
- 422:顔が見つかりませんでした。顔が1つだけ写った、よりはっきりした写真をユーザーに依頼してください。
失敗したリクエストには課金されません。クレジットは完成した画像に対してのみ差し引かれるため、422の後に再試行しても二重に料金はかかりません。残高は GET /v1/credits/balance でいつでも無料で確認できます。
より良い結果を得るコツ
- はっきりしたソースの顔を使う。 1人だけ、カメラの方を向き、目を開け、サングラスなし、明るい光で。
- 角度を合わせる。 正面を向いた顔は、ターゲットの人物もほぼカメラの方を向いている写真に最もよくなじみます。
- 顔を十分な大きさにする。 ターゲット内で数ピクセル幅しかない顔は、うまく交換できません。
- 光の条件が近いと効果的。 日中の光で撮った顔は、日中の光で撮ったターゲット写真で最も自然に見えます。
- 実際の画像でテストする。 無料クレジットの一部を、ユーザーがアップロードしそうな写真で試してみましょう。
同意とプライバシー
顔を交換するのは、本人が同意している場合だけにしてください。人をだます目的、他人になりすます目的、実在の人物を傷つけるコンテンツを作る目的で顔交換を使わないでください。結果を公開する場合は、AI生成であることを明記してください。アップロードされた画像と結果は1時間以内にストレージから削除され、AIモデルの学習には使用しません。悪用はお問い合わせページから報告でき、48時間以内に対応します。
AIエージェントから使う
同じ顔交換は、Morfranの https://api.morfran.com/mcp にあるMCPサーバーでも利用できます。そのため、ClaudeなどのアシスタントがあなたのAPIキーで呼び出せます。設定方法はドキュメントのMCPセクションで説明しています。
よくある質問
顔交換APIの料金はいくらですか?
1人の顔交換は5クレジット、グループ顔交換(最大8人)は10クレジットです。新規アカウントには50クレジットが無料で付与されます。その後はクレジットパックを購入します。サブスクリプションはありません。パックについては料金をご覧ください。
顔交換にはどのくらい時間がかかりますか?
ほとんどの結果は、約60秒の同期待機時間内に返ってきます。時間のかかる処理やサーバーのタイムアウトが短い場合は、?async=true を使い、タスクIDで結果を取得してください。
画像をURLではなくbase64で送れますか?
ここでのサンプルは公開URLを使っており、これが最も簡単な方法です。OpenAPIスキーマには、このエンドポイントが受け付けるすべての入力フィールドが記載されています。
結果はどのくらい保存されますか?
アップロードされた画像と結果は1時間以内に削除されます。結果の画像は受け取ったらすぐに自分の側で保存してください。
コードを書かずに試せますか?
はい。ログインしてプレイグラウンドを開いてください。同じ顔交換をブラウザで実行し、対応するAPIリクエストを表示します。