AI 顔交換 API ワークフロー：許可済みアップロード、非同期ジョブ、確実な配信

交換前に参照写真と色を確認する。

SpicyAPI の Face Swap は、画像 2 枚（または画像 1 枚とクリップ 1 本）を受け取るだけで、プロンプトもマスクも要らない規制なしのエンドポイント群です。このガイドでは、どのエンドポイントを呼ぶべきか、まず Playground で試し、次にコードやエージェントから呼ぶ方法、出力で何を確認するか、プラットフォームが削除したあとも結果を残す方法を説明します。

作業に合うエンドポイントを選ぶ

まず $0.013 の Face Swap から試します。交換した顔が枠の残りより滑らか、または鮮明に見えるときは Pro へ移ります。2 枚の写真で肌色や光の色が明らかに違うときは Plus へ。200 個のアバター展開は Face Swap なら $2.60、Pro なら $32 です。いちばん難しいペアを両方でお試しください。Plus には効かない prompt フィールドがあるので省いてください。眼鏡や表情は対象写真に入れてください。

Video Face Swap は元のクリップを 10 秒単位のブロックで課金します。12 秒のクリップは 20 秒分（$0.52）として請求されます。40 秒のクリップは $1.04 です。送信時に 40 秒の見積額（$1.04）を確保し、タスク確定時に差額を解放します。送信前にブロックの境界で切ってください。

実際の顔でエンドポイントは何をするか

これらのエンドポイントは規制なしとして掲載されています。SpicyAPI がリクエストごとの顔スキャンや実在人物の確認を追加することはありません。失敗の多くは入力側の問題です（顔が検出できない、ファイルに到達できない）。ただし個々のモデルはリクエストを拒否することがあります。許容利用ポリシーは、他者へのなりすまし、本人の同意のない親密な用途や性的表現としての肖像の利用、未成年者の関与を禁じています。通報があれば SpicyAPI は保存した資産を削除し、アクセスを停止することがあります。公開写真や過去の関係も同意にはなりません。同意記録はあなたが保管するもので、アップロードボタンの前に置いてください。

• サインイン中のユーザーは、2 枚の画像とこの利用について対象者の許可を持っていることを確認します。確認はプロジェクトに一緒に保存します（誰、どの資産、どの用途、いつ）。
• 未成年者の画像は使いません。実在の人物になりすまして人を欺く用途も使いません。

これらは製品記録として残してください。プロンプト、分析イベント、ログには残しません。

失敗しない入力を用意する

強さを調整する設定はないので、結果が悪ければ別の入力ペアにしてください。

• 正面で大きく鮮明な顔。強いプロフィール、動きによるぼけ、密度の高い遮蔽（手、マスク、大きなサングラス）、ごく小さな顔は、転写の質を下げたりリクエストを失敗させたりします。大きく鮮明で正面の参照顔が最良の結果になります。
• 同じ光の方向。交換は対象のライティングを作り直しません。反対側から照らされた参照は顎のラインに継ぎ目として現れます。方向とおおよその肌色を合わせるか、別の参照顔を選んでください。Plus は肌色だけなら調和します。光の方向の不一致は直りません。
• 画像 1 枚につき 1 つの顔。集合写真では Face Swap と Video Face Swap が face_mapping を受け取ります。最大 10 エントリで、各エントリが参照顔と対象顔を対応づけ、0 から検出順に番号付けします。画像を変えるたびに番号を必ず確認し直してください。Plus と Pro は 1 つの顔を前提とするので、先に切り抜きます。

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

これは参照顔 0 を、対象で見つかった 2 番目の顔と交換します。1 つの顔だけを交換するなら、このフィールドは省略してください。

• ファイルへの直接リンク。画像 URL はログインなしでファイルに解決できる必要があります。動画では、クリップを再生するページはクリップではなく HTML を返し、その要求は失敗し、課金は返金されます。代わりにファイルをアップロードしてください。
• 役割は入れ替えられません。image_url は変更される画像です。reference_image_url は顔を提供します。両者を入れ替えても有効な要求で結果だけが変わり、エラーは返りません。逆向きの交換はモデルの不具合のように見えます。

動画の制限は、MP4 が 90 MB までで 3 秒から 40 秒、参照画像が JPG・PNG・WEBP で 10 MB までです。顔は枠の中で大きく保ち、長いあいだ横向きにしないでください。このエンドポイントは画面に 1 人だけがいるときが最もよく動きます。複数人のクリップでは face_mapping を追加するか（上と同じ形式、検出順に番号付け）、その人物に切り抜いてください。

まず Playground で試す

Face Swap のタスクページを開いて Playground タブ（設定、見積、実行）を使ってください。対象画像と参照の顔画像を登録し、設定に対する価格見積を確認してから実行します。コードを書く前に、いちばん難しいペアをここで試してください。Playground で間違える結果は API でも間違え、その直し方は別の入力ペアです。Head Swapにも頭部全体の交換用に同じタブがあります。

次にコードから呼び出す

Python SDK（pip install spicyapi）をインストールし、環境に SPICY_API_KEY を設定して実行します。

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

ジョブファイル 1 つにつき 1 つのプロセスを動かします。待ってタイムアウトしたら、同じファイルで再実行して保存済みのタスクを再開してください。送信自体が ID を返す前にタイムアウトした場合は、ファイルを保持して再試行の前にその要求を照合してください。冪等性の保護は永続ではありません。新しい支払いのある要求を意図するときだけ、新しいジョブファイル名を使ってください。

アップロード、待機、エラー、再試行は Subject Swap ガイドと Python SDK リファレンスにまとまっています。Video Face Swap は video_url と reference_image_url を取る spicyapi/face-swap-video-v1/video-edit を使います。

エージェントに作業を任せる

アシスタントに交換を任せたい場合は、CLI か MCP サーバーを渡します。どちらも価格を表示し、支払いのある呼び出しの前に確認を求めます。Skill はその上に指示を追加します。

• CLI. spicyapi はターミナルやスクリプトから 1 つのタスクを実行します（npx @spicyapi/cli はインストールなしで動きます）。

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json には上と同じ input オブジェクトを、spicy:// URI で入れます。このブロックは新しいジョブを開始します。表示されたキーとタスク ID は残してください。タイムアウトしたら、新しいキーのブロックをやり直すのではなく、そのタスクを再開します。

• MCP サーバー。MCP サーバーをアシスタントに追加して、それからこう尋ねます。"Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap."spicyapi_upload_file を呼び、次に spicyapi_task_create（価格確認で停止します）を呼び、次に spicyapi_task_wait を呼びます。

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill は Agent Skill をインストールします。これはコーディングアシスタントに、現在のスキーマを読み、冪等性キーを再利用し、推測ではなく結果を保存する方法を教えます。それ自体はタスクを実行できないので、CLI か MCP と一緒に使ってください。

同意記録と結果の自社ストレージへのコピーは、エージェントの呼び出しにも自分自身の呼び出しと同じように当てはまります。

完了とする前に確認する

succeeded は生成が終わったことを意味します。ダウンロード前に、資産に利用できる URL があり、pending も unavailable も真でないことを確認してください。pending が真の間、または URL がない間は、同じタスクを問い合わせ続けてください。配信の準備ができても、画像が承認されたことにはなりません。動画では、最初のフレームだけでなくカットや速い動きを確認してください。類似度スコアは診断の指標であって、同意や公開の承認ではありません。

このあと何をするかを変える確認が 2 つあります。

• 髪がデザインの一部である場合（ゲームキャラクター、マスコット）。Face Swap は対象の髪型を保つので、新しい顔は古い髪の下に来ます。代わりに Head Swap を使い、キャラクターシートの固定画像を参照にしてください。各出力をシートと比べます。安定した構図の上で顔がドリフトしていれば同一性の問題、逆なら構図の問題で、再試行で直せるのはどちらか一方です。
• 複数のレイアウトで 1 つのポートレートを使う場合。同じ参照と同じ seed で、レイアウトごとに 1 回ずつ Face Swap を実行します。公開する切り抜きのサイズでポートレートと照合して顔が認識でき、眼鏡と生え際がドリフトせず、余分な人が現れないなら出力を受け入れます。参照リビジョン、対象リビジョン、タスク ID をそれと一緒に残してください。

配信する：結果は自分でコピーする

アップロードされたソースは 1 日後に削除され、結果は最大 14 日後に削除されます（正確な時刻は retention.outputsExpireAt にあります）。結果はダウンロードして自分で保存してください。結果リンクは約 20 分しか続きません。保持ガイドも参照してください。

うまくいかないとき

FAQ

API は実在の人の顔を拒否しますか？

SpicyAPI はチェックしません。実在人物の確認もリクエストごとのスキャンもなく、失敗の多くは入力側の問題です。個々のモデルは拒否することがあり、許容利用ポリシーはなりすまし、同意のない親密な用途、未成年者を禁じています。許可の記録は自分で作ってください。

動画と画像を 1 回の呼び出しで送れますか？

Video Face Swap なら可能です。MP4 1 本と参照写真 1 枚です。1 本のクリップに複数人がいるときは、そこで face_mapping を使うか、頭部全体が必要な場合は 2 段階の Video Head Swap フローを使ってください。

ホスティング API とセルフホストのオープンソース交換はどちらですか？

ホスティング版のエンドポイントは画像あたり $0.013 で、GPU の用意とモデル保守から解放されます。セルフホストは画像ごとの料金を GPU と運用のコストに置き換えます。安くなるかは処理量と稼働率によります。量が安定して多いとこれらのコストをより多くの画像に分散できますが、同意と保持の管理は引き続き自分で維持する必要があります。

これは一般的な画像編集 API と同じですか？

違います。交換用のエンドポイントは画像 2 枚（または画像 1 枚とクリップ 1 本）を受け取り、プロンプトもマスクも要りません。どの要素が対象から残るかはエンドポイントごとに決まります。Face Swap は髪を残し、Head Swap は髪を置き換えます。同じ入力ペアでも審査の落ち方が違うので、まずエンドポイントを選んでください。

元のポートレートを出力と一緒に残すべきですか？

明確な理由があり、保持方針を公開している場合だけ残してください。SpicyAPI のアップロード済みソースは 1 日で削除されるので、各ポートレートの永続コピーではなく、参照と対象のリビジョン ID とタスク ID を系譜として残してください。

Webhook が必要ですか、それともポーリングで十分ですか？

ポーリングだけで動き、復旧経路にもなります。数秒ごとに読み取るか、短い画像交換では createTask に wait（最大 60 秒）を足してください。レイテンシーを下げるには Webhook を追加し、各イベントは 1 回だけ保存し、ポーリングは取りこぼしたコールバックの照合として扱います。

答えられるようにしておくこと

顔交換機能が信頼されるのは、チームが次の点に答えられるときです。誰の画像が使われたか、どのリビジョンが入力されたか、タスクが 1 回だけ受け付けられたか、なぜその結果が配信されたか、どう削除するか。同意記録、冪等性キー、自社ストレージ、確認のステップが、その答えを生みます。